dommy 0.9.0 → 0.10.0

data/lib/dommy/internal/global_functions.rb

@@ -1,32 +1,45 @@
 # frozen_string_literal: true
 
-require "cgi"
-require "erb"
 require "base64"
 
+require_relative "url_parser"
+
 module Dommy
   module Internal
     # Stateless global functions exposed on the JS global (Window) that don't
-    # depend on any window state. Kept here so Window doesn't carry the cgi/erb
-    # dependency just for URI component encoding.
+    # depend on any window state.
     module GlobalFunctions
       module_function
 
-      # JS `encodeURIComponent`: percent-encode everything except
-      # `A-Za-z0-9 - _ . ! ~ * ' ( )`. `ERB::Util.url_encode` matches this,
-      # unlike `CGI.escape` (which uses `+` for space).
+      # WebIDL DOMString conversion of a JS value: null → "null", undefined →
+      # "undefined", booleans → "true"/"false", everything else its string form.
+      # (Ruby's `nil.to_s` is "", which would silently drop a `btoa(null)` arg.)
+      def js_domstring(value)
+        return "null" if value.nil?
+        return "undefined" if defined?(Bridge::UNDEFINED) && value.equal?(Bridge::UNDEFINED)
+
+        value.to_s
+      end
+
+      # JS `encodeURIComponent`: UTF-8 percent-encode everything except the
+      # unreserved marks `A-Za-z0-9 - _ . ! ~ * ' ( )`. (Neither
+      # `ERB::Util.url_encode` nor `CGI.escape` matches this set — the former
+      # encodes `!~*'()`, the latter uses `+` for space.)
       def encode_uri_component(value)
-        ERB::Util.url_encode(value.to_s)
+        value.to_s.b.gsub(/[^A-Za-z0-9\-_.!~*'()]/n) { |c| format("%%%02X", c.ord) }
       end
 
+      # JS `decodeURIComponent`: percent-decode only — unlike form-urlencoded
+      # decoding, "+" stays a literal "+". Malformed UTF-8 becomes U+FFFD
+      # (a real engine throws URIError; nothing downstream relies on that).
       def decode_uri_component(value)
-        CGI.unescape(value.to_s)
+        UrlParser.percent_decode(value.to_s).force_encoding(Encoding::UTF_8).scrub("\u{FFFD}")
       end
 
       # JS `btoa`: base64-encode a binary (Latin1) string. Each code unit must be
       # 0..255; anything beyond Latin1 is an InvalidCharacterError (per spec).
       def btoa(value)
-        codepoints = value.to_s.codepoints
+        codepoints = js_domstring(value).codepoints
         if codepoints.any? { |c| c > 0xFF }
           raise DOMException::InvalidCharacterError.new(
             "Failed to execute 'btoa': characters outside the Latin1 range cannot be base64-encoded."

data/lib/dommy/internal/mutation_coordinator.rb

@@ -144,14 +144,23 @@ module Dommy
         nk.children.each { |c| notify_disconnected_subtree(c) } if nk.respond_to?(:children)
       end
 
-      def notify_attribute_changed(element, name, old_value, new_value)
+      def notify_attribute_changed(element, name, old_value, new_value, namespace = nil)
         return unless element&.respond_to?(:attribute_changed_callback)
 
         klass = element.class
         return unless klass.respond_to?(:observed_attributes)
         return unless klass.observed_attributes.include?(name.to_s.downcase)
 
-        element.attribute_changed_callback(name, old_value, new_value)
+        # attributeChangedCallback's 4th arg is the attribute's namespace (null
+        # for a plain HTML attribute). Pass it only to callbacks that accept it
+        # (the JS bridge, or a 4-arg Ruby callback) so existing 3-arg Ruby custom
+        # elements keep working.
+        cb = element.method(:attribute_changed_callback)
+        if cb.arity.negative? || cb.arity >= 4
+          element.attribute_changed_callback(name, old_value, new_value, namespace)
+        else
+          element.attribute_changed_callback(name, old_value, new_value)
+        end
       rescue StandardError
         nil
       end
@@ -169,13 +178,24 @@ module Dommy
         return nil unless target
         return nil if added_nodes.empty? && removed_nodes.empty?
 
+        # Custom Element connected/disconnected callbacks, script execution, and
+        # blank-iframe load all require the subtree to be connected to the
+        # document (the script/iframe paths already check is_connected?, and
+        # connectedCallback fires only when connected). So skip the O(subtree)
+        # walk for mutations within a still-detached tree — the common case
+        # during bulk DOM construction, where nothing in the walk can fire.
+        if !target.respond_to?(:is_connected?) || target.is_connected?
+          added_nodes.each { |nk| notify_connected_subtree(nk) }
+          removed_nodes.each { |nk| notify_disconnected_subtree(nk) }
+        end
+
+        # MutationRecords are only needed when something is observing; skip the
+        # eager wrapping + record entirely when no observer is registered.
+        return nil unless @observer_manager.any?
+
         wrapped_added = added_nodes.map { |node| @document.wrap_node(node) }.compact
         wrapped_removed = removed_nodes.map { |node| @document.wrap_node(node) }.compact
 
-        # Fire Custom Element lifecycle callbacks (synchronous, before MutationObserver microtask)
-        added_nodes.each { |nk| notify_connected_subtree(nk) }
-        removed_nodes.each { |nk| notify_disconnected_subtree(nk) }
-
         # Capture previousSibling / nextSibling (the position within target)
         prev_w = previous_sibling
         next_w = next_sibling
@@ -223,7 +243,7 @@ module Dommy
         new_value = target_node[attr]
 
         # Custom Element attributeChangedCallback (synchronous)
-        notify_attribute_changed(target, attr, old_value, new_value)
+        notify_attribute_changed(target, attr, old_value, new_value, namespace)
 
         @observer_manager.observers_matching(target).each do |observer|
           entry = observer.find_matching_entry(target)

data/lib/dommy/internal/node_wrapper_cache.rb

@@ -115,14 +115,14 @@ module Dommy
         # 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)
+        Attr.new(str, document: @document)
       end
 
       def create_attribute_ns(namespace_uri, qualified_name)
         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)
-        Attr.new(qualified_name, namespace_uri: ns, prefix: prefix, local_name: local)
+        Attr.new(qualified_name, namespace_uri: ns, prefix: prefix, local_name: local, document: @document)
       end
 
       def create_element_ns(namespace_uri, qualified_name)
@@ -135,7 +135,17 @@ module Dommy
         qualified_name = domstring(qualified_name)
         ns, prefix, local = Namespaces.validate_and_extract(namespace_uri, qualified_name, context: :element)
 
-        el = Backend.create_element(qualified_name, @document.backend_doc)
+        # An XML backend rejects some DOM-valid qualified names (an invalid char
+        # in the local part, which DOM permits): the loose creator builds them
+        # verbatim. A genuinely invalid name it (or the strict path) rejects with
+        # an ArgumentError becomes an InvalidCharacterError, per DOM.
+        el =
+          begin
+            Backend.create_element_loose(qualified_name, prefix, local, ns, @document.backend_doc) ||
+              Backend.create_element(qualified_name, @document.backend_doc)
+          rescue ArgumentError
+            raise DOMException::InvalidCharacterError, "'#{qualified_name}' is not a valid element name"
+          end
         Backend.add_namespace_definition(el, prefix, ns) if ns
 
         wrapper = build_element_wrapper(el, namespace: ns, local_name: local)
@@ -143,6 +153,18 @@ module Dommy
         wrapper
       end
 
+      # Wrap a freshly-cloned backend element whose original was built via
+      # createElementNS: route the wrapper class by the known local name (the
+      # backend node name may be the full qualified name, e.g. "foo:div", which
+      # would otherwise resolve to HTMLUnknownElement) and reapply its namespace
+      # metadata (namespaceURI / prefix / localName / tagName).
+      def wrap_cloned_element_ns(node, namespace, prefix, local, qualified_name)
+        reset_wrapper(node)
+        wrapper = build_element_wrapper(node, namespace: namespace, local_name: local)
+        wrapper.__internal_set_namespace__(namespace, prefix, local, qualified_name)
+        wrapper
+      end
+
       # Query methods
 
       def query_selector(selector)
@@ -183,14 +205,7 @@ module Dommy
       end
 
       def get_elements_by_tag_name(name)
-        n = name.to_s.downcase
-        doc = @document.backend_doc
-        cache = self
-        if n == "*"
-          HTMLCollection.new { doc.css("*").map { |x| cache.wrap(x) }.compact }
-        else
-          HTMLCollection.new { doc.css(n).map { |x| cache.wrap(x) }.compact }
-        end
+        HTMLCollection.elements_by_tag_name(@document.backend_doc, @document, name)
       end
 
       def get_elements_by_name(name)
@@ -202,15 +217,27 @@ module Dommy
         end
       end
 
+      # DOM "ASCII whitespace" (https://infra.spec.whatwg.org/#ascii-whitespace):
+      # TAB, LF, FF, CR, SPACE — NOT Ruby's `\s` (which also matches VT / U+000B)
+      # and NOT any Unicode space (U+00A0, U+2000…). Class tokens split on exactly
+      # this set, so a class of a single U+000B or U+00A0 is ONE token.
+      ASCII_WHITESPACE = /[\t\n\f\r ]+/
+
       def get_elements_by_class_name(name)
-        tokens = name.to_s.split(/\s+/).reject(&:empty?)
+        tokens = name.to_s.split(ASCII_WHITESPACE).reject(&:empty?)
         doc = @document.backend_doc
         cache = self
         HTMLCollection.new do
           next [] if tokens.empty?
 
-          selector = tokens.map { |t| ".#{t}" }.join("")
-          doc.css(selector).map { |n| cache.wrap(n) }.compact
+          # Match class tokens directly rather than composing a `.tok` CSS
+          # selector string — an exotic class token (control chars, Unicode
+          # spaces, quotes) can't be safely embedded in a selector, and the
+          # split must be ASCII-whitespace, not the CSS engine's tokenization.
+          doc.css("[class]").select do |n|
+            classes = n["class"].to_s.split(ASCII_WHITESPACE)
+            tokens.all? { |t| classes.include?(t) }
+          end.map { |n| cache.wrap(n) }.compact
         end
       end
 
@@ -219,6 +246,13 @@ module Dommy
         @wrappers.delete(identity_key(nokogiri_node))
       end
 
+      # The cached wrapper for `node`, or nil — WITHOUT creating one (unlike
+      # #wrap). Used by cross-document adoption to find the live descendant
+      # wrappers that must be reseated onto the imported copy.
+      def peek(node)
+        node && @wrappers[identity_key(node)]
+      end
+
       # Register an externally-built wrapper. Used by
       # Document#adopt_node when migrating a wrapper from another
       # document so the existing Ruby object survives the move
@@ -293,6 +327,12 @@ module Dommy
 
       def build_wrapper_for(node)
         case node
+        when Backend.document_class
+          # The backend document node has no wrapper of its own — map it to the
+          # Dommy Document that owns this cache, so a top-level node's parentNode /
+          # getRootNode resolves to the document (documentElement.parentNode ===
+          # document), matching the DOM tree.
+          @document
         when Backend.element_class
           build_element_wrapper(node)
         when ->(n) { Backend.cdata_class && n.is_a?(Backend.cdata_class) }
@@ -306,6 +346,8 @@ module Dommy
           ProcessingInstructionNode.new(@document, node)
         when Backend.document_fragment_class
           Fragment.new(@document, node)
+        when ->(n) { (dt = Backend.document_type_class) && n.is_a?(dt) }
+          DocumentType.new(backend_node: node, document: @document)
         end
       end
 

data/lib/dommy/internal/observer_manager.rb

@@ -26,6 +26,12 @@ module Dommy
       def all
         @observers.dup
       end
+
+      # True when at least one observer is registered — a cheap gate so a
+      # mutation with no observers skips building MutationRecords entirely.
+      def any?
+        !@observers.empty?
+      end
     end
   end
 end

data/lib/dommy/internal/observer_matcher.rb

@@ -4,9 +4,8 @@ module Dommy
   module Internal
     # Matches a mutation target against an observed node based on observer options.
     # Works exclusively with wrapped DOM nodes (not Nokogiri internals).
-    class ObserverMatcher
-      def initialize
-      end
+    module ObserverMatcher
+      module_function
 
       # Does this observer's target scope match the mutation target?
       # Returns true if:
@@ -20,11 +19,10 @@ module Dommy
         observed_wrapped.contains?(target_wrapped)
       end
 
-      # Special case: Document observation
-      # Matches if subtree=false (never) or target is in document (always)
-      def matches_document?(target_wrapped, subtree:)
-        return true if subtree
-        false
+      # Special case: Document observation. Matches iff subtree=true
+      # (a plain target==observed match never applies to a Document).
+      def matches_document?(_target_wrapped, subtree:)
+        subtree
       end
     end
   end

data/lib/dommy/internal/parent_node.rb

@@ -11,6 +11,11 @@ module Dommy
     # coordinator already no-ops on empty added/removed sets and on an
     # unwrappable target, so callers may invoke it unconditionally.
     module ParentNode
+      # Argument coercion (`detach_dom_nodes`), childList notification, and the
+      # ChildNode `before`/`after`/`replaceWith` surface all live in ChildNode,
+      # shared with the leaf CharacterData nodes.
+      include ChildNode
+
       # `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)
@@ -37,7 +42,10 @@ module Dommy
         nodes = args.flat_map { |arg| detach_dom_nodes(arg) }
         anchor = @__node__.children.first
         if anchor
-          nodes.reverse_each { |n| anchor.add_previous_sibling(n) }
+          # Insert each node before the (fixed) original first child in order:
+          # forward iteration keeps document order (n1, n2, … then the old first
+          # child). Reversing here would emit them backwards.
+          nodes.each { |n| anchor.add_previous_sibling(n) }
         else
           nodes.each { |n| @__node__.add_child(n) }
         end
@@ -57,84 +65,40 @@ module Dommy
         nil
       end
 
-      private
+      # Node#normalize — merge each run of adjacent exclusive Text descendants
+      # into its first node (preserving that node's identity, so a JS reference
+      # to it survives) and drop empty Text nodes. Recurses the whole subtree,
+      # so it works for Element, DocumentFragment, and ShadowRoot alike.
+      def normalize
+        text_nodes = []
+        @__node__.traverse { |node| text_nodes << node if node.respond_to?(:text?) && node.text? }
 
-      # Centralized MutationObserver childList notification. Defaults the
-      # target to this node; beforebegin/afterend/replaceWith/outerHTML
-      # callers pass the parent explicitly. The coordinator filters out
-      # empty added/removed sets, so this is always safe to call.
-      def notify_child_list(added: [], removed: [], target: @__node__)
-        @document.notify_child_list_mutation(
-          target_node: target,
-          added_nodes: added,
-          removed_nodes: removed
-        )
-      end
+        text_nodes.each do |node|
+          next unless node.parent # already removed as part of an earlier run
 
-      # Coerce an append/prepend/replaceChildren argument into raw Nokogiri
-      # node(s), detached from any current parent:
-      #   - Element / TextNode / CommentNode → its backing node (unlinked)
-      #   - Fragment                          → its extracted children
-      #   - String                            → a fresh text node
-      #   - anything else with a backing node → that node (unlinked)
-      #
-      # The class constants resolve at call time, so the mixin only needs to
-      # be defined before the including class bodies run.
-      def detach_dom_nodes(value)
-        case value
-        when Fragment
-          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
-
-          # 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__]
+          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
-      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)
+        nil
       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
-      # record). Returns the raw node, ready to be re-linked.
-      def detach_with_notify(node)
-        old_parent = node.parent
-        return node unless old_parent
-
-        # Capture the position (as wrapped nodes — the coordinator records
-        # explicit siblings verbatim) before unlinking.
-        prev_sib = node.previous_sibling && @document.wrap_node(node.previous_sibling)
-        next_sib = node.next_sibling && @document.wrap_node(node.next_sibling)
-        node.unlink
-        @document.notify_child_list_mutation(
-          target_node: old_parent,
-          added_nodes: [],
-          removed_nodes: [node],
-          previous_sibling: prev_sib,
-          next_sibling: next_sib
-        )
-        node
-      end
+      private
 
       # Hierarchy guard hook. Default no-op (Fragment / ShadowRoot stay
       # permissive, matching current behavior). Element overrides this to

data/lib/dommy/internal/selector_matcher.rb

@@ -358,6 +358,12 @@ module Dommy
         when "hover"
           hovered = element.owner_document&.__internal_hovered_element__
           hovered && (element.equal?(hovered) || element.contains?(hovered))
+        when "invalid" then constraint_invalid?(element)
+        when "valid" then constraint_valid?(element)
+        when "required" then form_control_required?(element)
+        when "optional" then form_control_optional?(element)
+        when "read-only" then read_only_element?(element)
+        when "read-write" then read_write_element?(element)
         when "active", "visited" then false # supported-but-currently-false (no pointer state / history)
         when "dir" then dir_match?(element, pseudo.argument)
         when "target" then element.get_attribute("id").to_s == Internal.target_id(element.owner_document).to_s && !Internal.target_id(element.owner_document).nil?
@@ -642,6 +648,89 @@ module Dommy
         %w[button input select textarea optgroup option fieldset].include?(element.local_name.to_s.downcase)
       end
 
+      # A candidate for constraint validation: a form-associated control whose
+      # `willValidate` is true (not disabled / readonly / barred).
+      def validation_candidate?(element)
+        element.respond_to?(:will_validate) && element.respond_to?(:validity) && element.will_validate
+      end
+
+      # `:invalid` / `:valid` apply to candidates (by their validity) and to a
+      # form / fieldset (by whether any descendant candidate is invalid).
+      def constraint_invalid?(element)
+        name = element.local_name.to_s.downcase
+        if %w[form fieldset].include?(name)
+          descendant_candidates(element).any? { |c| !c.validity.valid }
+        else
+          validation_candidate?(element) && !element.validity.valid
+        end
+      end
+
+      def constraint_valid?(element)
+        name = element.local_name.to_s.downcase
+        if %w[form fieldset].include?(name)
+          descendant_candidates(element).all? { |c| c.validity.valid }
+        else
+          validation_candidate?(element) && element.validity.valid
+        end
+      end
+
+      def descendant_candidates(element)
+        element.query_selector_all("input, select, textarea, button").select do |c|
+          validation_candidate?(c)
+        end
+      end
+
+      # `:required` / `:optional` apply to input / select / textarea per the
+      # `required` attribute.
+      def requirable_element?(element)
+        %w[input select textarea].include?(element.local_name.to_s.downcase)
+      end
+
+      def form_control_required?(element)
+        requirable_element?(element) && element.has_attribute?("required")
+      end
+
+      def form_control_optional?(element)
+        requirable_element?(element) && !element.has_attribute?("required")
+      end
+
+      # `:read-write` matches an editable control (a mutable text input / textarea,
+      # or an element with contenteditable); `:read-only` is its complement over
+      # the elements the pseudo-classes apply to.
+      def read_write_element?(element)
+        name = element.local_name.to_s.downcase
+        if name == "textarea"
+          return !element.has_attribute?("readonly") && !disabled_element?(element)
+        end
+        if name == "input"
+          return false unless mutable_input_type?(element)
+
+          return !element.has_attribute?("readonly") && !disabled_element?(element)
+        end
+        editable_via_contenteditable?(element)
+      end
+
+      def read_only_element?(element)
+        name = element.local_name.to_s.downcase
+        return !read_write_element?(element) if %w[input textarea].include?(name)
+
+        # For other elements, :read-only matches when not editable.
+        !editable_via_contenteditable?(element)
+      end
+
+      # Text-like input types that can be read-write (not button/checkbox/etc.).
+      def mutable_input_type?(element)
+        %w[text search url tel email password date month week time
+           datetime-local number range color].include?(
+             (element.get_attribute("type") || "text").to_s.downcase
+           )
+      end
+
+      def editable_via_contenteditable?(element)
+        v = element.get_attribute("contenteditable")
+        !v.nil? && v.to_s.downcase != "false"
+      end
+
       def disabled_element?(element)
         return true if element.has_attribute?("disabled")
 

data/lib/dommy/internal/selector_parser.rb

@@ -12,7 +12,8 @@ module Dommy
     # exactly the inputs the spec requires — cases Nokogiri's CSS parser silently
     # accepts (`[*=test]`, `div % p`, `..x`) or rejects with the wrong error.
     #
-    # This only VALIDATES; matching is still delegated to the backend. It is a
+    # `parse!` returns the AST that `SelectorMatcher` matches against (it both
+    # validates and is the matcher's front end). It is a
     # hand-written tokenizer + recursive-descent parser covering the productions
     # the Selectors spec (and the WPT corpus) exercise: selector lists,
     # combinators, type/universal selectors with namespace prefixes, id/class,
@@ -39,6 +40,17 @@ module Dommy
       IDENT_FUNCTIONS = %w[lang dir].to_set.freeze
       NESTED_SELECTOR_FUNCTIONS = %w[host host-context current].to_set.freeze
 
+      # A parsed AST is a pure function of (selector string, namespaces) and never
+      # goes stale as the DOM mutates (unlike the query-result caches, which tag
+      # entries with style_generation). So memoize globally: `matches?` / `closest`
+      # re-parse on every call, and query* re-parse on every cache miss (i.e. after
+      # any mutation), so the same handful of selectors are otherwise re-parsed
+      # constantly. Bounded via the same "clear at cap" idiom as the query caches.
+      # Lock-free plain Hash: `parse!` is pure Ruby (never releases the GVL), so a
+      # read/write is atomic under the GVL — a benign duplicate parse is the worst
+      # a race can cause, matching the existing per-document caches.
+      AST_CACHE_CAP = 2048
+
       module_function
 
       # `namespaces` maps a prefix String to its URI (with the symbol key
@@ -46,9 +58,32 @@ module Dommy
       # stylesheet that declared `@namespace`. nil/empty (the DOM querySelector
       # path) keeps any named prefix undeclared — a SyntaxError, as before.
       def parse!(selector, namespaces: nil)
-        new_parser(selector.to_s, namespaces).parse_selector_list!
-      rescue InvalidSelector => e
-        raise ::Dommy::DOMException::SyntaxError, "'#{selector}' is not a valid selector: #{e.message}"
+        key = [selector.to_s, namespaces]
+        cache = (@ast_cache ||= {})
+        if cache.key?(key)
+          cached = cache[key]
+          # An invalid selector is memoized as its SyntaxError so a repeat still
+          # throws (the message embeds the selector, so re-raising is exact).
+          raise cached if cached.is_a?(::Dommy::DOMException::SyntaxError)
+
+          return cached
+        end
+
+        ast =
+          begin
+            new_parser(selector.to_s, namespaces).parse_selector_list!
+          rescue InvalidSelector => e
+            error = ::Dommy::DOMException::SyntaxError.new("'#{selector}' is not a valid selector: #{e.message}")
+            ast_cache_store(cache, key, error)
+            raise error
+          end
+        ast_cache_store(cache, key, ast)
+        ast
+      end
+
+      def ast_cache_store(cache, key, value)
+        cache.clear if cache.size >= AST_CACHE_CAP
+        cache[key] = value
       end
 
       # Validate `selector`; raise DOMException::SyntaxError if it is not a valid
@@ -451,7 +486,9 @@ module Dommy
         # Validate `name(...)` per the function's argument grammar.
         def consume_function_args!(name, pseudo_element:)
           advance # consume '('
-          arg = consume_function_argument_source
+          # :is()/:where()/:matches() take a forgiving selector list, which may be
+          # empty (matches nothing); other functional pseudos require an argument.
+          arg = consume_function_argument_source(allow_empty: %w[is where matches].include?(name))
           arg_parser = Parser.new(arg, in_has: @in_has, namespaces: @namespaces)
           if pseudo_element
             # ::slotted(<compound>), ::part(<ident>+), ::cue(<selector>), …
@@ -485,7 +522,7 @@ module Dommy
           end
         end
 
-        def consume_function_argument_source
+        def consume_function_argument_source(allow_empty: false)
           skip_ws
           start = @i
           depth = 0
@@ -504,7 +541,7 @@ module Dommy
             advance
           end
           arg = @s[start...@i].to_s.strip
-          fail!("empty function arguments") if arg.empty?
+          fail!("empty function arguments") if arg.empty? && !allow_empty
           advance if peek == ")"
           arg
         end

data/lib/dommy/js/custom_element_bridge.rb

@@ -36,6 +36,17 @@ module Dommy
         nil
       end
 
+      # Direct `new MyElement()`: create a fresh, unattached backing element for a
+      # registered tag (its ownerDocument is the window's document). The JS ctor
+      # is already running, so the element must NOT be re-upgraded — the bridge
+      # crosses it with upgrade suppressed. Returns nil when the tag is undefined.
+      def create(name)
+        return unless @window.respond_to?(:custom_elements)
+        return unless @window.custom_elements.get(name.to_s)
+
+        @window.document.create_element(name.to_s)
+      end
+
       private
 
       # A Dommy custom element class for `name` whose reactions forward to the JS
@@ -82,8 +93,8 @@ module Dommy
         self.class.js_bridge.invoke_lifecycle(self, "adoptedCallback", [])
       end
 
-      def attribute_changed_callback(attr, old_value, new_value)
-        self.class.js_bridge.invoke_lifecycle(self, "attributeChangedCallback", [attr, old_value, new_value])
+      def attribute_changed_callback(attr, old_value, new_value, namespace = nil)
+        self.class.js_bridge.invoke_lifecycle(self, "attributeChangedCallback", [attr, old_value, new_value, namespace])
       end
     end
   end