dommy 0.6.0 → 0.8.0

data/lib/dommy/element.rb

@@ -8,8 +8,11 @@ module Dommy
   class Fragment
     include EventTarget
     include Node
+    include Internal::ParentNode
 
-    attr_reader :__node__, :document
+    attr_reader :document
+
+    def __dommy_backend_node__ = @__node__
 
     def initialize(document, nokogiri_node)
       @document = document
@@ -26,8 +29,12 @@ module Dommy
       @__node__.element_children.size
     end
 
+    # Live, cached childNodes so `fragment.childNodes === fragment.childNodes` and
+    # later mutations are reflected (WHATWG live NodeList).
     def child_nodes
-      NodeList.new(@__node__.children.map { |n| @document.wrap_node(n) }.compact)
+      @live_child_nodes ||= LiveNodeList.new do
+        @__node__.children.map { |n| @document.wrap_node(n) }.compact
+      end
     end
 
     def first_child
@@ -50,23 +57,18 @@ module Dommy
       @__node__.text
     end
 
-    def append_child(child)
-      nodes = detach_dom_nodes(child)
-      nodes.each { |n| @__node__.add_child(n) }
-      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
-      child
-    end
-
     def query_selector(selector)
-      return nil if selector.nil? || selector.to_s.empty?
+      return nil if selector.nil?
+      Internal.validate_selector!(selector)
 
-      @document.wrap_node(@__node__.at_css(selector.to_s))
+      @document.wrap_node(@__node__.at_css(Internal.backend_safe_selector(selector.to_s)))
     end
 
     def query_selector_all(selector)
-      return NodeList.new if selector.nil? || selector.to_s.empty?
+      return NodeList.new if selector.nil?
+      Internal.validate_selector!(selector)
 
-      NodeList.new(@__node__.css(selector.to_s).map { |n| @document.wrap_node(n) }.compact)
+      NodeList.new(@__node__.css(Internal.backend_safe_selector(selector.to_s)).map { |n| @document.wrap_node(n) }.compact)
     end
 
     def get_element_by_id(id)
@@ -79,6 +81,8 @@ module Dommy
       case key
       when "nodeType"
         11
+      when "nodeName"
+        "#document-fragment"
       when "children"
         element_children
       when "childNodes"
@@ -95,23 +99,69 @@ module Dommy
         last_element_child
       when "textContent"
         @__node__.text
+      when "ownerDocument"
+        @document
       end
     end
 
+    include Bridge::Methods
+    js_methods %w[cloneNode querySelector querySelectorAll getElementById appendChild isEqualNode hasChildNodes
+      append prepend replaceChildren removeChild insertBefore replaceChild
+      isSameNode getRootNode contains normalize compareDocumentPosition
+      lookupNamespaceURI lookupPrefix isDefaultNamespace
+      addEventListener removeEventListener dispatchEvent]
     def __js_call__(method, args)
       case method
+      when "hasChildNodes"
+        @__node__.children.any?
+      when "compareDocumentPosition"
+        compare_document_position(args[0])
+      when "lookupNamespaceURI"
+        lookup_namespace_uri(args[0])
+      when "lookupPrefix"
+        lookup_prefix(args[0])
+      when "isDefaultNamespace"
+        is_default_namespace(args[0])
       when "cloneNode"
         deep = args.empty? ? false : !!args[0]
         deep ? @document.wrap_node(Parser.fragment(@__node__.to_html, owner_doc: @document.nokogiri_doc)) : @document
           .wrap_node(Parser.fragment("", owner_doc: @document.nokogiri_doc))
       when "querySelector"
-        query_selector(args[0])
+        query_selector(Internal.css_query_arg!(args))
       when "querySelectorAll"
-        query_selector_all(args[0])
+        query_selector_all(Internal.css_query_arg!(args))
       when "getElementById"
         get_element_by_id(args[0])
       when "appendChild"
         append_child(args[0])
+      when "append"
+        append(*args)
+      when "prepend"
+        prepend(*args)
+      when "replaceChildren"
+        replace_children(*args)
+      when "removeChild"
+        remove_child(args[0])
+      when "insertBefore"
+        insert_before(args[0], args[1])
+      when "replaceChild"
+        replace_child(args[0], args[1])
+      when "isEqualNode"
+        is_equal_node(args[0])
+      when "isSameNode"
+        is_same_node(args[0])
+      when "getRootNode"
+        get_root_node(args[0])
+      when "contains"
+        contains?(args[0])
+      when "normalize"
+        normalize
+      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])
       else
         nil
       end
@@ -123,21 +173,50 @@ module Dommy
       nodes
     end
 
-    private
+    # Node mutation on the fragment's children (ParentNode covers append/prepend/
+    # replaceChildren; these are the remaining Node methods).
+    def remove_child(node)
+      bn = node.respond_to?(:__dommy_backend_node__) ? node.__dommy_backend_node__ : nil
+      raise DOMException::NotFoundError, "node is not a child of this fragment" unless bn && bn.parent == @__node__
 
-    def detach_dom_nodes(value)
-      case value
-      when String
-        [@document.create_text_node(value).__node__]
-      else
-        node = value.respond_to?(:__node__) ? value.__node__ : nil
-        return [] unless node
+      bn.unlink
+      node
+    end
 
-        node.unlink if node.parent
-        [node]
+    def insert_before(node, ref)
+      nodes = detach_dom_nodes(node)
+      ref_bn = ref.respond_to?(:__dommy_backend_node__) ? ref.__dommy_backend_node__ : nil
+      if ref_bn && ref_bn.parent == @__node__
+        nodes.each { |n| ref_bn.add_previous_sibling(n) }
+      else
+        nodes.each { |n| @__node__.add_child(n) }
       end
+      node
+    end
+
+    def replace_child(new_child, old_child)
+      old_bn = old_child.respond_to?(:__dommy_backend_node__) ? old_child.__dommy_backend_node__ : nil
+      raise DOMException::NotFoundError, "node is not a child of this fragment" unless old_bn && old_bn.parent == @__node__
+
+      detach_dom_nodes(new_child).each { |n| old_bn.add_previous_sibling(n) }
+      old_bn.unlink
+      old_child
+    end
+
+    def contains?(other)
+      return false unless other.respond_to?(:__dommy_backend_node__)
+
+      on = other.__dommy_backend_node__
+      on == @__node__ || on.ancestors.include?(@__node__)
+    end
+
+    def normalize
+      @__node__.children.each { |n| n.unlink if n.text? && n.content.empty? }
+      nil
     end
 
+    private
+
     def element_children
       @__node__.element_children.each_with_object([]) do |node, out|
         wrapped = @document.wrap_node(node)
@@ -147,7 +226,7 @@ module Dommy
 
     # Fragments aren't part of the bubble chain; nil terminates
     # bubbling at the boundary (shadow root, detached fragment, etc.).
-    def __event_parent__
+    def __internal_event_parent__
       nil
     end
   end
@@ -156,8 +235,29 @@ module Dommy
   # nodeValue / textContent API and `remove` / `cloneNode` semantics.
   class CharacterDataNode
     include Node
+    include EventTarget
+
+    def __dommy_backend_node__ = @__node__
+
+    # EventTarget needs a parent for event propagation; a character-data node
+    # bubbles to its parent element.
+    def __internal_event_parent__
+      @__node__.parent && @document.wrap_node(@__node__.parent)
+    end
 
-    attr_reader :__node__
+    # Text.splitText / CharacterData split: break the node at `offset`, keeping
+    # [0, offset) here and returning a new sibling node with the remainder.
+    def split_text(offset)
+      off = offset.to_i
+      full = @__node__.content
+      raise DOMException::IndexSizeError, "offset #{off} is out of bounds" if off.negative? || off > full.length
+
+      rest = full[off..] || ""
+      write_data(full[0, off])
+      new_node = @document.create_text_node(rest)
+      @__node__.add_next_sibling(new_node.__dommy_backend_node__) if @__node__.parent
+      new_node
+    end
 
     def initialize(document, nokogiri_node)
       @document = document
@@ -191,7 +291,7 @@ module Dommy
     end
 
     def remove
-      @__node__.unlink
+      @document.remove_node_with_notify(@__node__)
       nil
     end
 
@@ -215,22 +315,83 @@ module Dommy
       __js_set__(key.to_s, value)
     end
 
+    # WHATWG nodeName for character-data nodes is a per-type constant
+    # ("#text" / "#comment" / "#cdata-section"), not the element name.
+    def node_name
+      case node_type
+      when 3 then "#text"
+      when 4 then "#cdata-section"
+      when 8 then "#comment"
+      end
+    end
+
+    # CharacterData length / mutation methods. Offsets and counts are UTF-16 code
+    # units per spec; for BMP text (the common case) Ruby char indices match.
+    # Each mutating op routes through write_data, which fires the characterData
+    # MutationObserver record.
+
+    def length
+      @__node__.content.length
+    end
+
+    def substring_data(offset, count)
+      s = @__node__.content
+      raise DOMException::IndexSizeError, "offset out of bounds" if offset.to_i.negative? || offset.to_i > s.length
+
+      s[offset.to_i, [count.to_i, 0].max].to_s
+    end
+
+    def append_data(value)
+      write_data(@__node__.content + value.to_s)
+    end
+
+    def insert_data(offset, value)
+      replace_data(offset, 0, value)
+    end
+
+    def delete_data(offset, count)
+      replace_data(offset, count, "")
+    end
+
+    def replace_data(offset, count, value)
+      s = @__node__.content
+      o = offset.to_i
+      raise DOMException::IndexSizeError, "offset out of bounds" if o.negative? || o > s.length
+
+      c = [[count.to_i, 0].max, s.length - o].min
+      write_data(s[0, o].to_s + value.to_s + s[(o + c)..].to_s)
+    end
+
     def __js_get__(key)
       case key
       when "nodeType"
         node_type
+      when "nodeName"
+        node_name
       when "textContent"
         @__node__.content
       when "data"
         @__node__.content
       when "nodeValue"
         @__node__.content
+      when "length"
+        length
       when "parentNode"
         parent_node
+      when "ownerDocument"
+        @document
       when "nextSibling"
         next_sibling
       when "previousSibling"
         previous_sibling
+      when "childNodes"
+        # CharacterData is a leaf node: childNodes is always an empty (but
+        # present and iterable) NodeList, and firstChild/lastChild are null.
+        # DOM-walking code (e.g. idiomorph's morphChildren) iterates
+        # `node.childNodes` on every node, so a missing one crashes it.
+        NodeList.new
+      when "firstChild", "lastChild"
+        nil
       end
     end
 
@@ -243,16 +404,151 @@ module Dommy
       nil
     end
 
-    def __js_call__(method, _args)
+    include Bridge::Methods
+    js_methods %w[remove before after replaceWith isEqualNode hasChildNodes
+      appendData insertData deleteData replaceData substringData contains
+      isSameNode getRootNode normalize splitText compareDocumentPosition
+      lookupNamespaceURI lookupPrefix isDefaultNamespace
+      appendChild insertBefore removeChild replaceChild
+      addEventListener removeEventListener dispatchEvent]
+    def __js_call__(method, args)
       case method
+      when "hasChildNodes"
+        false
+      when "contains"
+        # A leaf node contains only itself (no descendants).
+        args[0].respond_to?(:__dommy_backend_node__) &&
+          args[0].__dommy_backend_node__ == @__node__
+      when "appendChild", "insertBefore"
+        # CharacterData is a leaf — it cannot be a parent.
+        raise DOMException::HierarchyRequestError, "this node type does not support children"
+      when "removeChild", "replaceChild"
+        raise DOMException::NotFoundError, "the node to be removed is not a child of this node"
+      when "compareDocumentPosition"
+        compare_document_position(args[0])
+      when "isSameNode"
+        is_same_node(args[0])
+      when "getRootNode"
+        get_root_node(args[0])
+      when "lookupNamespaceURI"
+        lookup_namespace_uri(args[0])
+      when "lookupPrefix"
+        lookup_prefix(args[0])
+      when "isDefaultNamespace"
+        is_default_namespace(args[0])
+      when "normalize"
+        nil # a leaf has no child text runs to merge
+      when "splitText"
+        split_text(args[0])
+      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])
+      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 "substringData"
+        substring_data(args[0], args[1])
       when "remove"
-        @__node__.unlink
-        nil
+        remove
+      when "before"
+        before(*args)
+      when "after"
+        after(*args)
+      when "replaceWith"
+        replace_with(*args)
+      when "isEqualNode"
+        is_equal_node(args[0])
+      end
+    end
+
+    # ChildNode mixin: WHATWG DOM defines `before`, `after`,
+    # `replaceWith` on all child nodes, including Text and Comment.
+    # Implementations operate on the Nokogiri layer and notify the
+    # MutationObserver with the underlying nodes (mirroring
+    # Element#remove_child / replace_child).
+
+    def before(*args)
+      parent = @__node__.parent
+      return nil unless parent
+
+      added = args.map { |arg| coerce_node(arg) }.compact
+      added.reverse_each { |node| @__node__.add_previous_sibling(node) }
+      notify_child_list_added(parent, added)
+      nil
+    end
+
+    def after(*args)
+      parent = @__node__.parent
+      return nil unless parent
+
+      added = args.map { |arg| coerce_node(arg) }.compact
+      anchor = @__node__.next_sibling
+      if anchor
+        added.reverse_each { |node| anchor.add_previous_sibling(node) }
+      else
+        added.each { |node| parent.add_child(node) }
+      end
+      notify_child_list_added(parent, added)
+      nil
+    end
+
+    def replace_with(*args)
+      parent = @__node__.parent
+      return nil unless parent
+
+      added = args.map { |arg| coerce_node(arg) }.compact
+      removed = @__node__
+      anchor = @__node__.next_sibling
+      @__node__.unlink
+      if anchor
+        added.reverse_each { |node| anchor.add_previous_sibling(node) }
+      else
+        added.each { |node| parent.add_child(node) }
       end
+      @document.notify_child_list_mutation(
+        target_node: parent,
+        added_nodes: added,
+        removed_nodes: [removed]
+      )
+      nil
     end
 
     private
 
+    # Coerce a `before` / `after` / `replaceWith` argument into a raw
+    # Nokogiri node, ready to be linked into a parent. Strings become
+    # fresh text nodes; existing nodes are detached from their current
+    # parent first (matching Element#detach_dom_nodes minus the
+    # Fragment branch which is rarely needed off a text/comment node).
+    def coerce_node(arg)
+      case arg
+      when String
+        @document.create_text_node(arg).__dommy_backend_node__
+      else
+        node = arg.respond_to?(:__dommy_backend_node__) ? arg.__dommy_backend_node__ : nil
+        node.unlink if node && node.parent
+        node
+      end
+    end
+
+    def notify_child_list_added(parent, added)
+      return if added.empty?
+
+      @document.notify_child_list_mutation(
+        target_node: parent,
+        added_nodes: added,
+        removed_nodes: []
+      )
+    end
+
     def write_data(value)
       old = @__node__.content
       @__node__.content = value.to_s
@@ -265,6 +561,8 @@ module Dommy
       3
     end
 
+    # Own __js_call__ methods, on top of CharacterDataNode's.
+    js_methods %w[cloneNode]
     def __js_call__(method, args)
       case method
       when "cloneNode"
@@ -275,11 +573,21 @@ module Dommy
     end
   end
 
+  # CDATASection — a Text subtype (nodeType 4). CharacterData methods and the
+  # "#cdata-section" nodeName come from CharacterDataNode via node_type.
+  class CDATASectionNode < TextNode
+    def node_type
+      4
+    end
+  end
+
   class CommentNode < CharacterDataNode
     def node_type
       8
     end
 
+    # Own __js_call__ methods, on top of CharacterDataNode's.
+    js_methods %w[cloneNode]
     def __js_call__(method, args)
       case method
       when "cloneNode"
@@ -296,8 +604,11 @@ module Dommy
   class ClassList
     include Enumerable
 
-    def initialize(element)
+    # `attribute` is the content attribute this token list reflects ("class" for
+    # `classList`, "rel" for `relList`, "sandbox", "sizes", "for", …).
+    def initialize(element, attribute = "class")
       @element = element
+      @attribute = attribute
     end
 
     def length
@@ -307,15 +618,18 @@ module Dommy
     alias size length
 
     def item(index)
-      class_tokens[index.to_i]
+      i = index.to_i
+      return nil if i.negative?
+
+      class_tokens[i]
     end
 
     def value
-      @element.__node__["class"].to_s
+      @element.__dommy_backend_node__[@attribute].to_s
     end
 
     def value=(new_value)
-      @element.set_attribute("class", new_value.to_s)
+      @element.set_attribute(@attribute, new_value.to_s)
     end
 
     # Spec: contains() does NOT validate (no SyntaxError on empty).
@@ -334,14 +648,22 @@ module Dommy
     end
 
     def replace(old_token, new_token)
-      old_s = validate_token(old_token)
-      new_s = validate_token(new_token)
+      # Spec order: both tokens' empty checks (SyntaxError) precede both
+      # whitespace checks (InvalidCharacterError) — so replace(" ", "") is a
+      # SyntaxError (the empty newToken), not an InvalidCharacterError.
+      old_s = stringify_token(old_token)
+      new_s = stringify_token(new_token)
+      raise DOMException::SyntaxError, "token is empty" if old_s.empty? || new_s.empty?
+      if old_s.match?(/[ \t\n\f\r]/) || new_s.match?(/[ \t\n\f\r]/)
+        raise DOMException::InvalidCharacterError, "token contains whitespace"
+      end
+
       tokens = class_tokens
       idx = tokens.index(old_s)
       return false unless idx
 
       tokens[idx] = new_s
-      @element.set_attribute("class", tokens.uniq.join(" "))
+      @element.set_attribute(@attribute, tokens.uniq.join(" "))
       true
     end
 
@@ -368,8 +690,14 @@ module Dommy
       when "value"
         value
       else
-        if key.is_a?(Integer) || key.to_s.match?(/\A\d+\z/)
-          item(key.to_i)
+        # Indexed getter: `classList[i]` is an undefined-returning indexed
+        # property — out-of-range or negative indices yield JS `undefined`
+        # (unlike `item(i)`, which returns null). Returning Ruby nil here would
+        # marshal as JS null, so use the UNDEFINED sentinel.
+        if key.is_a?(Integer) || key.to_s.match?(/\A-?\d+\z/)
+          i = key.to_i
+          token = i.negative? ? nil : class_tokens[i]
+          token.nil? ? Bridge::UNDEFINED : token
         end
       end
     end
@@ -383,22 +711,30 @@ module Dommy
       nil
     end
 
+    include Bridge::Methods
+    # NOTE: `supports` is intentionally absent — for the class attribute's token
+    # list it must throw a TypeError, which `list.supports(...)` (not a function)
+    # already does.
+    js_methods %w[add remove contains toggle replace item toString]
     def __js_call__(method, args)
       case method
       when "add"
         update_tokens { |tokens| tokens | normalize_tokens(args) }
-        nil
+        Bridge::UNDEFINED
       when "remove"
         update_tokens { |tokens| tokens - normalize_tokens(args) }
-        nil
+        Bridge::UNDEFINED
       when "contains"
-        class_tokens.include?(args[0].to_s)
+        # contains() does not validate; null coerces to the string "null".
+        class_tokens.include?(stringify_token(args[0]))
       when "toggle"
         toggle(args[0], args[1])
       when "replace"
         replace(args[0], args[1])
       when "item"
         item(args[0])
+      when "toString"
+        value
       else
         nil
       end
@@ -409,52 +745,63 @@ module Dommy
     def toggle(token, force)
       name = validate_token(token)
       present = class_tokens.include?(name)
-      if force.nil?
-        desired = !present
-      else
-        desired = !!force
-      end
+      force_given = !(force.nil? || force.equal?(Bridge::UNDEFINED))
+
+      # Spec: toggle runs the update steps only when it actually adds or removes.
+      # With an explicit force that already matches the current state it's a
+      # no-op — the attribute is left byte-for-byte untouched (no re-serialize).
+      if force_given
+        want = !!force
+        return want if want == present
 
-      update_tokens do |tokens|
-        desired ? (tokens | [name]) : (tokens - [name])
+        update_tokens { |tokens| want ? tokens | [name] : tokens - [name] }
+        return want
       end
 
+      desired = !present
+      update_tokens { |tokens| desired ? tokens | [name] : tokens - [name] }
       desired
     end
 
+    # USVString coercion of a token argument: JS `null` becomes the string
+    # "null" (so `add(null)` adds the token "null"), not the empty string.
+    def stringify_token(token)
+      token.nil? ? "null" : token.to_s
+    end
+
     # Spec: any empty-string argument throws SyntaxError; any token
     # containing ASCII whitespace throws InvalidCharacterError. Applies
     # to add / remove / replace / toggle.
     def normalize_tokens(args)
-      args.map do |t|
-        s = t.to_s
-        raise DOMException::SyntaxError, "token is empty" if s.empty?
-        raise DOMException::InvalidCharacterError, "token contains whitespace: #{s.inspect}" if s.match?(/\s/)
-
-        s
-      end
+      args.map { |t| validate_token(t) }
     end
 
     def validate_token(token)
-      s = token.to_s
+      s = stringify_token(token)
       raise DOMException::SyntaxError, "token is empty" if s.empty?
       raise DOMException::InvalidCharacterError, "token contains whitespace: #{s.inspect}" if s.match?(/\s/)
 
       s
     end
 
+    # The DOMTokenList token set: the class attribute parsed as an *ordered set*
+    # (whitespace-split, duplicates removed preserving first-seen order). length,
+    # item, iteration, and contains all operate on this set; `value`/`toString`
+    # return the raw attribute. ASCII whitespace per the spec is space/tab/LF/FF/CR.
     def class_tokens
-      raw = @element.__node__["class"].to_s
-      raw.split(/\s+/).reject(&:empty?)
+      raw = @element.__dommy_backend_node__[@attribute].to_s
+      raw.split(/[ \t\n\f\r]+/).reject(&:empty?).uniq
     end
 
+    # DOMTokenList "update steps": serialize the (deduplicated) token set back to
+    # the class attribute. add/remove/replace always run this, so duplicates
+    # collapse and whitespace normalizes even on a no-op token. The one carve-out
+    # (per spec) is an empty set with no existing attribute — don't create one.
     def update_tokens
       tokens = yield(class_tokens)
-      if tokens.empty?
-        @element.remove_attribute("class") if @element.__node__.key?("class")
-      else
-        @element.set_attribute("class", tokens.join(" "))
-      end
+      return if tokens.empty? && !@element.__dommy_backend_node__.key?(@attribute)
+
+      @element.set_attribute(@attribute, tokens.join(" "))
     end
   end
 
@@ -467,7 +814,7 @@ module Dommy
     end
 
     def __js_get__(key)
-      @element.__node__[attr_name(key)]
+      @element.__dommy_backend_node__[attr_name(key)]
     end
 
     def __js_set__(key, value)
@@ -475,10 +822,28 @@ module Dommy
       nil
     end
 
+    # Named deleter (`delete el.dataset.foo`): removes the data-* attribute.
+    def __js_delete__(key)
+      @element.remove_attribute(attr_name(key))
+      true
+    end
+
     def __js_call__(_method, _args)
       nil
     end
 
+    # WebIDL "supported property names" for DOMStringMap: each `data-*`
+    # attribute's name with the `data-` prefix stripped and `-x` sequences
+    # camel-cased (`data-date-of-birth` → `dateOfBirth`, `data-` → ``).
+    def __js_named_props__
+      Backend.attribute_nodes(@element.__dommy_backend_node__).filter_map do |a|
+        name = Backend.attribute_ns_info(a)[:qualified_name]
+        next unless name.start_with?("data-")
+
+        name.sub(/\Adata-/, "").gsub(/-([a-z])/) { ::Regexp.last_match(1).upcase }
+      end
+    end
+
     private
 
     def attr_name(key)
@@ -629,6 +994,8 @@ module Dommy
       nil
     end
 
+    include Bridge::Methods
+    js_methods %w[setProperty removeProperty getPropertyValue item]
     def __js_call__(method, args)
       case method
       when "setProperty"
@@ -674,7 +1041,7 @@ module Dommy
     end
 
     def properties
-      raw = @element.__node__["style"].to_s
+      raw = @element.__dommy_backend_node__["style"].to_s
       raw.split(";").each_with_object({}) do |entry, out|
         key, value = entry.split(":", 2)
         next unless key && value
@@ -685,7 +1052,7 @@ module Dommy
 
     def write_properties(props)
       if props.empty?
-        @element.remove_attribute("style") if @element.__node__.key?("style")
+        @element.remove_attribute("style") if @element.__dommy_backend_node__.key?("style")
       else
         @element.set_attribute("style", props.map { |k, v| "#{k}:#{v}" }.join(";"))
       end
@@ -695,8 +1062,11 @@ module Dommy
   class Element
     include EventTarget
     include Node
+    include Internal::ParentNode
 
-    attr_reader :__node__, :document
+    attr_reader :document
+
+    def __dommy_backend_node__ = @__node__
 
     def initialize(document, nokogiri_node)
       @document = document
@@ -712,6 +1082,11 @@ module Dommy
       @live_children = HTMLCollection.new do
         @__node__.element_children.map { |n| @document.wrap_node(n) }.compact
       end
+      # Live `childNodes` (all node types, not just elements), cached so
+      # `el.childNodes === el.childNodes` holds like the spec's live NodeList.
+      @live_child_nodes = LiveNodeList.new do
+        @__node__.children.map { |n| @document.wrap_node(n) }.compact
+      end
     end
 
     # ----- Public Ruby API (snake_case) -----
@@ -726,19 +1101,61 @@ module Dommy
     end
 
     def text_content=(value)
-      __js_set__("textContent", value)
+      # `node.content =` removes all existing children and (if value is
+      # non-empty) appends a single text node. Capture before/after to feed
+      # MutationObserver.
+      removed = @__node__.children.to_a
+      @__node__.content = value.to_s
+      added = @__node__.children.to_a
+      notify_child_list(added: added, removed: removed)
     end
 
     def inner_html
-      __js_get__("innerHTML")
+      if @__node__.name == "template"
+        @document.template_content_inner_html(self)
+      else
+        @__node__.inner_html
+      end
     end
 
     def inner_html=(value)
-      __js_set__("innerHTML", value)
+      removed = @__node__.children.to_a
+      if @__node__.name == "template"
+        # `<template>` content is invisible to outer selectors in real DOM (it
+        # lives in a separate DocumentFragment exposed via `[:content]`).
+        @document.attach_template_content(self, value.to_s)
+      else
+        @__node__.inner_html = value.to_s
+        @document.migrate_template_descendants(@__node__)
+      end
+      notify_child_list(added: @__node__.children.to_a, removed: removed)
+    end
+
+    HTML_NAMESPACE = "http://www.w3.org/1999/xhtml"
+
+    # Record the namespace/prefix/localName an element was created with via
+    # createElementNS, so the getters report them faithfully (Nokogiri can't
+    # always round-trip a foreign-namespace prefix).
+    def __internal_set_namespace__(namespace, prefix, local_name, qualified_name)
+      @__ns_uri = namespace
+      @__ns_prefix = prefix
+      @__ns_local = local_name
+      @__ns_qname = qualified_name
+      nil
     end
 
+    # tagName is the qualified name, ASCII-upper-cased only for an HTML-namespace
+    # element whose node document is an HTML document. An XHTML element (HTML
+    # namespace, but in an XML document) and any non-HTML-namespace element keep
+    # their case.
     def tag_name
-      @__node__.name.upcase
+      qname = @__ns_qname || @__node__.name
+      html_ns = @__ns_qname ? @__ns_uri == HTML_NAMESPACE : true
+      html_ns && @document.html_document? ? qname.upcase(:ascii) : qname
+    end
+
+    def element_prefix
+      @__ns_prefix
     end
 
     def id
@@ -761,6 +1178,33 @@ module Dommy
       @class_list
     end
 
+    # Element + namespace combinations for which a reflected DOMTokenList IDL
+    # attribute is defined; elsewhere the attribute does not exist (→ undefined).
+    REFLECTED_TOKEN_LIST_HOSTS = {
+      "relList" => {html: %w[a area link], svg: %w[a]},
+      "htmlFor" => {html: %w[output]},
+      "sandbox" => {html: %w[iframe]},
+      "sizes" => {html: %w[link]}
+    }.freeze
+
+    SVG_NAMESPACE = "http://www.w3.org/2000/svg"
+
+    # A reflected DOMTokenList for `prop` backed by content attribute
+    # `attribute`, cached for identity (`el.relList === el.relList`). Returns the
+    # UNDEFINED sentinel (→ JS `undefined`) when the attribute is not defined on
+    # this element in its namespace.
+    def reflected_token_list(prop, attribute)
+      hosts = REFLECTED_TOKEN_LIST_HOSTS[prop]
+      ns = namespace_uri
+      ln = local_name
+      applicable =
+        (ns == HTML_NAMESPACE && hosts[:html].include?(ln)) ||
+        (ns == SVG_NAMESPACE && Array(hosts[:svg]).include?(ln))
+      return Bridge::UNDEFINED unless applicable
+
+      (@reflected_token_lists ||= {})[prop] ||= ClassList.new(self, attribute)
+    end
+
     def style
       @style
     end
@@ -820,7 +1264,7 @@ module Dommy
     end
 
     def has_attributes?
-      @__node__.attribute_nodes.any?
+      Backend.attribute_nodes(@__node__).any?
     end
 
     def next_sibling
@@ -860,7 +1304,7 @@ module Dommy
       parent = @__node__.parent
       return unless parent
 
-      if parent.is_a?(Nokogiri::XML::Document)
+      if parent.is_a?(Backend.document_class)
         raise(
           DOMException::NoModificationAllowedError,
           "outerHTML setter not allowed on the document element"
@@ -878,15 +1322,15 @@ module Dommy
         new_nodes.each { |n| parent.add_child(n) }
       end
 
-      @document.notify_child_list_mutation(target_node: parent, added_nodes: new_nodes, removed_nodes: [removed])
+      notify_child_list(added: new_nodes, removed: [removed], target: parent)
     end
 
     # `el.contains(other)` — true if `other` is `el` itself or any
     # descendant. Per spec, returns false for null/non-Node.
     def contains?(other)
-      return false unless other.respond_to?(:__node__)
+      return false unless other.respond_to?(:__dommy_backend_node__)
 
-      other_node = other.__node__
+      other_node = other.__dommy_backend_node__
       return true if other_node == @__node__
 
       Internal::NodeTraversal.ancestor_of?(@__node__, other_node)
@@ -897,7 +1341,7 @@ module Dommy
     # inside a shadow tree, returns that ShadowRoot. Otherwise walks
     # until we hit the Nokogiri Document (then returns the Document).
     def root_node
-      sr = @document.__shadow_root_containing__(@__node__)
+      sr = @document.__internal_shadow_root_containing__(@__node__)
       return sr if sr
 
       current = @__node__
@@ -905,7 +1349,7 @@ module Dommy
       loop do
         parent = current.respond_to?(:parent) ? current.parent : nil
         break unless parent
-        if parent.is_a?(Nokogiri::XML::Document)
+        if parent.is_a?(Backend.document_class)
           attached = true
           break
         end
@@ -938,6 +1382,8 @@ module Dommy
     end
 
     def toggle_attribute(name, force = nil)
+      raise DOMException::InvalidCharacterError, "empty attribute name" if name.to_s.empty?
+
       key = name.to_s.downcase
       present = @__node__.key?(key)
       desired = force.nil? ? !present : !!force
@@ -951,10 +1397,11 @@ module Dommy
     end
 
     def matches?(selector)
-      return false if selector.nil? || selector.to_s.empty?
+      return false if selector.nil?
+      Internal.validate_selector!(selector)
 
       # `:scope` pseudo — match against this element itself.
-      sel = selector.to_s.gsub(":scope", "*:nth-last-child(n)")
+      sel = Internal.backend_safe_selector(selector.to_s).gsub(":scope", "*:nth-last-child(n)")
       matches_selector?(@__node__, sel)
     end
 
@@ -981,6 +1428,10 @@ module Dommy
       end
     end
 
+    def get_elements_by_tag_name_ns(namespace, local_name)
+      HTMLCollection.elements_by_tag_name_ns(@__node__, @document, namespace, local_name)
+    end
+
     # NamedNodeMap of attributes. Lazily allocated and re-used so
     # `el.attributes === el.attributes` and `attr.ownerElement === el`.
     def attributes
@@ -1003,11 +1454,15 @@ module Dommy
 
     # HTML namespace constants — most HTML elements live in xhtml ns.
     def namespace_uri
-      ns = @__node__.namespace
-      ns ? ns.href : "http://www.w3.org/1999/xhtml"
+      return @__ns_uri if @__ns_qname
+
+      ns = Backend.namespace_of(@__node__)
+      ns ? ns.href : HTML_NAMESPACE
     end
 
     def local_name
+      return @__ns_local if @__ns_qname
+
       @__node__.name.downcase
     end
 
@@ -1054,14 +1509,14 @@ module Dommy
 
         parent = current.respond_to?(:parent) ? current.parent : nil
         return false unless parent
-        return true if parent.is_a?(Nokogiri::XML::Document)
+        return true if parent.is_a?(Backend.document_class)
 
-        sr = @document.__shadow_root_for_fragment__(parent)
+        sr = @document.__internal_shadow_root_for_fragment__(parent)
         if sr
           host = sr.host
           return false unless host
 
-          current = host.__node__
+          current = host.__dommy_backend_node__
         else
           current = parent
         end
@@ -1074,12 +1529,12 @@ module Dommy
     # tests rely on `document.activeElement` updating. Track the most
     # recently focused element on the document.
     def focus
-      @document.__set_active_element__(self)
+      @document.__internal_set_active_element__(self)
       nil
     end
 
     def blur
-      @document.__set_active_element__(nil)
+      @document.__internal_set_active_element__(nil)
       nil
     end
 
@@ -1149,7 +1604,7 @@ module Dommy
 
     # Internal — gives access to the shadow root regardless of mode.
     # Used by event composition / `composedPath()`.
-    def __shadow_root__
+    def __internal_shadow_root__
       @__shadow_root
     end
 
@@ -1157,7 +1612,7 @@ module Dommy
     # "beforebegin", "afterbegin", "beforeend", "afterend". Returns the
     # inserted element or nil if position has no anchor (root cases).
     def insert_adjacent_element(position, element)
-      return nil unless element.respond_to?(:__node__)
+      return nil unless element.respond_to?(:__dommy_backend_node__)
 
       case position.to_s
       when "beforebegin"
@@ -1165,22 +1620,22 @@ module Dommy
 
         node = detach_for_insert(element)
         @__node__.add_previous_sibling(node)
-        @document.notify_child_list_mutation(target_node: @__node__.parent, added_nodes: [node], removed_nodes: [])
+        notify_child_list(added: [node], target: @__node__.parent)
       when "afterbegin"
         node = detach_for_insert(element)
         first = @__node__.children.first
         first ? first.add_previous_sibling(node) : @__node__.add_child(node)
-        @document.notify_child_list_mutation(target_node: @__node__, added_nodes: [node], removed_nodes: [])
+        notify_child_list(added: [node])
       when "beforeend"
         node = detach_for_insert(element)
         @__node__.add_child(node)
-        @document.notify_child_list_mutation(target_node: @__node__, added_nodes: [node], removed_nodes: [])
+        notify_child_list(added: [node])
       when "afterend"
         return nil unless @__node__.parent
 
         node = detach_for_insert(element)
         @__node__.add_next_sibling(node)
-        @document.notify_child_list_mutation(target_node: @__node__.parent, added_nodes: [node], removed_nodes: [])
+        notify_child_list(added: [node], target: @__node__.parent)
       else
         return nil
       end
@@ -1189,36 +1644,56 @@ module Dommy
     end
 
     def insert_adjacent_html(position, html)
+      # Position is ASCII case-insensitive ("beforeBegin" == "beforebegin").
+      pos = position.to_s.downcase
+      unless %w[beforebegin afterbegin beforeend afterend].include?(pos)
+        raise DOMException::SyntaxError, "The value provided ('#{position}') is not one of 'beforeBegin', 'afterBegin', 'beforeEnd', or 'afterEnd'."
+      end
+
       fragment = Parser.fragment(html.to_s, owner_doc: @__node__.document)
       nodes = fragment.children.to_a
-      case position.to_s
+      # `add_previous_sibling` inserts immediately before the anchor, so a forward
+      # walk preserves document order; `add_next_sibling` inserts immediately
+      # after, so afterend walks in reverse to keep order.
+      case pos
       when "beforebegin"
-        return nil unless @__node__.parent
-
-        nodes.reverse_each { |n| @__node__.add_previous_sibling(n) }
-        @document.notify_child_list_mutation(target_node: @__node__.parent, added_nodes: nodes, removed_nodes: [])
+        parent = insertion_parent!
+        nodes.each { |n| @__node__.add_previous_sibling(n) }
+        notify_child_list(added: nodes, target: parent)
       when "afterbegin"
         first = @__node__.children.first
         if first
-          nodes.reverse_each { |n| first.add_previous_sibling(n) }
+          nodes.each { |n| first.add_previous_sibling(n) }
         else
           nodes.each { |n| @__node__.add_child(n) }
         end
 
-        @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
+        notify_child_list(added: nodes)
       when "beforeend"
         nodes.each { |n| @__node__.add_child(n) }
-        @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
+        notify_child_list(added: nodes)
       when "afterend"
-        return nil unless @__node__.parent
-
+        parent = insertion_parent!
         nodes.reverse_each { |n| @__node__.add_next_sibling(n) }
-        @document.notify_child_list_mutation(target_node: @__node__.parent, added_nodes: nodes, removed_nodes: [])
+        notify_child_list(added: nodes, target: parent)
       end
 
       nil
     end
 
+    # The parent that a beforebegin/afterend insertion targets. Per the spec, if
+    # the element has no parent, or its parent is the Document, there is nowhere
+    # to insert a sibling — throw NoModificationAllowedError.
+    def insertion_parent!
+      parent = @__node__.parent
+      is_document = parent && ((parent.respond_to?(:document?) && parent.document?) || parent.name == "document")
+      if parent.nil? || is_document
+        raise DOMException::NoModificationAllowedError, "The element has no parent."
+      end
+
+      parent
+    end
+
     def insert_adjacent_text(position, text)
       return nil if text.to_s.empty?
 
@@ -1254,48 +1729,7 @@ module Dommy
     # CONTAINS/CONTAINED_BY bitmask for ancestor/descendant pairs, or
     # PRECEDING/FOLLOWING for siblings (and DISCONNECTED for unrelated
     # nodes).
-    def compare_document_position(other)
-      return 0 if equal?(other)
-      return DOCUMENT_POSITION_DISCONNECTED unless other.respond_to?(:__node__)
-
-      self_node = @__node__
-      other_node = other.__node__
-
-      self_ancestors = ancestor_chain(self_node)
-      other_ancestors = ancestor_chain(other_node)
-
-      common = nil
-      self_ancestors.each do |a|
-        if other_ancestors.include?(a)
-          common = a
-          break
-        end
-      end
-
-      unless common
-        return DOCUMENT_POSITION_DISCONNECTED | DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC | DOCUMENT_POSITION_PRECEDING
-      end
-
-      if common == self_node
-        return DOCUMENT_POSITION_CONTAINED_BY | DOCUMENT_POSITION_FOLLOWING
-      elsif common == other_node
-        return DOCUMENT_POSITION_CONTAINS | DOCUMENT_POSITION_PRECEDING
-      end
-
-      # Sibling-of-some-level case: compare the two branch points
-      # under the common ancestor.
-      self_branch = branch_under(common, self_ancestors)
-      other_branch = branch_under(common, other_ancestors)
-      common.children.each do |child|
-        if child == self_branch
-          return DOCUMENT_POSITION_FOLLOWING
-        elsif child == other_branch
-          return DOCUMENT_POSITION_PRECEDING
-        end
-      end
-
-      DOCUMENT_POSITION_DISCONNECTED
-    end
+    # compareDocumentPosition is provided generically by the Node module.
 
     # `Node.isSameNode(other)` — strict reference identity. The DOM
     # spec deprecates this in favor of `===`, but linkedom-style
@@ -1309,62 +1743,19 @@ module Dommy
     # suite and standard DOM Node.isEqualNode.
     def equal_node?(other)
       return false unless other.is_a?(Element)
-      return false unless @__node__.name == other.__node__.name
+      return false unless @__node__.name == other.__dommy_backend_node__.name
       return false unless attribute_signature == other.send(:attribute_signature)
-      return false unless @__node__.children.size == other.__node__.children.size
+      return false unless @__node__.children.size == other.__dommy_backend_node__.children.size
 
-      @__node__.children.zip(other.__node__.children).all? do |a, b|
+      @__node__.children.zip(other.__dommy_backend_node__.children).all? do |a, b|
         wa = @document.wrap_node(a)
         wb = @document.wrap_node(b)
         wa.respond_to?(:equal_node?) ? wa.equal_node?(wb) : a.content == b.content
       end
     end
 
-    private
-
-    def ancestor_chain(node)
-      chain = [node]
-      Internal::NodeTraversal.each_ancestor(node) { |n| chain << n }
-      chain
-    end
-
-    def branch_under(common, chain)
-      # Walk back along `chain` to find the entry whose parent is `common`.
-      chain.each_with_index do |node, i|
-        return node if i.zero? && node == common
-        return node if node.respond_to?(:parent) && node.parent == common
-      end
-
-      nil
-    end
-
-    def attribute_signature
-      @__node__.attribute_nodes.map { |a| [a.name, a.value] }.sort
-    end
-
-    public
-
     def remove
-      __js_call__("remove", [])
-    end
-
-    # ParentNode mixin methods — append / prepend / replaceChildren
-    # take a mix of Node and String args (strings become text nodes).
-
-    def append(*args)
-      append_nodes(args)
-    end
-
-    def prepend(*args)
-      prepend_nodes(args)
-    end
-
-    def replace_children(*args)
-      removed = @__node__.children.to_a
-      removed.each(&:unlink)
-      nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
-      nodes.each { |n| @__node__.add_child(n) }
-      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: removed)
+      @document.remove_node_with_notify(@__node__)
       nil
     end
 
@@ -1394,25 +1785,61 @@ module Dommy
     end
 
     def click
-      __js_call__("click", [])
+      dispatch_event(MouseEvent.new("click", "bubbles" => true, "cancelable" => true, "button" => 0))
     end
 
-    # Ruby block-style listener (in addition to the (type, callable,
-    # options) form inherited from EventTarget). Returns the resolved
-    # listener so callers can pass it back to remove_event_listener.
-    def on(type, &block)
-      add_event_listener(type, block)
-      block
+    def get_attribute_names
+      Backend.attribute_nodes(@__node__).map(&:name)
     end
 
-    # `el[:foo]` / `el[:foo] = ...` bracket shortcut for the JS-style
-    # property access pattern. Useful when porting browser-side code
-    # to CRuby tests.
-    def [](key)
-      __js_get__(key.to_s)
+    # No layout engine — geometry getters return zeroed rects.
+    def get_bounding_client_rect
+      DOMRect.new
     end
 
-    def []=(key, value)
+    def get_client_rects
+      []
+    end
+
+    def request_fullscreen
+      @document.__internal_set_fullscreen_element__(self)
+      PromiseValue.resolve(@document.default_view, nil)
+    end
+
+    # Popover API — show / hide / toggle fire beforetoggle + toggle events
+    # (no real visual change). Return values mirror the IDL.
+    def show_popover
+      toggle_popover_state(true)
+      nil
+    end
+
+    def hide_popover
+      toggle_popover_state(false)
+      nil
+    end
+
+    def toggle_popover
+      new_state = !@__popover_open__
+      toggle_popover_state(new_state)
+      new_state
+    end
+
+    # Ruby block-style listener (in addition to the (type, callable,
+    # options) form inherited from EventTarget). Returns the resolved
+    # listener so callers can pass it back to remove_event_listener.
+    def on(type, &block)
+      add_event_listener(type, block)
+      block
+    end
+
+    # `el[:foo]` / `el[:foo] = ...` bracket shortcut for the JS-style
+    # property access pattern. Useful when porting browser-side code
+    # to CRuby tests.
+    def [](key)
+      __js_get__(key.to_s)
+    end
+
+    def []=(key, value)
       __js_set__(key.to_s, value)
     end
 
@@ -1444,8 +1871,26 @@ module Dommy
         get_attribute("popover")
       when "children"
         @live_children
+      when "childNodes"
+        @live_child_nodes
+      when "firstChild"
+        first_child
+      when "lastChild"
+        last_child
+      when "childElementCount"
+        child_element_count
+      when "lastElementChild"
+        last_element_child
+      when "nextSibling"
+        next_sibling
+      when "previousSibling"
+        previous_sibling
+      when "nextElementSibling"
+        next_element_sibling
+      when "previousElementSibling"
+        previous_element_sibling
       when "firstElementChild"
-        @document.wrap_node(@__node__.element_children.first)
+        first_element_child
       when "parentElement", "parent"
         wrap_parent(@__node__.parent)
       when "parentNode"
@@ -1456,16 +1901,23 @@ module Dommy
       when "textContent"
         @__node__.text
       when "innerHTML"
-        if @__node__.name == "template"
-          @document.template_content_inner_html(self)
-        else
-          @__node__.inner_html
-        end
-
+        inner_html
+      when "outerHTML"
+        outer_html
       when "tagName"
-        @__node__.name.upcase
+        tag_name
+      when "prefix"
+        element_prefix
       when "classList"
         @class_list
+      when "relList"
+        reflected_token_list("relList", "rel")
+      when "htmlFor"
+        reflected_token_list("htmlFor", "for")
+      when "sandbox"
+        reflected_token_list("sandbox", "sandbox")
+      when "sizes"
+        reflected_token_list("sizes", "sizes")
       when "style"
         @style
       when "dataset"
@@ -1497,11 +1949,13 @@ module Dommy
       when "localName"
         local_name
       when "nodeName"
-        @__node__.name.upcase
+        tag_name
       when "slot"
         slot
       when "role"
-        role
+        aria_get("role")
+      when "accessKeyLabel"
+        access_key_label
       when "baseURI"
         base_uri
       when "shadowRoot"
@@ -1509,9 +1963,20 @@ module Dommy
       when "ownerDocument"
         @document
       else
-        # `el.onXxx` event handler property — returns the registered
-        # callback (if any), or nil.
-        if key.start_with?("on") && key.length > 2
+        if (elements_attr = aria_elements_attr(key))
+          # Plural ARIA element references (`ariaDescribedByElements` ↔
+          # `aria-describedby`) — a list of Elements.
+          aria_elements_get(elements_attr, key)
+        elsif (element_attr = aria_element_attr(key))
+          # ARIA element-reference IDL attribute (`ariaActiveDescendantElement`
+          # ↔ `aria-activedescendant`) — resolves to an Element or null.
+          aria_element_get(element_attr, key)
+        elsif (content_attr = aria_content_attr(key))
+          # ARIA / role reflected IDL attribute (`ariaLabel` ↔ `aria-label`,
+          # `role` ↔ `role`) — a nullable DOMString (null when absent).
+          aria_get(content_attr)
+        elsif key.start_with?("on") && key.length > 2
+          # `el.onXxx` event handler property — the registered callback or nil.
           @on_handlers&.[](event_name_from_on(key))
         end
       end
@@ -1531,6 +1996,143 @@ module Dommy
       raw.to_s
     end
 
+    # `accessKeyLabel` — the assigned access key's platform label. The
+    # `accesskey` content attribute is a set of one-code-point candidates; a
+    # single valid candidate yields a (modifier-prefixed) label, anything else
+    # (empty, or multiple/multi-char tokens) yields the empty string. The exact
+    # modifier varies by platform — tests only assert non-empty vs empty.
+    def access_key_label
+      keys = @__node__["accesskey"].to_s.split(/[ \t\n\f\r]+/).reject(&:empty?)
+      return "" unless keys.length == 1 && keys.first.length == 1
+
+      "Alt+#{keys.first.upcase}"
+    end
+
+    # The content attribute an ARIA element-reference IDL attribute reflects
+    # (`ariaActiveDescendantElement` → "aria-activedescendant",
+    # `ariaErrorMessageElement` → "aria-errormessage"), or nil. The IDL name is
+    # `aria<Xxx>Element`; the content attribute is "aria-" + <Xxx> lowercased.
+    def aria_element_attr(key)
+      return nil unless key.is_a?(String) && key.start_with?("aria") && key.end_with?("Element")
+      return nil unless key.length > 11 && key[4] =~ /[A-Z]/
+
+      "aria-#{key[4...-7].downcase}"
+    end
+
+    # Read an ARIA element reference: an explicitly-set Element wins; otherwise
+    # the content attribute is resolved as an IDREF (the element with that id in
+    # this element's tree), or null.
+    def aria_element_get(content_attr, key)
+      explicit = (@aria_element_refs ||= {})[key]
+      return explicit if explicit
+
+      idref = @__node__[content_attr].to_s
+      return nil if idref.empty?
+
+      aria_find_in_root(idref)
+    end
+
+    # Set an ARIA element reference: null/undefined clears it and removes the
+    # content attribute; an Element stores the explicit reference and sets the
+    # content attribute to the empty string (per the reflection spec).
+    def aria_element_set(content_attr, key, value)
+      refs = (@aria_element_refs ||= {})
+      if value.nil? || (defined?(Bridge::UNDEFINED) && value.equal?(Bridge::UNDEFINED))
+        refs.delete(key)
+        remove_attribute(content_attr) if @__node__.key?(content_attr)
+      else
+        # set_attribute clears explicit refs via its aria-* hook, so store the
+        # new reference afterward.
+        set_attribute(content_attr, "")
+        refs[key] = value
+      end
+      nil
+    end
+
+    # The content attribute a plural ARIA element-references IDL attribute
+    # reflects (`ariaDescribedByElements` → "aria-describedby",
+    # `ariaLabelledByElements` → "aria-labelledby"), or nil. The IDL name is
+    # `aria<Xxx>Elements`; the content attribute is "aria-" + <Xxx> lowercased.
+    def aria_elements_attr(key)
+      return nil unless key.is_a?(String) && key.start_with?("aria") && key.end_with?("Elements")
+      return nil unless key.length > 12 && key[4] =~ /[A-Z]/
+
+      "aria-#{key[4...-8].downcase}"
+    end
+
+    # Read a plural ARIA element references value (a list of Elements): the
+    # explicitly-set array wins; otherwise the content attribute is split as a
+    # space-separated IDREF list and each resolved (missing ids dropped).
+    def aria_elements_get(content_attr, key)
+      explicit = (@aria_elements_refs ||= {})[key]
+      return explicit.dup if explicit
+
+      @__node__[content_attr].to_s.split(/[ \t\n\f\r]+/).reject(&:empty?).filter_map do |id|
+        aria_find_in_root(id)
+      end
+    end
+
+    # Resolve an ARIA IDREF within this element's tree ROOT (its topmost
+    # ancestor) rather than the document — so references keep working when the
+    # subtree is disconnected from the document.
+    def aria_find_in_root(id)
+      root = @__node__
+      root = root.parent while root.parent && !root.parent.is_a?(Backend.document_class)
+      node = ([root] + root.css("*").to_a).find { |n| n["id"].to_s == id }
+      node && @document.wrap_node(node)
+    end
+
+    # Set a plural ARIA element references value: null/undefined clears it and
+    # removes the content attribute; an array of Elements is stored and the
+    # content attribute is set to the empty string.
+    def aria_elements_set(content_attr, key, value)
+      refs = (@aria_elements_refs ||= {})
+      if value.nil? || (defined?(Bridge::UNDEFINED) && value.equal?(Bridge::UNDEFINED))
+        refs.delete(key)
+        remove_attribute(content_attr) if @__node__.key?(content_attr)
+      else
+        set_attribute(content_attr, "")
+        refs[key] = Array(value)
+      end
+      nil
+    end
+
+    # Drop any explicit ARIA element reference (singular or plural) whose content
+    # attribute was just set directly (so the IDL getter re-resolves the IDREF).
+    def clear_aria_element_ref_for(content_attr)
+      @aria_element_refs&.delete_if { |key, _| aria_element_attr(key) == content_attr }
+      @aria_elements_refs&.delete_if { |key, _| aria_elements_attr(key) == content_attr }
+    end
+
+    # The content attribute a role/ARIA IDL attribute reflects, or nil for a
+    # non-ARIA key. `role` → "role"; `ariaXxx` → "aria-" + the rest, lowercased
+    # with humps removed (`ariaAutoComplete` → "aria-autocomplete",
+    # `ariaColIndexText` → "aria-colindextext").
+    def aria_content_attr(key)
+      return "role" if key == "role"
+      return nil unless key.is_a?(String) && key.length > 4 && key.start_with?("aria")
+      return nil unless key[4] =~ /[A-Z]/
+
+      "aria-#{key[4..].downcase}"
+    end
+
+    # Read a reflected nullable DOMString: the content attribute value, or nil
+    # (→ JS null) when the attribute is absent.
+    def aria_get(content_attr)
+      @__node__.key?(content_attr) ? @__node__[content_attr].to_s : nil
+    end
+
+    # Write a reflected nullable DOMString: null / undefined removes the content
+    # attribute; any other value is ToString-coerced and set.
+    def aria_set(content_attr, value)
+      if value.nil? || (defined?(Bridge::UNDEFINED) && value.equal?(Bridge::UNDEFINED))
+        remove_attribute(content_attr) if @__node__.key?(content_attr)
+      else
+        set_attribute(content_attr, value.to_s)
+      end
+      nil
+    end
+
     # Map a JS boolean property name to its underlying HTML attribute.
     # HTML attribute names are lowercase; the DOM property may be
     # camelCase (`readOnly` → `readonly`).
@@ -1541,25 +2143,12 @@ module Dommy
     def __js_set__(key, value)
       case key
       when "textContent"
-        @__node__.content = value.to_s
+        self.text_content = value
       when "innerHTML"
-        removed = @__node__.children.to_a
-        if @__node__.name == "template"
-          # `<template>` content is invisible to outer selectors in
-          # real DOM (it lives in a separate DocumentFragment exposed
-          # via `[:content]`). Mirror that here so child placeholders
-          # inside the template don't pollute outer queries.
-          @document.attach_template_content(self, value.to_s)
-        else
-          @__node__.inner_html = value.to_s
-          @document.migrate_template_descendants(@__node__)
-        end
-
-        @document.notify_child_list_mutation(
-          target_node: @__node__,
-          added_nodes: @__node__.children.to_a,
-          removed_nodes: removed
-        )
+        self.inner_html = value
+      when "outerHTML"
+        # [CEReactions, LegacyNullToEmptyString] DOMString — null becomes "".
+        self.outer_html = value.nil? ? "" : value.to_s
       when "hidden", "disabled", "checked", "readOnly", "multiple", "required"
         # Boolean reflected property — funnel through set_attribute /
         # remove_attribute so MutationObserver attribute records fire.
@@ -1572,6 +2161,13 @@ module Dommy
 
       when "className"
         set_attribute("class", value.to_s)
+      when "classList"
+        # WHATWG [PutForwards=value]: `el.classList = x` forwards to
+        # `el.classList.value = x` (set the class attribute). Handling it here
+        # (instead of letting the write fall through as unhandled) stops the JS
+        # bridge from stashing a string expando that would shadow the classList
+        # getter for the rest of the element's life.
+        set_attribute("class", value.to_s)
       when "id"
         set_attribute("id", value.to_s)
       when "value"
@@ -1579,40 +2175,48 @@ module Dommy
       when "slot"
         set_attribute("slot", value.to_s)
       when "role"
-        set_attribute("role", value.to_s)
+        aria_set("role", value)
       else
-        # `el.onXxx = fn` registers fn as a single named handler.
-        # Setting to nil removes it. Mirrors HTMLElement IDL.
-        if key.start_with?("on") && key.length > 2
+        if (elements_attr = aria_elements_attr(key))
+          # Plural ARIA element references setter (list of Elements).
+          aria_elements_set(elements_attr, key, value)
+        elsif (element_attr = aria_element_attr(key))
+          # ARIA element-reference IDL attribute setter.
+          aria_element_set(element_attr, key, value)
+        elsif (content_attr = aria_content_attr(key))
+          # ARIA / role reflected nullable DOMString (null/undefined → remove).
+          aria_set(content_attr, value)
+        elsif key.start_with?("on") && key.length > 2
+          # `el.onXxx = fn` registers fn as a single named handler; nil removes.
           set_on_handler(event_name_from_on(key), value)
         else
-          nil
+          # Not a known DOM property — tell the JS host to keep it as a
+          # JS-side expando (so object/instance fields keep their identity).
+          Bridge::UNHANDLED
         end
       end
     end
 
-    private
-
-    def event_name_from_on(key)
-      key.to_s.sub(/\Aon/, "").downcase
-    end
-
-    def set_on_handler(event_name, value)
-      @on_handlers ||= {}
-      previous = @on_handlers[event_name]
-      remove_event_listener(event_name, previous) if previous
-      if value
-        add_event_listener(event_name, value)
-        @on_handlers[event_name] = value
-      else
-        @on_handlers.delete(event_name)
-      end
-    end
-
-    public
-
+    include Bridge::Methods
+    js_methods %w[
+      getAttribute setAttribute hasAttribute removeAttribute getAttributeNames closest
+      getAttributeNS setAttributeNS hasAttributeNS removeAttributeNS getAttributeNodeNS setAttributeNodeNS
+      querySelector querySelectorAll getElementsByClassName getElementsByTagName getElementsByTagNameNS
+      insertAdjacentElement insertAdjacentHTML insertAdjacentText toggleAttribute matches
+      toString getAttributeNode setAttributeNode removeAttributeNode focus blur attachShadow
+      addEventListener removeEventListener dispatchEvent appendChild insertBefore removeChild
+      replaceChild cloneNode append prepend replaceChildren before after getInnerHTML getHTML
+      remove replaceWith click getBoundingClientRect getClientRects scrollIntoView scroll
+      scrollTo scrollBy requestFullscreen showPopover hidePopover togglePopover isEqualNode
+      hasChildNodes hasAttributes getRootNode normalize contains
+      compareDocumentPosition isSameNode lookupNamespaceURI lookupPrefix isDefaultNamespace
+    ]
     def __js_call__(method, args)
       case method
+      when "hasChildNodes"
+        has_child_nodes?
+      when "hasAttributes"
+        has_attributes?
       when "getAttribute"
         get_attribute(args[0])
       when "setAttribute"
@@ -1621,18 +2225,38 @@ module Dommy
         has_attribute?(args[0])
       when "removeAttribute"
         remove_attribute(args[0])
+      when "getAttributeNS"
+        get_attribute_ns(args[0], args[1])
+      when "setAttributeNS"
+        set_attribute_ns(args[0], args[1], args[2])
+      when "hasAttributeNS"
+        has_attribute_ns?(args[0], args[1])
+      when "removeAttributeNS"
+        remove_attribute_ns(args[0], args[1])
+      when "getAttributeNodeNS"
+        get_attribute_node_ns(args[0], args[1])
+      when "setAttributeNodeNS"
+        set_attribute_node(args[0])
       when "getAttributeNames"
-        @__node__.attribute_nodes.map(&:name)
+        get_attribute_names
       when "closest"
+        raise Bridge::TypeError, "1 argument required, but only 0 present" if args.empty?
+
         closest(args[0])
       when "querySelector"
-        query_selector(args[0])
+        query_selector(Internal.css_query_arg!(args))
       when "querySelectorAll"
-        query_selector_all(args[0])
+        query_selector_all(Internal.css_query_arg!(args))
       when "getElementsByClassName"
         get_elements_by_class_name(args[0])
+      when "getElementsByTagNameNS"
+        get_elements_by_tag_name_ns(args[0], args[1])
       when "getElementsByTagName"
         get_elements_by_tag_name(args[0])
+      when "getRootNode"
+        get_root_node
+      when "normalize"
+        normalize
       when "insertAdjacentElement"
         insert_adjacent_element(args[0], args[1])
       when "insertAdjacentHTML"
@@ -1642,7 +2266,23 @@ module Dommy
       when "toggleAttribute"
         toggle_attribute(args[0], args[1])
       when "matches"
+        raise Bridge::TypeError, "1 argument required, but only 0 present" if args.empty?
+
         matches?(args[0])
+      when "isEqualNode"
+        is_equal_node(args[0])
+      when "isSameNode"
+        is_same_node(args[0])
+      when "compareDocumentPosition"
+        compare_document_position(args[0])
+      when "lookupNamespaceURI"
+        lookup_namespace_uri(args[0])
+      when "lookupPrefix"
+        lookup_prefix(args[0])
+      when "isDefaultNamespace"
+        is_default_namespace(args[0])
+      when "contains"
+        contains?(args[0])
       when "toString"
         to_s
       when "getAttributeNode"
@@ -1660,7 +2300,7 @@ module Dommy
       when "addEventListener"
         add_event_listener(args[0], args[1], args[2])
       when "removeEventListener"
-        remove_event_listener(args[0], args[1])
+        remove_event_listener(args[0], args[1], args[2])
       when "dispatchEvent"
         dispatch_event(args[0])
       when "appendChild"
@@ -1674,9 +2314,9 @@ module Dommy
       when "cloneNode"
         clone_node(args[0])
       when "append"
-        append_nodes(args)
+        append(*args)
       when "prepend"
-        prepend_nodes(args)
+        prepend(*args)
       when "replaceChildren"
         replace_children(*args)
       when "before"
@@ -1686,91 +2326,30 @@ module Dommy
       when "getInnerHTML", "getHTML"
         inner_html
       when "remove"
-        parent = @__node__.parent
-        @__node__.unlink
-        @document.notify_child_list_mutation(target_node: parent, added_nodes: [], removed_nodes: [@__node__]) if parent
-        nil
+        remove
       when "replaceWith"
         replace_with(args)
       when "click"
-        dispatch_event(MouseEvent.new("click", "bubbles" => true, "cancelable" => true, "button" => 0))
+        click
       when "getBoundingClientRect"
-        DOMRect.new
+        get_bounding_client_rect
       when "getClientRects"
-        []
+        get_client_rects
       when "scrollIntoView", "scroll", "scrollTo", "scrollBy"
-        # No layout — record the request for tests to assert against.
-        @__scroll_log__ ||= []
-        @__scroll_log__ << [method, args]
-        nil
+        record_scroll(method, args)
       when "requestFullscreen"
-        @document.__set_fullscreen_element__(self)
-        PromiseValue.resolve(@document.default_view, nil)
+        request_fullscreen
       when "showPopover"
-        toggle_popover_state(true)
-        nil
+        show_popover
       when "hidePopover"
-        toggle_popover_state(false)
-        nil
+        hide_popover
       when "togglePopover"
-        new_state = !@__popover_open__
-        toggle_popover_state(new_state)
-        new_state
+        toggle_popover
       else
         nil
       end
     end
 
-    private
-
-    def normalize_attr_key(name)
-      s = name.to_s
-      case_sensitive_attribute_names? ? s : s.downcase
-    end
-
-    def element_children
-      @__node__.element_children.each_with_object([]) do |node, out|
-        wrapped = @document.wrap_node(node)
-        out << wrapped if wrapped
-      end
-    end
-
-    def wrap_parent(node)
-      @document.wrap_node(node)
-    end
-
-    def __event_parent__
-      parent_node = @__node__.parent
-      # If our Nokogiri parent is a shadow tree's backing fragment,
-      # the bubble path's next stop is the ShadowRoot itself — not
-      # the bare Fragment wrapper. The ShadowRoot's __event_parent__
-      # will return nil (composed events route to host explicitly).
-      if parent_node.is_a?(Nokogiri::XML::DocumentFragment)
-        sr = @document.__shadow_root_for_fragment__(parent_node)
-        return sr if sr
-      end
-
-      parent = wrap_parent(parent_node)
-      parent || @document
-    end
-
-    def template_content
-      return nil unless @__node__.name == "template"
-
-      @document.template_content_fragment(self)
-    end
-
-    # Attribute name handling depends on the element's namespace:
-    # - HTML: case-insensitive (browser DOM stores everything lowercase).
-    # - SVG / other XML: case-sensitive (`viewBox` ≠ `viewbox`).
-    # Subclasses with a known namespace override `case_sensitive_attribute_names?`
-    # to flip the behavior. Generic Element nodes inspect the namespace
-    # URI directly.
-    def case_sensitive_attribute_names?
-      ns = namespace_uri
-      !ns.nil? && ns != "http://www.w3.org/1999/xhtml"
-    end
-
     def get_attribute(name)
       return nil if name.nil?
 
@@ -1780,9 +2359,17 @@ module Dommy
     def set_attribute(name, value)
       return nil if name.nil?
 
+      # WHATWG: a qualifiedName not matching the Name production throws.
+      # The WPT corpus exercises only the empty string here (other shapes
+      # like "0"/":"/"invalid^Name" are deliberately treated as valid).
+      raise DOMException::InvalidCharacterError, "empty attribute name" if name.to_s.empty?
+
       key = normalize_attr_key(name)
       old = @__node__[key]
       @__node__[key] = value.to_s
+      # A direct write to an `aria-*` IDREF attribute drops any explicitly-set
+      # element reference, so the IDL getter re-resolves the new IDREF.
+      clear_aria_element_ref_for(key) if key.start_with?("aria-")
       @document.notify_attribute_mutation(target_node: @__node__, attribute_name: key, old_value: old)
       nil
     end
@@ -1800,17 +2387,75 @@ module Dommy
       return nil unless @__node__.key?(key)
 
       old = @__node__[key]
+      # Detach the cached Attr (caching its value) *before* the backend drop,
+      # so a held reference keeps the value it had when removed.
+      @attributes&.__internal_evict__(nil, key)
       @__node__.remove_attribute(key)
+      # Removing an `aria-*` IDREF attribute also clears any explicitly-set
+      # element reference (the IDL getter then returns null).
+      clear_aria_element_ref_for(key) if key.start_with?("aria-")
       @document.notify_attribute_mutation(target_node: @__node__, attribute_name: key, old_value: old)
       nil
     end
 
+    # ----- Namespaced attributes (DOM *AttributeNS) -----
+
+    def get_attribute_ns(namespace, local_name)
+      return nil if local_name.nil?
+
+      ns = namespace.to_s
+      Backend.get_attribute_ns(@__node__, ns.empty? ? nil : ns, local_name.to_s)
+    end
+
+    def has_attribute_ns?(namespace, local_name)
+      return false if local_name.nil?
+
+      ns = namespace.to_s
+      Backend.has_attribute_ns?(@__node__, ns.empty? ? nil : ns, local_name.to_s)
+    end
+
+    def set_attribute_ns(namespace, qualified_name, value)
+      ns, prefix, local = Internal::Namespaces.validate_and_extract(namespace, qualified_name)
+      old = Backend.get_attribute_ns(@__node__, ns, local)
+      Backend.set_attribute_ns(@__node__, ns, prefix, local, qualified_name.to_s, value.to_s)
+      @document.notify_attribute_mutation(target_node: @__node__, attribute_name: local, old_value: old, namespace: ns)
+      nil
+    end
+
+    def remove_attribute_ns(namespace, local_name)
+      return nil if local_name.nil?
+
+      ns = namespace.to_s
+      ns = nil if ns.empty?
+      local = local_name.to_s
+      old = Backend.get_attribute_ns(@__node__, ns, local)
+      @attributes&.__internal_evict__(ns, local)
+      Backend.remove_attribute_ns(@__node__, ns, local)
+      if old
+        @document.notify_attribute_mutation(target_node: @__node__, attribute_name: local, old_value: old, namespace: ns)
+      end
+      nil
+    end
+
+    def get_attribute_node_ns(namespace, local_name)
+      attributes.get_named_item_ns(namespace, local_name)
+    end
+
     def closest(selector)
-      return nil if selector.nil? || selector.to_s.empty?
+      return nil if selector.nil?
+      Internal.validate_selector!(selector)
+
+      # Elements matching the selector (scoped to this element, so `:scope`
+      # resolves here), then return the nearest inclusive ancestor among them.
+      handler = Internal.scoped_pseudo_handlers(@__node__)
+      safe = Internal.backend_safe_selector(selector.to_s)
+      matched = with_selector_errors(selector) do
+        @document.nokogiri_doc.css(safe, handler).map(&:pointer_id)
+      end
 
       node = @__node__
       while node&.element?
-        return @document.wrap_node(node) if matches_selector?(node, selector.to_s)
+        return @document.wrap_node(node) if matched.include?(node.pointer_id)
 
         node = node.parent
       end
@@ -1818,6 +2463,23 @@ module Dommy
       nil
     end
 
+    # Map Nokogiri's selector errors to spec behavior:
+    # - a CSS *parse* error ("unexpected … after …") means the selector is
+    #   syntactically invalid → SyntaxError (querySelector/closest must throw);
+    # - an "Unregistered function" means a valid pseudo Nokogiri compiled but
+    #   can't evaluate (`:hover`, `:invalid`, …) → degrade to matching nothing.
+    def with_selector_errors(selector)
+      yield
+    rescue ::StandardError => e
+      return [] if e.message.include?("Unregistered function")
+
+      if (defined?(::Nokogiri::CSS::SyntaxError) && e.is_a?(::Nokogiri::CSS::SyntaxError)) || e.message.include?("unexpected")
+        raise DOMException::SyntaxError, "'#{selector}' is not a valid selector."
+      end
+
+      raise
+    end
+
     # Web Animations: start an animation on this element.
     # Returns the new Animation. Dommy doesn't interpolate; the
     # animation simply transitions through the `playState` lifecycle,
@@ -1839,23 +2501,54 @@ module Dommy
     alias getAnimations get_animations
 
     def query_selector(selector)
-      return nil if selector.nil? || selector.to_s.empty?
+      return nil if selector.nil?
+      # The empty string is not a valid selector (an explicit DOMString "" is a
+      # SyntaxError; `null` coerces to "null" and is handled above as nil).
+      Internal.validate_selector!(selector)
 
-      @document.wrap_node(@__node__.at_css(selector.to_s))
+      @document.wrap_node(scoped_query(selector.to_s).first)
     end
 
     def query_selector_all(selector)
-      return NodeList.new if selector.nil? || selector.to_s.empty?
+      return NodeList.new if selector.nil?
+      Internal.validate_selector!(selector)
+
+      NodeList.new(scoped_query(selector.to_s).map { |node| @document.wrap_node(node) }.compact)
+    end
+
+    # Run a CSS query rooted at this element. A `:scope` selector must resolve to
+    # this element, but Nokogiri scopes `el.css` to descendants (`.//`), which
+    # excludes the element itself — so for `:scope` queries we evaluate against
+    # the whole document (where this element IS reachable) and restrict the
+    # results to this element's own subtree.
+    def scoped_query(sel)
+      sel = Internal.backend_safe_selector(sel)
+      handler = Internal.scoped_pseudo_handlers(@__node__)
+      with_selector_errors(sel) do
+        if sel.include?(":scope")
+          self_id = @__node__.pointer_id
+          @document.nokogiri_doc.css(sel, handler).select do |n|
+            n.ancestors.any? { |a| a.pointer_id == self_id }
+          end
+        else
+          @__node__.css(sel, handler)
+        end
+      end
+    end
+
+    # XPath queries scoped to this element, returning wrapped nodes.
+    def at_xpath(expression)
+      node = @__node__.at_xpath(expression)
+      node && @document.wrap_node(node)
+    end
 
-      NodeList.new(@__node__.css(selector.to_s).map { |node| @document.wrap_node(node) }.compact)
+    def xpath(expression)
+      @__node__.xpath(expression).map { |node| @document.wrap_node(node) }
     end
 
-    def append_child(child)
-      check_hierarchy!(child)
-      nodes = detach_dom_nodes(child)
-      append_dom_nodes(nodes)
-      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
-      child
+    # The XPath string locating this element in its document.
+    def path
+      @__node__.path
     end
 
     def insert_before(child, reference)
@@ -1875,7 +2568,7 @@ module Dommy
         end
       end
 
-      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
+      notify_child_list(added: nodes)
       child
     end
 
@@ -1885,8 +2578,7 @@ module Dommy
         raise DOMException::NotFoundError, "node is not a child of this element"
       end
 
-      node.unlink
-      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: [], removed_nodes: [node])
+      @document.remove_node_with_notify(node)
       child
     end
 
@@ -1902,50 +2594,102 @@ module Dommy
       new_nodes = detach_dom_nodes(new_child)
       new_nodes.reverse_each { |node| old_node.add_previous_sibling(node) }
       old_node.unlink
-      @document.notify_child_list_mutation(
-        target_node: @__node__,
-        added_nodes: new_nodes,
-        removed_nodes: [old_node]
-      )
+      notify_child_list(added: new_nodes, removed: [old_node])
       old_child
     end
 
     def clone_node(deep_arg)
-      deep = !!deep_arg
-      if deep
-        @document.wrap_node(
-          Parser.fragment(@__node__.to_html, owner_doc: @document.nokogiri_doc).children.find(&:element?)
-        )
+      # Copy the node in place via libxml's deep dup, NOT by re-parsing to_html as
+      # a fragment: the HTML fragment parser unwraps `<body>` / `<head>` /
+      # `<html>`, so cloning a body produced its children, not a body element
+      # (which broke Turbo's snapshot cache — it clones the body and restores it
+      # via documentElement.replaceChild on back/forward). dup(1) preserves the
+      # element's namespace and attributes (createElement would lose the
+      # namespace); for a shallow clone we keep that node but drop its subtree.
+      copy = @__node__.dup(1)
+      copy.children.each(&:unlink) unless deep_arg
+      @document.wrap_node(copy)
+    end
+
+    # Test inspector for scroll calls (no real layout to scroll).
+    def __test_scroll_log__
+      @scroll_log ||= []
+    end
+
+    # ---- Internal helpers (single private section) ----
+    private
+
+    def attribute_signature
+      Backend.attribute_nodes(@__node__).map { |a| [a.name, a.value] }.sort
+    end
+
+    # on* event-handler property helpers.
+    def event_name_from_on(key)
+      key.to_s.sub(/\Aon/, "").downcase
+    end
+
+    def set_on_handler(event_name, value)
+      @on_handlers ||= {}
+      previous = @on_handlers[event_name]
+      remove_event_listener(event_name, previous) if previous
+      if value
+        add_event_listener(event_name, value)
+        @on_handlers[event_name] = value
       else
-        clone = @document.create_element(@__node__.name)
-        @__node__.attribute_nodes.each do |attr|
-          clone.__js_call__("setAttribute", [attr.name, attr.value])
-        end
+        @on_handlers.delete(event_name)
+      end
+    end
+
+    # Attribute-key / child-wrapping / event-parent helpers.
+    def normalize_attr_key(name)
+      s = name.to_s
+      case_sensitive_attribute_names? ? s : s.downcase
+    end
 
-        clone
+    def element_children
+      @__node__.element_children.each_with_object([]) do |node, out|
+        wrapped = @document.wrap_node(node)
+        out << wrapped if wrapped
       end
     end
 
-    def append_nodes(args)
-      nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
-      append_dom_nodes(nodes)
-      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
-      nil
+    def wrap_parent(node)
+      @document.wrap_node(node)
     end
 
-    def prepend_nodes(args)
-      nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
-      anchor = @__node__.children.first
-      if anchor
-        nodes.reverse_each { |node| anchor.add_previous_sibling(node) }
-      else
-        append_dom_nodes(nodes)
+    def __internal_event_parent__
+      parent_node = @__node__.parent
+      # If our Nokogiri parent is a shadow tree's backing fragment,
+      # the bubble path's next stop is the ShadowRoot itself — not
+      # the bare Fragment wrapper. The ShadowRoot's __internal_event_parent__
+      # will return nil (composed events route to host explicitly).
+      if parent_node.is_a?(Backend.document_fragment_class)
+        sr = @document.__internal_shadow_root_for_fragment__(parent_node)
+        return sr if sr
       end
 
-      @document.notify_child_list_mutation(target_node: @__node__, added_nodes: nodes, removed_nodes: [])
-      nil
+      parent = wrap_parent(parent_node)
+      parent || @document
+    end
+
+    def template_content
+      return nil unless @__node__.name == "template"
+
+      @document.template_content_fragment(self)
+    end
+
+    # Attribute name handling depends on the element's namespace:
+    # - HTML: case-insensitive (browser DOM stores everything lowercase).
+    # - SVG / other XML: case-sensitive (`viewBox` ≠ `viewbox`).
+    # Subclasses with a known namespace override `case_sensitive_attribute_names?`
+    # to flip the behavior. Generic Element nodes inspect the namespace
+    # URI directly.
+    def case_sensitive_attribute_names?
+      ns = namespace_uri
+      !ns.nil? && ns != "http://www.w3.org/1999/xhtml"
     end
 
+    # Insertion / scroll / popover helpers.
     def insert_adjacent(side, args)
       parent = @__node__.parent
       return nil unless parent
@@ -1963,7 +2707,7 @@ module Dommy
         end
       end
 
-      @document.notify_child_list_mutation(target_node: parent, added_nodes: nodes, removed_nodes: [])
+      notify_child_list(added: nodes, target: parent)
       nil
     end
 
@@ -1981,7 +2725,7 @@ module Dommy
         nodes.each { |node| parent.add_child(node) }
       end
 
-      @document.notify_child_list_mutation(target_node: parent, added_nodes: nodes, removed_nodes: [removed])
+      notify_child_list(added: nodes, removed: [removed], target: parent)
       nil
     end
 
@@ -1989,14 +2733,20 @@ module Dommy
       nodes.each { |node| @__node__.add_child(node) }
     end
 
+    # ParentNode hook: Element enforces the no-cycle hierarchy check that
+    # Fragment / ShadowRoot skip.
+    def check_insertion!(child)
+      check_hierarchy!(child)
+    end
+
     # Raise HierarchyRequestError when the proposed insertion would
     # produce a cycle (inserting an ancestor as a descendant of
     # itself). Strings and Fragments are always safe.
     def check_hierarchy!(child)
-      return unless child.respond_to?(:__node__)
+      return unless child.respond_to?(:__dommy_backend_node__)
 
-      node = child.__node__
-      return unless node.is_a?(Nokogiri::XML::Node)
+      node = child.__dommy_backend_node__
+      return unless node.is_a?(Backend.node_class)
 
       if node == @__node__ || @__node__.ancestors.any? { |a| a == node }
         raise(
@@ -2010,27 +2760,8 @@ module Dommy
       detach_dom_nodes(value).first
     end
 
-    def detach_dom_nodes(value)
-      case value
-      when Element, TextNode, CommentNode
-        node = value.__node__
-        node.unlink if node.parent
-        [node]
-      when Fragment
-        value.extract_children
-      when String
-        [@document.create_text_node(value).__node__]
-      else
-        node = unwrap_dom_node(value)
-        return [] unless node
-
-        node.unlink if node.parent
-        [node]
-      end
-    end
-
     def unwrap_dom_node(value)
-      return value.__node__ if value.respond_to?(:__node__)
+      return value.__dommy_backend_node__ if value.respond_to?(:__dommy_backend_node__)
 
       nil
     end
@@ -2043,6 +2774,13 @@ module Dommy
       end
     end
 
+    # No real layout — record the scroll request so tests can assert it.
+    def record_scroll(name, args)
+      @scroll_log ||= []
+      @scroll_log << [name, args]
+      nil
+    end
+
     # Popover state — modern HTML pattern. `show`/`hide`/`toggle`
     # fire `beforetoggle` and `toggle` events (no real visual change).
     def toggle_popover_state(open)
@@ -2064,34 +2802,5 @@ module Dommy
         )
       )
     end
-
-    # Test inspector for scroll calls (no real layout to scroll).
-    def __scroll_log__
-      @__scroll_log__ ||= []
-    end
-
-    public :__scroll_log__
-
-    # Re-expose snake_case methods that the JS bridge dispatch routes
-    # to. Defined as private originally so internal helpers (element_children,
-    # detach_dom_nodes, etc.) stay encapsulated; CRuby users call these
-    # as the public Ruby API.
-    public(
-      :get_attribute,
-      :set_attribute,
-      :has_attribute?,
-      :remove_attribute,
-      :append_child,
-      :insert_before,
-      :remove_child,
-      :replace_child,
-      :clone_node,
-      :query_selector,
-      :query_selector_all,
-      :closest,
-      :animate,
-      :get_animations,
-      :getAnimations
-    )
   end
 end