dommy 0.9.0 → 0.10.0

data/lib/dommy/element.rb

@@ -57,6 +57,27 @@ module Dommy
       @__node__.text
     end
 
+    def text_content=(value)
+      # Replace all children with a single Text node (nullable: null/undefined
+      # clear with no replacement). Unlink old children so a removed node keeps
+      # its own descendants.
+      removed = @__node__.children.to_a
+      str = nullable_dom_string(value)
+      removed.each(&:unlink)
+      @__node__.add_child(@document.create_text_node(str).__dommy_backend_node__) unless str.empty?
+      notify_child_list(added: @__node__.children.to_a, removed: removed)
+    end
+
+    def __js_set__(key, value)
+      case key
+      when "textContent"
+        self.text_content = value
+        nil
+      else
+        Bridge::UNHANDLED
+      end
+    end
+
     def query_selector(selector)
       return nil if selector.nil?
       ast = Internal::SelectorParser.parse!(selector)
@@ -84,6 +105,9 @@ module Dommy
         11
       when "nodeName"
         "#document-fragment"
+      when "nodeValue"
+        # A DocumentFragment's nodeValue is null (not undefined).
+        nil
       when "children"
         element_children
       when "childNodes"
@@ -100,6 +124,10 @@ module Dommy
         last_element_child
       when "textContent"
         @__node__.text
+      when "parentNode", "parentElement"
+        # A DocumentFragment is never inserted, so it has no parent (null, not
+        # undefined).
+        nil
       when "ownerDocument"
         @document
       else
@@ -146,6 +174,7 @@ module Dommy
       when "removeChild"
         remove_child(args[0])
       when "insertBefore"
+        validate_insert_before_ref!(args)
         insert_before(args[0], args[1])
       when "replaceChild"
         replace_child(args[0], args[1])
@@ -192,6 +221,8 @@ module Dommy
     end
 
     def insert_before(node, ref)
+      coerce_node_argument!(node)
+      ensure_pre_insertion_validity!(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__
@@ -203,9 +234,11 @@ module Dommy
     end
 
     def replace_child(new_child, old_child)
+      coerce_node_argument!(new_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__
 
+      ensure_pre_insertion_validity!(new_child, old_child)
       detach_dom_nodes(new_child).each { |n| old_bn.add_previous_sibling(n) }
       old_bn.unlink
       old_child
@@ -221,11 +254,6 @@ module Dommy
       on == @__node__ || Internal::NodeTraversal.ancestor_of?(@__node__, on)
     end
 
-    def normalize
-      @__node__.children.each { |n| n.unlink if n.text? && n.content.empty? }
-      nil
-    end
-
     private
 
     def element_children
@@ -247,6 +275,9 @@ module Dommy
   class CharacterDataNode
     include Node
     include EventTarget
+    # `before` / `after` / `replaceWith` (+ their argument coercion) — the same
+    # spec-correct implementation Element uses, minus appendChild/insertBefore.
+    include Internal::ChildNode
 
     # The owning Dommy document (as Element exposes), so cross-document adoption
     # checks work for text/comment nodes too.
@@ -319,6 +350,12 @@ module Dommy
       @__node__.parent && @document.wrap_node(@__node__.parent)
     end
 
+    # parentElement is the parent only when it is an element (a document or
+    # fragment parent is a parentNode but not a parentElement).
+    def parent_element
+      @document.wrap_node(@__node__.parent) if @__node__.parent&.element?
+    end
+
     def next_sibling
       @__node__.next && @document.wrap_node(@__node__.next)
     end
@@ -351,18 +388,67 @@ module Dommy
     # MutationObserver record.
 
     def length
-      @__node__.content.length
+      utf16_length(@__node__.content)
+    end
+
+    # CharacterData offsets and counts are measured in UTF-16 code units, not
+    # Unicode code points, so an astral character (e.g. an emoji) counts as 2.
+    def utf16_length(str)
+      str.encode(Encoding::UTF_16LE).bytesize / 2
+    end
+
+    # Extract `count` UTF-16 code units from `str` starting at code unit
+    # `offset`. Slicing on the UTF-16LE byte buffer keeps astral characters
+    # intact for the offsets these APIs actually produce.
+    #
+    # If the range starts or ends inside a surrogate pair the result would be a
+    # lone (unpaired) surrogate. JS strings can hold those; a Ruby UTF-8 String
+    # cannot, so re-raise the raw encoding error as a clear, intentional message
+    # rather than leaking "\xDF on UTF-16LE" to the caller. This is a Dommy
+    # limitation and, since splitting a surrogate pair signals a UTF-16 offset
+    # bug in the caller, failing loud is deliberate.
+    def utf16_slice(str, offset, count)
+      buf = str.encode(Encoding::UTF_16LE)
+      buf.byteslice(offset * 2, count * 2).encode(Encoding::UTF_8, Encoding::UTF_16LE)
+    rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+      raise "cannot split a UTF-16 surrogate pair: the requested range would " \
+            "produce a lone surrogate, which Dommy cannot represent"
     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
+      len = utf16_length(s)
+      o = to_uint32(offset)
+      raise DOMException::IndexSizeError, "offset out of bounds" if o > len
+
+      c = [to_uint32(count), len - o].min
+      utf16_slice(s, o, c)
+    end
+
+    # ECMAScript ToUint32 — WebIDL `unsigned long` conversion for a data offset
+    # or count: ToNumber (a non-numeric string is NaN), truncate toward zero,
+    # then take modulo 2**32 (so -1 wraps to 4294967295, 0x100000000+2 to 2).
+    def to_uint32(value)
+      num =
+        case value
+        when Integer then value
+        when Numeric then value
+        when nil then 0 # JS null -> 0
+        else Float(value.to_s) rescue Float::NAN
+        end
+      return 0 unless num.respond_to?(:finite?) ? num.finite? : true
 
-      s[offset.to_i, [count.to_i, 0].max].to_s
+      num.to_i % (2**32)
     end
 
     def append_data(value)
-      write_data(@__node__.content + value.to_s)
+      write_data(@__node__.content + dom_string(value))
+    end
+
+    # WebIDL DOMString coercion for a CharacterData mutation argument: JS null
+    # becomes the string "null" (undefined already stringifies to "undefined").
+    def dom_string(value)
+      value.nil? ? "null" : value.to_s
     end
 
     def insert_data(offset, value)
@@ -375,11 +461,12 @@ module Dommy
 
     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
+      len = utf16_length(s)
+      o = to_uint32(offset)
+      raise DOMException::IndexSizeError, "offset out of bounds" if o > len
 
-      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)
+      c = [to_uint32(count), len - o].min
+      write_data(utf16_slice(s, 0, o) + dom_string(value) + utf16_slice(s, o + c, len - (o + c)))
     end
 
     def __js_get__(key)
@@ -398,6 +485,8 @@ module Dommy
         length
       when "parentNode"
         parent_node
+      when "parentElement"
+        parent_element
       when "ownerDocument"
         @document
       when "nextSibling"
@@ -412,11 +501,32 @@ module Dommy
         NodeList.new
       when "firstChild", "lastChild"
         nil
+      when "assignedSlot"
+        assigned_slot
       else
         Bridge::ABSENT # unknown property: JS undefined, `in` absent
       end
     end
 
+    # Slottable mixin: the <slot> this text node is assigned to. A text node has
+    # no `slot` attribute, so it targets the default (unnamed) slot of its parent
+    # element's shadow tree; a closed shadow tree hides the assignment (null).
+    def assigned_slot
+      parent = @__node__.parent
+      return nil unless parent.respond_to?(:element?) && parent.element?
+
+      host = @document.wrap_node(parent)
+      return nil unless host.respond_to?(:shadow_root)
+
+      sr = host.shadow_root
+      return nil unless sr
+      return nil if sr.__js_get__("mode") == "closed"
+
+      sr.query_selector_all("slot").find do |slot|
+        (slot.respond_to?(:name) ? slot.name.to_s : "") == ""
+      end
+    end
+
     def __js_set__(key, value)
       case key
       when "textContent", "data", "nodeValue"
@@ -441,13 +551,15 @@ module Dommy
         # A leaf node contains only itself (no descendants).
         args[0].respond_to?(:__dommy_backend_node__) &&
           args[0].__dommy_backend_node__ == @__node__
-      when "appendChild", "insertBefore"
+      when "appendChild", "insertBefore", "replaceChild"
         # WebIDL coerces the Node argument first (null/non-Node → TypeError);
-        # only then does a leaf node reject any child with HierarchyRequestError.
+        # only then does the leaf reject the insertion. WHATWG pre-insert /
+        # replace step 1 checks the PARENT type before the reference child, so a
+        # leaf parent is a HierarchyRequestError even when `child` isn't a child.
         raise Bridge::TypeError, "Argument is not a Node." unless args[0].is_a?(Dommy::Node)
 
         raise DOMException::HierarchyRequestError, "this node type does not support children"
-      when "removeChild", "replaceChild"
+      when "removeChild"
         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"
@@ -474,6 +586,8 @@ module Dommy
       when "dispatchEvent"
         dispatch_event(args[0])
       when "appendData"
+        raise Bridge::TypeError, "appendData requires 1 argument." if args.empty?
+
         append_data(args[0])
       when "insertData"
         insert_data(args[0], args[1])
@@ -482,9 +596,12 @@ module Dommy
       when "replaceData"
         replace_data(args[0], args[1], args[2])
       when "substringData"
+        raise Bridge::TypeError, "substringData requires 2 arguments." if args.length < 2
+
         substring_data(args[0], args[1])
       when "remove"
         remove
+        Bridge::UNDEFINED # ChildNode#remove is void -> JS undefined, not null
       when "before"
         before(*args)
       when "after"
@@ -496,86 +613,26 @@ module Dommy
       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).
+    # ChildNode mixin: WHATWG DOM defines `before`, `after`, `replaceWith` on
+    # all child nodes, including Text and Comment. The spec-correct algorithm
+    # (viable previous/next sibling, forward insertion, string coercion,
+    # Fragment/cross-document adoption) lives in Internal::ParentNode and is
+    # shared with Element — these just forward to it.
 
     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
+      child_node_before(args)
     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
+      child_node_after(args)
     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
+      child_node_replace_with(args)
     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
@@ -588,6 +645,30 @@ module Dommy
       3
     end
 
+    # WHATWG Text.wholeText — the concatenated data of this node together with
+    # its contiguous, logically-adjacent Text / CDATASection siblings (node
+    # types 3 and 4), in document order.
+    def whole_text
+      run = [@__node__]
+      prev = @__node__.previous
+      while prev && [3, 4].include?(prev.node_type)
+        run.unshift(prev)
+        prev = prev.previous
+      end
+      nxt = @__node__.next
+      while nxt && [3, 4].include?(nxt.node_type)
+        run.push(nxt)
+        nxt = nxt.next
+      end
+      run.map { |bn| bn.content.to_s }.join
+    end
+
+    def __js_get__(key)
+      return whole_text if key == "wholeText"
+
+      super
+    end
+
     # Own __js_call__ methods, on top of CharacterDataNode's.
     js_methods %w[cloneNode]
     def __js_call__(method, args)
@@ -1171,11 +1252,12 @@ module Dommy
     end
 
     def write_properties(props)
-      if props.empty?
-        @element.remove_attribute("style") if @element.__dommy_backend_node__.key?("style")
-      else
-        @element.set_attribute("style", serialize_properties(props))
-      end
+      # Per CSSOM, mutating an inline style declaration serializes it back to the
+      # `style` content attribute. An emptied declaration serializes to "" and
+      # the attribute STAYS present (style="") — it is removed only via an
+      # explicit removeAttribute("style"), never as a side effect of clearing the
+      # last property.
+      @element.set_attribute("style", serialize_properties(props))
     end
   end
 
@@ -1221,17 +1303,16 @@ module Dommy
     end
 
     def text_content=(value)
-      # Setting textContent removes all existing children and, only for a
-      # non-empty value, appends a single text node. Capture before/after to
-      # feed MutationObserver. The empty case clears children directly: the
-      # backend's `content=` is the parser's, and Makiri leaves an empty text
-      # node behind for "" (Nokogiri and the DOM produce no node at all).
+      # textContent is a nullable DOMString, so null AND undefined both mean "no
+      # value" -> clear the children with no replacement text. Otherwise replace
+      # all children with a single Text node. Unlink the old children (rather
+      # than the backend's `content=`, which frees their whole subtree) so a
+      # reference to a removed node keeps its own descendants intact.
       removed = @__node__.children.to_a
-      str = value.to_s
-      if str.empty?
-        removed.each(&:unlink)
-      else
-        @__node__.content = str
+      str = nullable_dom_string(value)
+      removed.each(&:unlink)
+      unless str.empty?
+        @__node__.add_child(@document.create_text_node(str).__dommy_backend_node__)
       end
       added = @__node__.children.to_a
       notify_child_list(added: added, removed: removed)
@@ -1533,35 +1614,6 @@ module Dommy
     # WHATWG Node.normalize: drop empty Text nodes and merge each run of
     # contiguous Text nodes into the first, firing the matching mutation records
     # (childList for every removed node, characterData for the merged data).
-    def normalize
-      text_nodes = []
-      @__node__.traverse { |node| text_nodes << node if node.respond_to?(:text?) && node.text? }
-
-      text_nodes.each do |node|
-        next unless node.parent # already removed as part of an earlier run
-
-        if node.content.to_s.empty?
-          @document.remove_node_with_notify(node)
-          next
-        end
-
-        merged = []
-        sib = node.next
-        while sib.respond_to?(:text?) && sib.text?
-          merged << sib
-          sib = sib.next
-        end
-        next if merged.empty?
-
-        old = node.content.to_s
-        node.content = old + merged.map { |m| m.content.to_s }.join
-        @document.notify_character_data_mutation(target_node: node, old_value: old)
-        merged.each { |m| @document.remove_node_with_notify(m) }
-      end
-
-      nil
-    end
-
     def toggle_attribute(name, force = nil)
       raise DOMException::InvalidCharacterError, "empty attribute name" if name.to_s.empty?
 
@@ -1596,14 +1648,7 @@ module Dommy
     end
 
     def get_elements_by_tag_name(name)
-      n = name.to_s.downcase
-      root = @__node__
-      doc = @document
-      if n == "*"
-        HTMLCollection.new { root.css("*").map { |x| doc.wrap_node(x) }.compact }
-      else
-        HTMLCollection.new { root.css(n).map { |x| doc.wrap_node(x) }.compact }
-      end
+      HTMLCollection.elements_by_tag_name(@__node__, @document, name)
     end
 
     def get_elements_by_tag_name_ns(namespace, local_name)
@@ -1616,6 +1661,10 @@ module Dommy
       @attributes ||= NamedNodeMap.new(self)
     end
 
+    # Public bridges to the attribute-name case machinery, for NamedNodeMap.
+    def __internal_normalize_attr_key__(name) = normalize_attr_key(name)
+    def __internal_case_sensitive_attribute_names__? = case_sensitive_attribute_names?
+
     def get_attribute_node(name)
       attributes.get_named_item(name)
     end
@@ -1755,16 +1804,31 @@ module Dommy
 
     alias connected? is_connected?
 
-    # `focus()` / `blur()` — Dommy has no layout / real focus, but
-    # tests rely on `document.activeElement` updating. Track the most
-    # recently focused element on the document.
+    # `focus()` — the HTML focusing steps, minus layout: Dommy treats any
+    # element as focusable (except a disabled form control), then updates
+    # document.activeElement AND fires the focus-change events a real
+    # browser would — blur/focusout on the previously focused element, then
+    # focus/focusin here, with relatedTarget linking the two. JS calling
+    # `input.focus()` therefore triggers the same focus handlers a user's
+    # click/tab would; already-focused and disabled targets are no-ops.
     def focus
+      return nil if disabled_form_control?
+      return nil if @document.__internal_focused_element__.equal?(self)
+
+      previous = @document.__internal_focused_element__
+      fire_focus_out(previous, self) if previous
       @document.__internal_set_active_element__(self)
+      dispatch_event(Dommy::FocusEvent.new("focus", "composed" => true, "relatedTarget" => previous))
+      dispatch_event(Dommy::FocusEvent.new("focusin",
+        "bubbles" => true, "composed" => true, "relatedTarget" => previous))
       nil
     end
 
     def blur
+      return nil unless @document.__internal_focused_element__.equal?(self)
+
       @document.__internal_set_active_element__(nil)
+      fire_focus_out(self, nil)
       nil
     end
 
@@ -1805,14 +1869,18 @@ module Dommy
         raise DOMException::NotSupportedError, "<#{tag}> cannot host a shadow root"
       end
 
-      raise DOMException::InvalidStateError, "Shadow root already attached" if @__shadow_root
+      raise DOMException::NotSupportedError, "Shadow root already attached" if @__shadow_root
 
       opts = options.is_a?(Hash) ? options : {}
       mode_raw = opts.key?("mode") ? opts["mode"] : opts[:mode]
-      raise TypeError, "attachShadow init dictionary requires 'mode'" if mode_raw.nil?
+      # `mode` is a required WebIDL dictionary member — omitting it, like an
+      # invalid enum value below, is a (JS) TypeError, not a DOMException.
+      raise Bridge::TypeError, "attachShadow init dictionary requires 'mode'" if mode_raw.nil?
 
+      # `mode` is a WebIDL enum (ShadowRootMode); a value that isn't "open"/
+      # "closed" fails enum conversion → TypeError, not a DOMException.
       mode = mode_raw.to_s
-      raise DOMException::SyntaxError, "mode must be 'open' or 'closed'" unless %w[open closed].include?(mode)
+      raise Bridge::TypeError, "mode must be 'open' or 'closed'" unless %w[open closed].include?(mode)
 
       @__shadow_root = ShadowRoot.new(
         self,
@@ -1841,16 +1909,26 @@ module Dommy
     # `el.insertAdjacentElement(position, element)` — DOM spec positions:
     # "beforebegin", "afterbegin", "beforeend", "afterend". Returns the
     # inserted element or nil if position has no anchor (root cases).
+    ADJACENT_POSITIONS = %w[beforebegin afterbegin beforeend afterend].freeze
+
     def insert_adjacent_element(position, element)
+      # Position is an ASCII case-insensitive enum; anything else is a SyntaxError
+      # (checked before the node coercion / anchor lookup, per spec).
+      pos = position.to_s.downcase
+      unless ADJACENT_POSITIONS.include?(pos)
+        raise DOMException::SyntaxError, "'#{position}' is not a valid insertAdjacent position."
+      end
       return nil unless element.respond_to?(:__dommy_backend_node__)
 
-      case position.to_s
+      case pos
       when "beforebegin"
-        return nil unless @__node__.parent
+        parent = @__node__.parent
+        return nil unless parent
 
+        validate_adjacent_document_insert!(parent, element)
         node = detach_for_insert(element)
         @__node__.add_previous_sibling(node)
-        notify_child_list(added: [node], target: @__node__.parent)
+        notify_child_list(added: [node], target: parent)
       when "afterbegin"
         node = detach_for_insert(element)
         first = @__node__.children.first
@@ -1861,18 +1939,27 @@ module Dommy
         @__node__.add_child(node)
         notify_child_list(added: [node])
       when "afterend"
-        return nil unless @__node__.parent
+        parent = @__node__.parent
+        return nil unless parent
 
+        validate_adjacent_document_insert!(parent, element)
         node = detach_for_insert(element)
         @__node__.add_next_sibling(node)
-        notify_child_list(added: [node], target: @__node__.parent)
-      else
-        return nil
+        notify_child_list(added: [node], target: parent)
       end
 
       element
     end
 
+    # beforebegin / afterend insert a sibling — when this element's parent is the
+    # document, that would add a second document child, so run the document's
+    # WHATWG pre-insertion hierarchy check (a second root element is rejected).
+    def validate_adjacent_document_insert!(parent, element)
+      return unless parent == @document.backend_doc
+
+      @document.ensure_document_insertion_validity!([element], @__node__)
+    end
+
     def insert_adjacent_html(position, html)
       # Position is ASCII case-insensitive ("beforeBegin" == "beforebegin").
       pos = position.to_s.downcase
@@ -1993,15 +2080,15 @@ module Dommy
     # ChildNode mixin — before / after / replaceWith with mixed args.
 
     def before(*args)
-      insert_adjacent(:before, args)
+      child_node_before(args)
     end
 
     def after(*args)
-      insert_adjacent(:after, args)
+      child_node_after(args)
     end
 
     def replace_with_nodes(*args)
-      replace_with(args)
+      child_node_replace_with(args)
     end
 
     # `getInnerHTML()` — happy-dom alias for the `innerHTML` getter.
@@ -2022,19 +2109,19 @@ module Dommy
     # activation behavior (the default) just dispatch the event.
     def click
       pre = pre_click_activation_state
-      not_canceled = dispatch_event(MouseEvent.new("click", "bubbles" => true, "cancelable" => true, "button" => 0))
-      return not_canceled if pre.nil?
-
+      event = MouseEvent.new("click", "bubbles" => true, "cancelable" => true, "button" => 0)
+      not_canceled = dispatch_event(event)
       if not_canceled
-        run_post_click_activation(pre)
-      else
+        run_post_click_activation(pre) unless pre.nil?
+        __run_click_activation_behavior__(event)
+      elsif pre
         restore_pre_click_activation(pre)
       end
       not_canceled
     end
 
-    # Activation-behavior hooks. The default element has none; HTMLInputElement
-    # overrides these for checkbox/radio.
+    # Pre-click activation hooks (checkbox/radio toggle-then-maybe-revert). The
+    # default element has none; HTMLInputElement overrides these.
     def pre_click_activation_state
       nil
     end
@@ -2043,10 +2130,59 @@ module Dommy
 
     def restore_pre_click_activation(_state); end
 
+    # Activation behavior: the default action of a non-canceled click (a
+    # hyperlink navigates; a submit button submits its form — added later). The
+    # default element has none. Called on the *activation target*.
+    def activation_behavior(_event); end
+
+    # An element is an "activation target" when it carries its own activation
+    # behavior (a hyperlink). Default: no.
+    def activation_target?
+      false
+    end
+
+    # The activation target for a click on this element: the nearest inclusive
+    # ancestor that is an activation target, or nil — so clicking a <span> inside
+    # an <a href> activates the anchor.
+    def activation_target
+      node = self
+      while node
+        return node if node.respond_to?(:activation_target?) && node.activation_target?
+
+        node = node.respond_to?(:parent_element) ? node.parent_element : nil
+      end
+      nil
+    end
+
+    # Run the activation target's activation behavior after a non-canceled click.
+    # Shared by Element#click (JS `.click()`) and synthetic clicks
+    # (EventSynthesis) so a real default action fires from both paths.
+    def __run_click_activation_behavior__(event)
+      activation_target&.activation_behavior(event)
+    end
+
     def get_attribute_names
       Backend.attribute_nodes(@__node__).map(&:name)
     end
 
+    # A plain {name => value} snapshot of ALL attributes, for the JS bridge's
+    # per-proxy attribute cache (see host_runtime.js): one crossing answers
+    # every subsequent getAttribute/hasAttribute until the DOM epoch moves.
+    # nil for an element whose attribute lookups are case-SENSITIVE (foreign
+    # namespace) — the JS side then keeps the per-call bridge path. Keys are
+    # as stored (already lowercased for HTML elements), so a JS-side
+    # `name.toLowerCase()` lookup matches get_attribute's normalize_attr_key.
+    def __js_attribute_snapshot__
+      return nil if case_sensitive_attribute_names?
+
+      # Two attributes can share a qualified name (differing only by namespace);
+      # get-an-attribute-by-name returns the FIRST in list order, so keep the
+      # first occurrence (Ruby's Array#to_h would keep the last).
+      Backend.attribute_nodes(@__node__).each_with_object({}) do |a, snapshot|
+        snapshot[a.name] = a.value.to_s unless snapshot.key?(a.name)
+      end
+    end
+
     # No real layout engine. By default geometry getters return zeroed rects;
     # when the window opts into approximate geometry (window.approximate_layout)
     # they return non-zero estimates from a cheap pseudo-layout so a site that
@@ -2174,7 +2310,9 @@ module Dommy
       when "firstElementChild"
         first_element_child
       when "parentElement", "parent"
-        wrap_parent(@__node__.parent)
+        # parentElement is null unless the parent is an element (the document /
+        # a fragment parent is a parentNode but not a parentElement).
+        @__node__.parent&.element? ? wrap_parent(@__node__.parent) : nil
       when "parentNode"
         # `parentNode` is broader than `parentElement` — includes
         # DocumentFragment / Document parents too. Reconcilers use
@@ -2182,6 +2320,11 @@ module Dommy
         @__node__.parent && @document.wrap_node(@__node__.parent)
       when "textContent"
         @__node__.text
+      when "nodeValue"
+        # Per DOM, an Element's nodeValue is always null (only CharacterData /
+        # Attr carry a value). Without this it fell through to ABSENT → JS
+        # `undefined`, which fails `assert_equals(el.nodeValue, null)`.
+        nil
       when "innerHTML"
         inner_html
       when "outerHTML"
@@ -2212,6 +2355,15 @@ module Dommy
         @__node__["class"].to_s
       when "id"
         @__node__["id"].to_s
+      when "lang"
+        # The `lang` IDL attribute reflects the `lang` content attribute (own
+        # value, "" when absent) — not the inherited/computed language.
+        @__node__["lang"].to_s
+      when "translate"
+        # `translate` is a boolean reflecting the element's translation mode,
+        # which inherits: translate="yes"/"" → true, "no" → false, else the
+        # nearest ancestor's mode; the root defaults to translate (true).
+        translate_mode?
       when "hidden", "disabled", "checked", "readOnly", "multiple", "required"
         # Boolean reflected properties — true iff the matching HTML
         # attribute is present. Real DOM normalizes attribute names to
@@ -2309,10 +2461,11 @@ module Dommy
     # `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}"
+      # Only aria-activedescendant reflects as a SINGULAR element reference; every
+      # other ARIA element reference (controls / describedby / details /
+      # errormessage / flowto / labelledby / owns) is plural (aria*Elements), so
+      # e.g. `ariaErrorMessageElement` must not exist.
+      key == "ariaActiveDescendantElement" ? "aria-activedescendant" : nil
     end
 
     # Read an ARIA element reference: an explicitly-set Element wins; otherwise
@@ -2320,7 +2473,13 @@ module Dommy
     # this element's tree), or null.
     def aria_element_get(content_attr, key)
       explicit = (@aria_element_refs ||= {})[key]
-      return explicit if explicit
+      if explicit
+        # An explicitly-set attr-element is only observable while it stays in a
+        # valid scope: a shadow-including descendant of one of this element's
+        # shadow-including ancestors. A reference that crosses into a shadow tree
+        # (or whose target is reparented out of scope) reads as null.
+        return aria_ref_in_valid_scope?(explicit) ? explicit : nil
+      end
 
       idref = @__node__[content_attr].to_s
       return nil if idref.empty?
@@ -2328,6 +2487,27 @@ module Dommy
       aria_find_in_root(idref)
     end
 
+    # WHATWG "reflecting element references" scope check: `attr_element` is valid
+    # iff its root is this element's root or a shadow-including-ancestor root
+    # (reached by hopping each shadow root to its host). So a same-tree reference
+    # and a reference to a shadow-inclusive ancestor are valid, but crossing into
+    # a shadow tree (or a sibling/detached scope) is not.
+    def aria_ref_in_valid_scope?(attr_element)
+      return false unless attr_element.respond_to?(:root_node)
+
+      target_root = attr_element.root_node
+      scope = self
+      loop do
+        root = scope.root_node
+        return true if root.equal?(target_root)
+
+        host = root.respond_to?(:host) ? root.host : nil
+        return false unless host
+
+        scope = host
+      end
+    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).
@@ -2337,6 +2517,9 @@ module Dommy
         refs.delete(key)
         remove_attribute(content_attr) if @__node__.key?(content_attr)
       else
+        # WebIDL: the value is an `Element?` — a non-Element throws a TypeError.
+        raise Bridge::TypeError, "value is not an Element or null" unless value.is_a?(Dommy::Element)
+
         # set_attribute clears explicit refs via its aria-* hook, so store the
         # new reference afterward.
         set_attribute(content_attr, "")
@@ -2360,8 +2543,24 @@ module Dommy
     # 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)
+      # null when there are neither explicit elements nor a content attribute.
+      return nil if aria_elements_current(content_attr, key).nil?
+
+      # Otherwise a per-property memoized live list, so repeated reads return the
+      # [SameObject] (WebIDL requires a stable FrozenArray) while its contents track
+      # the current references/IDREFs.
+      lists = (@aria_elements_lists ||= {})
+      lists[key] ||= LiveNodeList.new { aria_elements_current(content_attr, key) || [] }
+    end
+
+    # The current resolved element list for a plural ARIA element reference, or
+    # nil when neither explicit elements nor the content attribute are present. An
+    # explicitly-set list wins (out-of-scope entries dropped); otherwise the
+    # content attribute is split as space-separated IDREFs and each resolved.
+    def aria_elements_current(content_attr, key)
       explicit = (@aria_elements_refs ||= {})[key]
-      return explicit.dup if explicit
+      return explicit.select { |el| aria_ref_in_valid_scope?(el) } if explicit
+      return nil unless @__node__.key?(content_attr)
 
       @__node__[content_attr].to_s.split(/[ \t\n\f\r]+/).reject(&:empty?).filter_map do |id|
         aria_find_in_root(id)
@@ -2387,8 +2586,14 @@ module Dommy
         refs.delete(key)
         remove_attribute(content_attr) if @__node__.key?(content_attr)
       else
+        # WebIDL: the value is a `sequence<Element>?` — a non-array, or an array
+        # containing a non-Element, throws a TypeError.
+        unless value.is_a?(Array) && value.all? { |el| el.is_a?(Dommy::Element) }
+          raise Bridge::TypeError, "value is not a sequence of Elements"
+        end
+
         set_attribute(content_attr, "")
-        refs[key] = Array(value)
+        refs[key] = value.dup
       end
       nil
     end
@@ -2436,6 +2641,24 @@ module Dommy
       {"readOnly" => "readonly"}.fetch(key, key)
     end
 
+    # The element's translation mode (HTML `translate`): the nearest ancestor-or-
+    # self with a valid translate attribute decides ("yes"/"" → true, "no" →
+    # false); with none, the root default is translate (true).
+    def translate_mode?
+      node = self
+      while node
+        attr = node.respond_to?(:get_attribute) ? node.get_attribute("translate") : nil
+        unless attr.nil?
+          value = attr.to_s.downcase
+          return true if value == "yes" || value.empty?
+          return false if value == "no"
+          # An invalid value inherits — keep walking up.
+        end
+        node = node.respond_to?(:parent_element) ? node.parent_element : nil
+      end
+      true
+    end
+
     def __js_set__(key, value)
       case key
       when "textContent"
@@ -2461,6 +2684,11 @@ module Dommy
         # Handling it here stops the bridge from stashing a string expando that
         # would shadow the CSSStyleDeclaration getter.
         @style.css_text = value.nil? ? "" : value.to_s
+      when "lang"
+        set_attribute("lang", value.to_s)
+      when "translate"
+        # The setter is a plain boolean → "yes" / "no".
+        set_attribute("translate", value ? "yes" : "no")
       when "className"
         set_attribute("class", value.to_s)
       when "classList"
@@ -2504,7 +2732,7 @@ module Dommy
       getAttribute setAttribute hasAttribute removeAttribute getAttributeNames closest
       getAttributeNS setAttributeNS hasAttributeNS removeAttributeNS getAttributeNodeNS setAttributeNodeNS
       querySelector querySelectorAll getElementsByClassName getElementsByTagName getElementsByTagNameNS
-      insertAdjacentElement insertAdjacentHTML insertAdjacentText toggleAttribute matches
+      insertAdjacentElement insertAdjacentHTML insertAdjacentText toggleAttribute matches webkitMatchesSelector
       toString getAttributeNode setAttributeNode removeAttributeNode focus blur attachShadow
       addEventListener removeEventListener dispatchEvent appendChild insertBefore removeChild
       replaceChild cloneNode append prepend replaceChildren before after getInnerHTML getHTML
@@ -2574,10 +2802,12 @@ module Dommy
         insert_adjacent_text(args[0], args[1])
       when "toggleAttribute"
         toggle_attribute(args[0], args[1])
-      when "matches"
+      when "matches", "webkitMatchesSelector"
         raise Bridge::TypeError, "1 argument required, but only 0 present" if args.empty?
 
-        matches?(args[0])
+        # WebIDL DOMString: a null selector coerces to "null" (so `<null>` matches),
+        # undefined to "undefined". webkitMatchesSelector is a legacy alias.
+        matches?(args[0].nil? ? "null" : args[0])
       when "isEqualNode"
         is_equal_node(args[0])
       when "isSameNode"
@@ -2615,6 +2845,7 @@ module Dommy
       when "appendChild"
         append_child(args[0])
       when "insertBefore"
+        validate_insert_before_ref!(args)
         insert_before(args[0], args[1])
       when "removeChild"
         remove_child(args[0])
@@ -2629,15 +2860,16 @@ module Dommy
       when "replaceChildren"
         replace_children(*args)
       when "before"
-        insert_adjacent(:before, args)
+        child_node_before(args)
       when "after"
-        insert_adjacent(:after, args)
+        child_node_after(args)
       when "getInnerHTML", "getHTML"
         inner_html
       when "remove"
         remove
+        Bridge::UNDEFINED # ChildNode#remove is void -> JS undefined, not null
       when "replaceWith"
-        replace_with(args)
+        child_node_replace_with(args)
       when "click"
         click
       when "getBoundingClientRect"
@@ -2673,6 +2905,19 @@ module Dommy
       # like "0"/":"/"invalid^Name" are deliberately treated as valid).
       raise DOMException::InvalidCharacterError, "empty attribute name" if name.to_s.empty?
 
+      # A case-sensitive element (non-HTML namespace, or any element in a non-HTML
+      # document) must preserve the attribute name's case, but a plain `node[name]=`
+      # write goes through the HTML backend which ASCII-lowercases it. Route an
+      # upper-cased name through the case-preserving namespace setter (null
+      # namespace) to keep the case; lower-case names take the fast path unchanged.
+      qn = name.to_s
+      if case_sensitive_attribute_names? && qn.match?(/[A-Z]/)
+        old = Backend.get_attribute_ns(@__node__, nil, qn)
+        Backend.set_attribute_ns(@__node__, nil, nil, qn, qn, value.to_s)
+        @document.notify_attribute_mutation(target_node: @__node__, attribute_name: qn, old_value: old)
+        return nil
+      end
+
       key = normalize_attr_key(name)
       old = @__node__[key]
       @__node__[key] = value.to_s
@@ -2696,9 +2941,16 @@ 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)
+      # Detach the cached Attr (caching its value) *before* the backend drop, so a
+      # held reference keeps the value it had when removed and reports
+      # `ownerElement === null` (so it's no longer "in use"). An attribute set via
+      # setAttributeNS may carry a namespace, so evict by the removed node's real
+      # (namespace, localName) rather than assuming the null namespace.
+      if @attributes
+        removed = Backend.attribute_nodes(@__node__).find { |a| Backend.attribute_ns_info(a)[:qualified_name] == key }
+        info = removed && Backend.attribute_ns_info(removed)
+        @attributes.__internal_evict__(info ? info[:namespace_uri] : nil, info ? info[:local_name] : key)
+      end
       @__node__.remove_attribute(key)
       # Removing an `aria-*` IDREF attribute also clears any explicitly-set
       # element reference (the IDL getter then returns null).
@@ -2712,15 +2964,13 @@ module Dommy
     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)
+      Backend.get_attribute_ns(@__node__, namespace_arg(namespace), 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)
+      Backend.has_attribute_ns?(@__node__, namespace_arg(namespace), local_name.to_s)
     end
 
     def set_attribute_ns(namespace, qualified_name, value)
@@ -2734,8 +2984,7 @@ module Dommy
     def remove_attribute_ns(namespace, local_name)
       return nil if local_name.nil?
 
-      ns = namespace.to_s
-      ns = nil if ns.empty?
+      ns = namespace_arg(namespace)
       local = local_name.to_s
       old = Backend.get_attribute_ns(@__node__, ns, local)
       @attributes&.__internal_evict__(ns, local)
@@ -2881,7 +3130,12 @@ module Dommy
 
       # Capture the insertion point (old's next sibling) before detaching the new
       # child, which may itself be old (replaceChild(x, x)) or old's sibling.
+      # WHATWG: if that reference child IS the node being inserted (new_child is
+      # old's next sibling), advance it to new_child's next sibling so the node
+      # lands in old's slot rather than being appended.
       anchor = old_node.next_sibling
+      new_bn = unwrap_dom_node(new_child)
+      anchor = anchor.next_sibling if anchor && new_bn && anchor == new_bn
       new_nodes = detach_dom_nodes(new_child)
       anchor = nil if anchor && anchor.parent != @__node__
 
@@ -2911,7 +3165,21 @@ module Dommy
       # preserves the element's namespace and attributes (createElement would
       # lose the namespace).
       copy = Backend.clone_node(@__node__, deep: deep_arg)
-      @document.wrap_node(copy)
+      # The backend (lexbor, HTML-only) doesn't retain the createElementNS
+      # prefix/local/qualified-name/namespace, so rebuild the clone's wrapper from
+      # that metadata — routing the interface class by the local name and
+      # reapplying tagName/localName/prefix/namespaceURI. Otherwise the clone loses
+      # its prefix/case and resolves to HTMLUnknownElement.
+      clone =
+        if @__ns_qname
+          @document.wrap_cloned_element_ns(copy, @__ns_uri, @__ns_prefix, @__ns_local, @__ns_qname)
+        else
+          @document.wrap_node(copy)
+        end
+      # HTML cloning steps: propagate form-control dirty state (an input's value /
+      # checkedness, …) that lives on the wrapper, not the backend node.
+      @document.__internal_apply_cloning_steps__(@__node__, copy, deep_arg)
+      clone
     end
 
     # Test inspector for scroll calls (no real layout to scroll).
@@ -2922,33 +3190,41 @@ module Dommy
     # ---- Internal helpers (single private section) ----
     private
 
-    def attribute_signature
-      Backend.attribute_nodes(@__node__).map { |a| [a.name, a.value] }.sort
+    # blur (at the element) then focusout (bubbling), per UI Events order.
+    def fire_focus_out(element, new_target)
+      element.dispatch_event(Dommy::FocusEvent.new("blur", "composed" => true, "relatedTarget" => new_target))
+      element.dispatch_event(Dommy::FocusEvent.new("focusout",
+        "bubbles" => true, "composed" => true, "relatedTarget" => new_target))
+      nil
     end
 
-    # on* event-handler property helpers.
-    def event_name_from_on(key)
-      key.to_s.sub(/\Aon/, "").downcase
+    # A disabled form control cannot be focused (HTML focusability). Other
+    # elements are all treated as focusable — no layout means no visibility /
+    # tabindex modelling.
+    def disabled_form_control?
+      %w[input button select textarea].include?(local_name) && has_attribute?("disabled")
     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
+    def attribute_signature
+      Backend.attribute_nodes(@__node__).map { |a| [a.name, a.value] }.sort
     end
 
+    # on* event-handler property helpers.
     # Attribute-key / child-wrapping / event-parent helpers.
     def normalize_attr_key(name)
       s = name.to_s
       case_sensitive_attribute_names? ? s : s.downcase
     end
 
+    # WebIDL nullable-DOMString namespace argument (*AttributeNS): JS null and
+    # undefined, and the empty string, all denote the null namespace.
+    def namespace_arg(namespace)
+      return nil if namespace.nil? || namespace.equal?(Bridge::UNDEFINED)
+
+      s = namespace.to_s
+      s.empty? ? nil : s
+    end
+
     def element_children
       @__node__.element_children.each_with_object([]) do |node, out|
         wrapped = @document.wrap_node(node)
@@ -2987,51 +3263,15 @@ module Dommy
     # Subclasses with a known namespace override `case_sensitive_attribute_names?`
     # to flip the behavior. Generic Element nodes inspect the namespace
     # URI directly.
+    # Attribute qualified names are ASCII-lowercased (case-insensitive) only for an
+    # element in the HTML namespace within an HTML document; every other case — a
+    # non-HTML (or null) namespace, or any element in a non-HTML document —
+    # preserves case (WHATWG "set/get/has attribute" lowercasing condition).
     def case_sensitive_attribute_names?
-      ns = namespace_uri
-      !ns.nil? && ns != "http://www.w3.org/1999/xhtml"
+      !(namespace_uri == "http://www.w3.org/1999/xhtml" && @document.html_document?)
     end
 
     # Insertion / scroll / popover helpers.
-    def insert_adjacent(side, args)
-      parent = @__node__.parent
-      return nil unless parent
-
-      nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
-      case side
-      when :before
-        nodes.reverse_each { |node| @__node__.add_previous_sibling(node) }
-      when :after
-        anchor = @__node__.next_sibling
-        if anchor
-          nodes.reverse_each { |node| anchor.add_previous_sibling(node) }
-        else
-          nodes.each { |node| parent.add_child(node) }
-        end
-      end
-
-      notify_child_list(added: nodes, target: parent)
-      nil
-    end
-
-    def replace_with(args)
-      parent = @__node__.parent
-      return nil unless parent
-
-      nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
-      removed = @__node__
-      anchor = @__node__.next_sibling
-      @__node__.unlink
-      if anchor
-        nodes.reverse_each { |node| anchor.add_previous_sibling(node) }
-      else
-        nodes.each { |node| parent.add_child(node) }
-      end
-
-      notify_child_list(added: nodes, removed: [removed], target: parent)
-      nil
-    end
-
     def append_dom_nodes(nodes)
       nodes.each { |node| @__node__.add_child(node) }
     end