dommy 0.8.0 → 0.9.0

data/lib/dommy/internal/node_wrapper_cache.rb

@@ -6,9 +6,28 @@ module Dommy
     # Ensures that wrap_node(nokogiri_node) always returns the same Ruby object.
     # Separates identity/caching management from Document's public DOM API.
     class NodeWrapperCache
+      # Distinguishes "no namespace argument given" (derive from the backend /
+      # document) from an explicit nil namespace passed by createElementNS.
+      NAMESPACE_UNSET = Object.new.freeze
+
+      # Cap on distinct cached selectors before the query cache is cleared
+      # wholesale — a backstop against a page that generates unbounded unique
+      # selector strings; real pages reuse a small set (tens).
+      QUERY_CACHE_CAP = 512
+
       def initialize(document)
         @document = document
         @wrappers = {}
+        # Memoizes document-rooted CSS query results within a DOM generation.
+        # querySelector(All) over a large tree is a full descendant walk, yet a
+        # heavy page issues the SAME selector hundreds of times between mutations
+        # (measured ~87% repeats on a real site). `Document#style_generation`
+        # bumps on every childList / attribute / characterData mutation — and on
+        # focus / active-element changes too, so `:focus`-dependent selectors are
+        # invalidated correctly — so a result tagged with the generation it was
+        # computed in stays valid until the next mutation, then is recomputed
+        # lazily. Keyed by [kind, selector] => [generation, value].
+        @query_cache = {}
       end
 
       # Returns the wrapped node, creating and caching if needed.
@@ -16,11 +35,22 @@ module Dommy
       def wrap(node)
         return nil unless node
 
-        cached = @wrappers[node.object_id]
-        return cached if cached
+        key = identity_key(node)
+        cached = @wrappers[key]
+        # A hit is only trustworthy if the cached wrapper still describes the
+        # SAME kind of node as the one now at this identity key. The key is a
+        # backend pointer/object_id, and a backend MAY recycle a freed node's
+        # identity (Nokogiri reuses object_ids; Makiri reuses the lxb pointer of
+        # a *transient* node — e.g. a throwaway fragment parsed by
+        # `Parser.fragment` — once it's GC'd). When that happens the stale entry
+        # would hand back a wrapper of the wrong type (observed: a Fragment
+        # clone resolving to a cached TextNode). Validate cheaply via nodeType —
+        # compared against a static class→type map so we never dereference the
+        # cached wrapper's (possibly freed) backend node — and rebuild on a miss.
+        return cached if cached && cached_wrapper_live?(cached, node)
 
         wrapper = build_wrapper_for(node)
-        @wrappers[node.object_id] = wrapper if wrapper
+        @wrappers[key] = wrapper if wrapper
         wrapper
       end
 
@@ -29,7 +59,7 @@ module Dommy
       def create_element(name)
         str = domstring(name)
         raise DOMException::InvalidCharacterError, "name must not be empty" if str.empty?
-        raise DOMException::InvalidCharacterError, "invalid element name: #{str.inspect}" unless str.match?(Namespaces::NAME)
+        raise DOMException::InvalidCharacterError, "invalid element name: #{str.inspect}" unless str.match?(Namespaces::HTML_NAME)
 
         # WHATWG createElement: lowercase (ASCII) the name only in an HTML
         # document; the namespace is the HTML namespace for HTML/XHTML documents
@@ -44,25 +74,37 @@ module Dommy
           namespace = @document.content_type == "application/xhtml+xml" ? Element::HTML_NAMESPACE : nil
         end
 
-        wrapper = wrap_node(Backend.create_element(local, @document.nokogiri_doc))
+        wrapper = wrap_node(Backend.create_element(local, @document.backend_doc))
         wrapper.__internal_set_namespace__(namespace, nil, local, local)
         wrapper
       end
 
       def create_text_node(text)
-        wrap_node(Backend.create_text(text.to_s, @document.nokogiri_doc))
+        wrap_node(Backend.create_text(text.to_s, @document.backend_doc))
       end
 
       def create_cdata_section(text)
-        wrap_node(Backend.create_cdata(text.to_s, @document.nokogiri_doc))
+        wrap_node(Backend.create_cdata(text.to_s, @document.backend_doc))
       end
 
       def create_comment(text)
-        wrap_node(Backend.create_comment(text.to_s, @document.nokogiri_doc))
+        wrap_node(Backend.create_comment(text.to_s, @document.backend_doc))
+      end
+
+      # WHATWG Document.createProcessingInstruction: the target must be a valid
+      # XML Name and the data must not contain the PI close delimiter "?>", else
+      # InvalidCharacterError. The result is a real backend-backed PI node.
+      def create_processing_instruction(target, data)
+        t = domstring(target)
+        d = domstring(data)
+        raise DOMException::InvalidCharacterError, "invalid processing instruction target: #{t.inspect}" unless t.match?(Namespaces::NAME)
+        raise DOMException::InvalidCharacterError, "processing instruction data must not contain '?>'" if d.include?("?>")
+
+        wrap_node(Backend.create_processing_instruction(t, d, @document.backend_doc))
       end
 
       def create_document_fragment
-        wrap_node(@document.nokogiri_doc.fragment(""))
+        wrap_node(@document.backend_doc.fragment(""))
       end
 
       def create_attribute(name)
@@ -70,6 +112,9 @@ module Dommy
         raise DOMException::InvalidCharacterError, "name must not be empty" if str.empty?
         raise DOMException::InvalidCharacterError, "invalid attribute name: #{str.inspect}" unless str.match?(Namespaces::NAME)
 
+        # WHATWG createAttribute: an HTML document lower-cases the name (an XML
+        # document preserves it). Attr.new no longer folds case, so do it here.
+        str = str.downcase if @document.html_document?
         Attr.new(str)
       end
 
@@ -88,12 +133,12 @@ module Dommy
         # DOMString (undefined → "undefined", null → "null").
         namespace_uri = nil if namespace_uri.equal?(Bridge::UNDEFINED)
         qualified_name = domstring(qualified_name)
-        ns, prefix, local = Namespaces.validate_and_extract(namespace_uri, qualified_name)
+        ns, prefix, local = Namespaces.validate_and_extract(namespace_uri, qualified_name, context: :element)
 
-        el = Backend.create_element(qualified_name, @document.nokogiri_doc)
+        el = Backend.create_element(qualified_name, @document.backend_doc)
         Backend.add_namespace_definition(el, prefix, ns) if ns
 
-        wrapper = wrap(el)
+        wrapper = build_element_wrapper(el, namespace: ns, local_name: local)
         wrapper.__internal_set_namespace__(ns, prefix, local, qualified_name)
         wrapper
       end
@@ -102,27 +147,44 @@ module Dommy
 
       def query_selector(selector)
         return nil if selector.nil?
-        Internal.validate_selector!(selector)
 
-        wrap(@document.nokogiri_doc.at_css(Internal.backend_safe_selector(selector.to_s), CSS_PSEUDO_HANDLERS))
+        key = selector.to_s
+        hit = query_cache_get(:first, key)
+        return hit.first if hit # [result] tuple — distinguishes a cached nil match from a miss
+
+        ast = Internal::SelectorParser.parse!(selector)
+        result = Internal::SelectorMatcher.query_first(@document, ast)
+        query_cache_set(:first, key, [result])
+        result
       end
 
       def query_selector_all(selector)
         return NodeList.new if selector.nil?
-        Internal.validate_selector!(selector)
 
-        NodeList.new(@document.nokogiri_doc.css(Internal.backend_safe_selector(selector.to_s), CSS_PSEUDO_HANDLERS).map { |node| wrap(node) }.compact)
+        key = selector.to_s
+        hit = query_cache_get(:all, key)
+        return NodeList.new(hit) if hit # NodeList.new copies, so the cached array is never aliased
+
+        ast = Internal::SelectorParser.parse!(selector)
+        matches = Internal::SelectorMatcher.query(@document, ast)
+        query_cache_set(:all, key, matches)
+        NodeList.new(matches)
       end
 
       def get_element_by_id(id)
         return nil if id.nil? || id.to_s.empty?
 
-        wrap(@document.nokogiri_doc.at_css("##{id}"))
+        # getElementById matches the `id` attribute literally — it is NOT a CSS
+        # selector, so an id with selector-special characters (e.g. React's
+        # `useId` values like `:rjm:`) is valid and must still resolve. Escape it
+        # to a valid id-selector ident before handing it to the backend's CSS
+        # engine (a raw "##{id}" would be an invalid selector and raise).
+        wrap(@document.backend_doc.at_css("##{Dommy::CSSNamespace.escape(id)}"))
       end
 
       def get_elements_by_tag_name(name)
         n = name.to_s.downcase
-        doc = @document.nokogiri_doc
+        doc = @document.backend_doc
         cache = self
         if n == "*"
           HTMLCollection.new { doc.css("*").map { |x| cache.wrap(x) }.compact }
@@ -132,7 +194,7 @@ module Dommy
       end
 
       def get_elements_by_name(name)
-        doc = @document.nokogiri_doc
+        doc = @document.backend_doc
         cache = self
         key = name.to_s
         HTMLCollection.new do
@@ -142,7 +204,7 @@ module Dommy
 
       def get_elements_by_class_name(name)
         tokens = name.to_s.split(/\s+/).reject(&:empty?)
-        doc = @document.nokogiri_doc
+        doc = @document.backend_doc
         cache = self
         HTMLCollection.new do
           next [] if tokens.empty?
@@ -154,7 +216,7 @@ module Dommy
 
       # Clear cached wrapper (used by customElements.define for upgrades)
       def reset_wrapper(nokogiri_node)
-        @wrappers.delete(nokogiri_node.object_id)
+        @wrappers.delete(identity_key(nokogiri_node))
       end
 
       # Register an externally-built wrapper. Used by
@@ -162,11 +224,60 @@ module Dommy
       # document so the existing Ruby object survives the move
       # rather than being replaced by a freshly-built one.
       def register(nokogiri_node, wrapper)
-        @wrappers[nokogiri_node.object_id] = wrapper
+        @wrappers[identity_key(nokogiri_node)] = wrapper
       end
 
       private
 
+      # Whether a cached wrapper still describes the node now at its identity
+      # key. A pure class→nodeType lookup: it must NOT dereference the wrapper's
+      # backend node, which may be a freed pointer after identity recycling.
+      # Unknown/exotic wrappers (Document, ShadowRoot, …) aren't produced by the
+      # fragment-parse paths that recycle identities, so we trust those entries
+      # rather than rebuild.
+      def cached_wrapper_live?(wrapper, node)
+        return true unless node.respond_to?(:node_type)
+
+        expected =
+          case wrapper
+          when Fragment then 11
+          when CDATASectionNode then 4 # subclass of TextNode — test first
+          when TextNode then 3
+          when CommentNode then 8
+          when ProcessingInstructionNode then 7
+          else
+            return true unless wrapper.is_a?(Element)
+
+            1
+          end
+        expected == node.node_type
+      end
+
+      # The cached value for [kind, selector] if it was computed in the current
+      # DOM generation, else nil (a miss, or a stale entry the caller recomputes).
+      def query_cache_get(kind, selector)
+        entry = @query_cache[[kind, selector]]
+        return nil unless entry && entry[0] == @document.style_generation
+
+        entry[1]
+      end
+
+      # Store `value` for [kind, selector] tagged with the current generation,
+      # clearing the cache wholesale if it has grown past the cap.
+      def query_cache_set(kind, selector, value)
+        @query_cache.clear if @query_cache.size >= QUERY_CACHE_CAP
+        @query_cache[[kind, selector]] = [@document.style_generation, value]
+      end
+
+      # DOM identity key for a backend node, delegated to the backend since
+      # the right key differs: Nokogiri reuses one Ruby wrapper per C node
+      # (object_id stable) and may recycle a freed node's pointer, so it keys
+      # on object_id; Makiri mints fresh wrappers but never frees nodes, so it
+      # keys on the stable node pointer (pointer_id).
+      def identity_key(node)
+        Backend.identity_key(node)
+      end
+
       # WebIDL DOMString coercion for a name/qualifiedName argument: JS
       # `undefined` → "undefined", JS `null` (Ruby nil) → "null", else #to_s.
       def domstring(value)
@@ -191,19 +302,45 @@ module Dommy
           TextNode.new(@document, node)
         when Backend.comment_class
           CommentNode.new(@document, node)
+        when Backend.processing_instruction_class
+          ProcessingInstructionNode.new(@document, node)
         when Backend.document_fragment_class
           Fragment.new(@document, node)
         end
       end
 
-      def build_element_wrapper(node)
+      # `namespace`/`local_name` let a caller that already knows the element's
+      # namespace and local name (e.g. createElementNS, which preserves case and
+      # carries a prefix the backend node name would otherwise fold in) route the
+      # wrapper class directly, rather than re-deriving it from the backend.
+      #
+      # When `namespace` is not supplied we derive it: the backend reports the
+      # null namespace for ordinary HTML elements, so in an HTML document an
+      # otherwise-namespaceless element is treated as HTML-namespaced (preserving
+      # HTML* interface routing); a non-HTML document leaves it null (generic
+      # Element). An explicit `namespace:` (including nil from createElementNS)
+      # is honored verbatim.
+      def build_element_wrapper(node, namespace: NAMESPACE_UNSET, local_name: nil)
+        ns =
+          if namespace.equal?(NAMESPACE_UNSET)
+            Backend.namespace_of(node)&.href || (@document.html_document? ? Element::HTML_NAMESPACE : nil)
+          else
+            namespace
+          end
+        # A JS-defined custom element (`customElements.define(name, classExpr)`
+        # from page script) registers its JS constructor — a HostCallback — not a
+        # Ruby class, so we cannot `.new(@document, node)` it. Wrap such a node as
+        # its plain built-in element instead (its server-rendered light-DOM
+        # content still displays; the JS upgrade is simply not run). Only a Ruby
+        # class definition routes a custom Ruby wrapper + #construct.
         custom_klass = custom_element_class_for(node.name)
-        klass = custom_klass || Dommy.element_class_for(node.name, Backend.namespace_of(node)&.href)
+        ruby_custom = custom_klass if custom_klass.is_a?(::Class)
+        klass = ruby_custom || Dommy.element_class_for(local_name || node.name, ns)
         instance = klass.new(@document, node)
 
-        @wrappers[node.object_id] = instance
+        @wrappers[identity_key(node)] = instance
 
-        if custom_klass && instance.respond_to?(:construct)
+        if ruby_custom && instance.respond_to?(:construct)
           begin
             instance.construct
           rescue StandardError

data/lib/dommy/internal/parent_node.rb

@@ -14,7 +14,8 @@ module Dommy
       # `appendChild(child)` — detach the node(s) from any current parent
       # and append to the end of this node's child list.
       def append_child(child)
-        check_insertion!(child)
+        coerce_node_argument!(child)
+        ensure_pre_insertion_validity!(child, nil)
         nodes = detach_dom_nodes(child)
         nodes.each { |n| @__node__.add_child(n) }
         notify_child_list(added: nodes)
@@ -23,6 +24,7 @@ module Dommy
 
       # ParentNode#append — mixed Node/String args appended in order.
       def append(*args)
+        validate_insertion_args!(args)
         nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
         nodes.each { |n| @__node__.add_child(n) }
         notify_child_list(added: nodes)
@@ -31,6 +33,7 @@ module Dommy
 
       # ParentNode#prepend — insert before the current first child.
       def prepend(*args)
+        validate_insertion_args!(args)
         nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
         anchor = @__node__.children.first
         if anchor
@@ -45,6 +48,7 @@ module Dommy
       # ParentNode#replaceChildren — remove all existing children, then
       # append the new set. One mutation record carries both sides.
       def replace_children(*args)
+        validate_insertion_args!(args)
         removed = @__node__.children.to_a
         removed.each(&:unlink)
         nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
@@ -78,20 +82,37 @@ module Dommy
       # be defined before the including class bodies run.
       def detach_dom_nodes(value)
         case value
-        when Element, TextNode, CommentNode
-          [detach_with_notify(value.__dommy_backend_node__)]
         when Fragment
-          value.extract_children
+          value.extract_children.map { |n| adopt_into_document(n) }
         when String
           [@document.create_text_node(value).__dommy_backend_node__]
         else
           node = value.respond_to?(:__dommy_backend_node__) ? value.__dommy_backend_node__ : nil
           return [] unless node
 
-          [detach_with_notify(node)]
+          # WHATWG pre-insert adopts the node into this node's document before
+          # linking it. libxml2 reassigns ownership in place during add_child, so
+          # the explicit adopt is a no-op move there; Makiri can't move a node
+          # between document arenas, so a cross-document insert must adopt (an
+          # imported copy) first. adopt_node reseats the Dommy wrapper onto the
+          # adopted node, so JS identity (`parent.appendChild(x); x` ===
+          # `parent.lastChild`) survives. Same-document: the wrapper's backend
+          # node is unchanged, so this is identical to the previous behavior.
+          detach_with_notify(node)
+          [@document.adopt_node(value).__dommy_backend_node__]
         end
       end
 
+      # Bring a raw backend node into this node's document (WHATWG adopt). A
+      # no-op when already same-document; otherwise Backend.adopt — in place for
+      # Nokogiri, an imported copy for Makiri (which can't move nodes between
+      # arenas). Used for fragment children, which have no standalone wrapper to
+      # reseat.
+      def adopt_into_document(node)
+        target = @document.backend_doc
+        node.document == target ? node : Backend.adopt(node, target)
+      end
+
       # Detach a node from its current parent, queuing a childList removal
       # record on that old parent first (WHATWG "remove" runs before the
       # subsequent insert, so moving a node yields a removal record + an addition
@@ -121,6 +142,62 @@ module Dommy
       def check_insertion!(_child)
         nil
       end
+
+      # WebIDL coercion for an `appendChild`/`insertBefore`/`replaceChild`
+      # argument typed `Node`: a null / undefined / non-Node value is a
+      # TypeError before any DOM step runs.
+      def coerce_node_argument!(value)
+        return value if value.is_a?(Dommy::Node)
+
+        raise Bridge::TypeError, "Argument is not a Node."
+      end
+
+      # WHATWG "ensure pre-insertion validity" for an element-like parent
+      # (Element / DocumentFragment / ShadowRoot — never a Document, so the
+      # document-only constraints in step 6 don't apply here). Steps run in
+      # spec order so the observable error matches: ancestor check (2), the
+      # reference child's parentage (3), the node's type (4), then the doctype
+      # placement rule (5).
+      def ensure_pre_insertion_validity!(node, child)
+        # Step 2 — node must not be an inclusive ancestor of this parent.
+        check_insertion!(node)
+
+        # Step 3 — a non-null reference child must be a child of this parent.
+        unless child.nil? || (defined?(Bridge::UNDEFINED) && child.equal?(Bridge::UNDEFINED))
+          ref = child.respond_to?(:__dommy_backend_node__) ? child.__dommy_backend_node__ : nil
+          unless ref && ref.parent == @__node__
+            raise DOMException::NotFoundError, "The reference child is not a child of this node."
+          end
+        end
+
+        # Step 4 — only an insertable node type may be inserted.
+        unless insertable_child?(node)
+          raise DOMException::HierarchyRequestError, "This node type cannot be inserted here."
+        end
+
+        # Step 5 — a doctype may only be a child of a document, never of an
+        # element-like parent.
+        return unless node.is_a?(Dommy::DocumentType)
+
+        raise DOMException::HierarchyRequestError, "A doctype may only be a child of a document."
+      end
+
+      # Validate each Node argument of append / prepend / replaceChildren (which
+      # also accept DOMStrings — those are always insertable as text, so skip
+      # anything that isn't a Node).
+      def validate_insertion_args!(args)
+        args.each { |arg| ensure_pre_insertion_validity!(arg, nil) if arg.is_a?(Dommy::Node) }
+      end
+
+      # The node types that may be inserted under an element-like parent:
+      # DocumentFragment, DocumentType, Element, and CharacterData (Text /
+      # Comment / CDATASection / ProcessingInstruction — all CharacterDataNode
+      # subclasses). A Document or Attr is not insertable.
+      def insertable_child?(value)
+        value.is_a?(Dommy::Element) || value.is_a?(Dommy::Fragment) ||
+          value.is_a?(Dommy::CharacterDataNode) ||
+          value.is_a?(Dommy::DocumentType)
+      end
     end
   end
 end

data/lib/dommy/internal/selector_ast.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Internal
+    module SelectorAST
+      Specificity = Struct.new(:a, :b, :c) do
+        def +(other)
+          self.class.new(a + other.a, b + other.b, c + other.c)
+        end
+
+        def to_a = [a, b, c]
+
+        def <=>(other)
+          to_a <=> other.to_a
+        end
+      end
+
+      ZERO = Specificity.new(0, 0, 0).freeze
+      ID = Specificity.new(1, 0, 0).freeze
+      CLASS = Specificity.new(0, 1, 0).freeze
+      TYPE = Specificity.new(0, 0, 1).freeze
+
+      SelectorList = Struct.new(:selectors) do
+        def specificity
+          selectors.map(&:specificity).max || ZERO
+        end
+      end
+
+      ComplexSelector = Struct.new(:parts) do
+        def rightmost = parts.last&.compound
+
+        def pseudo_element
+          rightmost&.pseudo_element
+        end
+
+        def pseudo_element?
+          !pseudo_element.nil?
+        end
+
+        def without_pseudo_element
+          return self unless pseudo_element?
+
+          duped = parts.map { |part| Part.new(part.combinator, part.compound) }
+          last = duped.last
+          last.compound = last.compound.without_pseudo_element
+          self.class.new(duped)
+        end
+
+        def specificity
+          parts.reduce(ZERO) { |sum, part| sum + part.compound.specificity }
+        end
+      end
+
+      Part = Struct.new(:combinator, :compound)
+      RelativeSelector = Struct.new(:leading_combinator, :complex)
+
+      CompoundSelector = Struct.new(:type, :subclass_selectors, :pseudo_element) do
+        def without_pseudo_element
+          self.class.new(type, subclass_selectors, nil)
+        end
+
+        def specificity
+          sum = type ? type.specificity : ZERO
+          subclass_selectors.each { |selector| sum += selector.specificity }
+          sum += pseudo_element.specificity if pseudo_element
+          sum
+        end
+      end
+
+      TypeSelector = Struct.new(:namespace, :name) do
+        def specificity = TYPE
+      end
+
+      UniversalSelector = Struct.new(:namespace) do
+        def specificity = ZERO
+      end
+
+      IdSelector = Struct.new(:value) do
+        def specificity = ID
+      end
+
+      ClassSelector = Struct.new(:value) do
+        def specificity = CLASS
+      end
+
+      AttributeSelector = Struct.new(:namespace, :name, :matcher, :value, :case_flag) do
+        def specificity = CLASS
+      end
+
+      PseudoClass = Struct.new(:name, :argument) do
+        def specificity
+          case name
+          when "is", "not", "has"
+            argument_specificity
+          when "where"
+            ZERO
+          when "nth-child", "nth-last-child"
+            CLASS + (argument&.of_selector_list&.specificity || ZERO)
+          else
+            CLASS
+          end
+        end
+
+        private
+
+        def argument_specificity
+          if argument.respond_to?(:specificity)
+            argument.specificity
+          elsif argument.respond_to?(:map)
+            argument.map { |item| item.respond_to?(:complex) ? item.complex.specificity : ZERO }.max || ZERO
+          else
+            ZERO
+          end
+        end
+      end
+
+      PseudoElement = Struct.new(:name, :argument) do
+        def specificity = TYPE
+      end
+
+      NthExpression = Struct.new(:a, :b, :of_selector_list)
+    end
+  end
+end