dommy 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ce9aec097da24f1f6a44792f44615605a1405483b6c6c5183031757d11a0853
-  data.tar.gz: cf7c0e05839c313763590fcdb4d134459f5b1fe91ed1b479f819b18181cf1058
+  metadata.gz: ae1783921d75a534741bfa2de3be6ddd7492f01a6d63d4a3102b85411518e64d
+  data.tar.gz: 3022f80e295f06db17782b034d252e8529435ccae9e7ce7283e936da2cea8804
 SHA512:
-  metadata.gz: 0db6e083fb62dd609fd719264a4d35e6bcadd6b97ce8515d08a8a8a53028e1f3f870224ef40ca33240688ddaf782d41e09d261c079c145144fe7b47b83288ef6
-  data.tar.gz: d33e89e420bf0f93c2e478c93dd9241643ee47c40efa40927ff77714f20b92af561330b2cbedcaa287951cd07aab4ecfb899e24371fe8d6e2b20f289f6973b53
+  metadata.gz: c3ccc2658999f785bab29f01e94bca1d7c0505370256fb55687cca8822b0e4dcdd8efb1d64d172a3a7dced5a3a4224612bc38d8df48f943088d56bd81bc85cd9
+  data.tar.gz: dc65af8b414579d71d72601e1c1f3ac070ed6e4a67a7385cbc17222ed9b896687a494709f974f75af192d2441f12de3cc6be0f4eaaa263198f5bc868335193ab

data/README.md

@@ -1,7 +1,7 @@
 # Dommy
 
-A pure-Ruby DOM polyfill on top of [Nokogiri::HTML5](https://nokogiri.org/) — a Ruby-side analogue to happy-dom / jsdom.
-Dommy exposes browser-like DOM semantics (events, MutationObserver, Custom Elements, Shadow DOM, File API, timers, Storage) so view / component / request specs can verify DOM structure and behavior without spinning up a real browser.
+Dommy is a pure Ruby DOM polyfill built on [Nokogiri::HTML5](https://nokogiri.org/), inspired by happy-dom and jsdom.
+It gives Ruby tests a browser style DOM with events, MutationObserver, Custom Elements, Shadow DOM, the File API, timers, and Storage, without requiring a real browser.
 
 ## Quick start
 
@@ -74,22 +74,24 @@ input.validation_message    #=> "Please fill out this field."
 ### File API (Blob / File / FormData / DataTransfer)
 
 ```ruby
+win = Dommy.parse("<form><input type='file' name='attachment'></form>")
 file = Dommy::File.new(["pdf body"], "doc.pdf", "type" => "application/pdf")
 
 # Seed a file input for tests
-input = dom.query_selector("input[type='file']")
-input.__set_files__([file])
+input = win.document.query_selector("input[type='file']")
+input.__driver_set_files__([file])
 
 # FormData picks it up
-fd = Dommy::FormData.new(dom.query_selector("form"))
+fd = Dommy::FormData.new(win.document.query_selector("form"))
 fd.entries.to_a   #=> [["attachment", #<Dommy::File doc.pdf>]]
 
 # Drag-and-drop simulation
 dt = Dommy::DataTransfer.new(files: [file])
 ev = Dommy::DragEvent.new("drop", "dataTransfer" => dt, "bubbles" => true)
-dropzone.dispatch_event(ev)
+win.document.body.dispatch_event(ev)
 
 # Blob URLs
+blob = Dommy::Blob.new(["blob body"], "type" => "text/plain")
 url = Dommy::URL.create_object_url(blob)   # "blob:dommy/..."
 ```
 
@@ -102,7 +104,7 @@ response = win.__js_call__("fetch", ["/api"]).await
 ```
 
 > [!WARNING]
-> Most Dommy accessors (`Blob#text`, `Response#text`, `localStorage.get_item`) return synchronous Ruby values — not Promises. `.await` is for the JS-bridged async surface.
+> Most Dommy accessors (`Blob#text`, `localStorage.get_item`) return synchronous Ruby values — not Promises. `.await` is only for the JS-bridged async surface (e.g., `fetch()`, `window.__js_call__`). Methods like `Response#text()` are Promise-returning and require `.await`.
 
 ## Test helpers
 
@@ -176,8 +178,7 @@ Supported Capybara-style options: `text:` / `exact:` / `count:` (Integer or Rang
 Implemented:
 
 - Core DOM (Document, Element, Text/Comment/Fragment, NodeList, Attr)
-- 26 specialized HTMLElement subclasses
-- SVG: SVGElement base + ~63 specialized subclasses covering shapes, gradients, marker / mask, the full set of standard filter primitives (Gaussian blur, offset, blend, color matrix, flood, composite, merge, component transfer, tile, morphology, image, drop shadow, turbulence, displacement map, convolve matrix, diffuse / specular lighting + light sources), `<a>` / `<textPath>` / `<view>` / `<switch>` / `<metadata>`, and SMIL animation (`<animate>` / `<animateTransform>` / `<animateMotion>` / `<set>` / `<mpath>` / `<discard>`) — with case-sensitive attribute round-trip
+- Specialized HTML and SVG element classes
 - events with composedPath / AbortSignal
 - MutationObserver (childList / attributes / characterData / subtree)
 - Custom Elements lifecycle
@@ -185,47 +186,38 @@ Implemented:
 - form validation
 - Scheduler (timers + microtasks with `advance_time`)
 - Promise
-- Location / History / URL (WHATWG-leaning parsing with whitespace/tab/newline stripping, percent-encoding of unsafe path chars, `\` → `/` conversion for special schemes, `./` and `../` resolution, IPv4 number forms normalization, ws/wss default port stripping, Punycode hostname encoding, full UTS #46 IDNA with RFC 5893 Bidi and RFC 5892 ContextJ/ContextO)
+- Location / History / URL
 - Storage
-- fetch (stub) / XMLHttpRequest (stub-driven, sync + async, shares the `__fetchy_stub__` fixture map)
-- WebSocket / EventSource — test seams (`__simulate_open__` / `__simulate_message__` / `__simulate_close__`) drive the streams
-- MessageChannel / MessagePort / BroadcastChannel — in-process pub/sub with `structuredClone`-on-transfer
-- FileReader (`readAsText` / `readAsDataURL` / `readAsArrayBuffer` / `readAsBinaryString`)
-- Notification (permission settable via `Notification.__set_permission__`)
-- Geolocation (mock position via `navigator.geolocation.__set_position__`)
-- `window.matchMedia` returning a `MediaQueryList` (`__set_matches__` flips and fires `change`)
-- `requestIdleCallback` / `cancelIdleCallback` (modelled on scheduler), `structuredClone` global
-- `crypto.subtle.digest` (SHA-1/256/384/512), HMAC sign/verify/import/generateKey, and AES-GCM encrypt/decrypt (128/256-bit with additionalData and tagLength options)
-- Streams API (`ReadableStream` / `WritableStream` / `TransformStream` + `TextEncoderStream` / `TextDecoderStream`)
-- `CompressionStream` / `DecompressionStream` (gzip / deflate / deflate-raw via Ruby `Zlib`)
-- Worker (inline-emulated — same-process message round-trip; tests register handlers via `worker.__on_message__`)
-- Performance User Timing (`performance.mark` / `measure` / `getEntriesByName`)
-- `cookieStore` (async Cookie Store API, backed by the same jar `document.cookie` uses)
-- Navigator extras: `share` / `vibrate` / `wakeLock.request` / `getBattery` / `locks` (Web Locks) / `storage.estimate` / `persist` / `persisted` (StorageManager)
-- Layout-adjacent stubs: `element.scrollIntoView` / `scrollTo` / scroll & client / offset metrics (return 0), `getComputedStyle` (inline style passthrough)
-- Popover API (`showPopover` / `hidePopover` / `togglePopover` with `beforetoggle` / `toggle` events)
-- Fullscreen API (`element.requestFullscreen` / `document.exitFullscreen` / `fullscreenchange`)
-- `URLPattern` (pattern matching for URL components — protocol, username, password, hostname, port, pathname, search, hash — with named capture groups and modifiers: `:id`, `*`, `:version+`, `:version?`)
-- `document.startViewTransition` (View Transitions API stub)
+- fetch / XMLHttpRequest stubs
+- WebSocket / EventSource / MessageChannel / BroadcastChannel test doubles
+- FileReader / Notification / Geolocation / `matchMedia`
+- `requestIdleCallback`, `structuredClone`, `URLPattern`
+- Web Crypto, Streams, Compression Streams, Worker
+- `performance`, `cookieStore`, Navigator extras
+- Popover API, Fullscreen API, View Transitions API stub
 - Navigator / Clipboard
 - TreeWalker / NodeIterator / NodeFilter
 - File API (Blob / File / FileList / FormData / DataTransfer)
-- Web Crypto (`crypto.randomUUID`, `getRandomValues`) / TextEncoder / TextDecoder
-- IntersectionObserver / ResizeObserver / PerformanceObserver (test-driven `__trigger__`)
+- IntersectionObserver / ResizeObserver / PerformanceObserver (test-driven `__test_trigger__`)
 - Range / Selection (DOM-level only, no layout)
-- Web Animations API (Animation / KeyframeEffect; lifecycle via scheduler, finished/ready Promises)
+- Web Animations API (Animation / KeyframeEffect)
 - Extended events: Touch / Clipboard / Composition / Wheel / Focus / BeforeUnload / Input / Pointer / Progress / Drag
 
+For implementation notes and tradeoffs, see [design.md](./design.md).
+
 > [!IMPORTANT]
 > Out of scope:
 >
-> - requires a layout / CSS engine or media subsystems: real `getBoundingClientRect` / scroll metrics
-> - CSS scoping (`:host`, `::slotted`, computed styles)
+> - layout and CSS-engine behavior
 > - JS evaluation
 > - Canvas / WebGL / media playback
-> - layout-dependent Range / Selection geometry (`getBoundingClientRect` returns zero rects)
-> - SVG-specific value types (SVGAnimatedLength, SVGTransform, SVGMatrix)
-> - Web Animations: no actual value interpolation — `Animation` is a state machine (`idle` / `running` / `paused` / `finished`) for testing lifecycle and event wiring
+> - layout-dependent Range / Selection geometry
+> - SVG-specific value types
+> - animation value interpolation
+
+## Method naming conventions
+
+See [docs/development.md](./docs/development.md) for method-naming conventions and internal protocols.
 
 ## Running the tests
 

data/lib/dommy/animation.rb

@@ -48,6 +48,8 @@ module Dommy
       end
     end
 
+    include Bridge::Methods
+    js_methods %w[getTiming updateTiming]
     def __js_call__(method, args)
       case method
       when "getTiming"
@@ -217,11 +219,17 @@ module Dommy
         @playback_rate = value.to_f
       when "id"
         @id = value.to_s
+      else
+        return Bridge::UNHANDLED
       end
 
       nil
     end
 
+    include Bridge::Methods
+    js_methods %w[
+      play pause cancel finish reverse addEventListener removeEventListener dispatchEvent
+    ]
     def __js_call__(method, args)
       case method
       when "play"
@@ -237,14 +245,14 @@ module Dommy
       when "addEventListener"
         add_event_listener(args[0], args[1], args[2])
       when "removeEventListener"
-        remove_event_listener(args[0], args[1])
+        remove_event_listener(args[0], args[1], args[2])
       when "dispatchEvent"
         dispatch_event(args[0])
       end
     end
 
     # Event bubbling stops at Animation — it isn't part of the DOM tree.
-    def __event_parent__
+    def __internal_event_parent__
       nil
     end
 

data/lib/dommy/attr.rb

@@ -13,12 +13,32 @@ module Dommy
   #     not yet attached. Value is stored locally; `setAttributeNode`
   #     transfers it to an element.
   class Attr
-    attr_reader :name
+    include Node
+    include EventTarget
 
-    def initialize(name, owner: nil, value: "")
-      @name = name.to_s.downcase
+    attr_reader :name, :namespace_uri, :prefix, :local_name
+
+    def __internal_event_parent__
+      nil
+    end
+
+    def initialize(name, owner: nil, value: "", namespace_uri: nil, prefix: nil, local_name: nil)
+      qname = name.to_s
       @owner = owner
       @detached_value = value.to_s
+      if namespace_uri && !namespace_uri.to_s.empty?
+        # Namespaced attributes preserve case and carry prefix / localName.
+        @name = qname
+        @namespace_uri = namespace_uri.to_s
+        @prefix = prefix
+        @local_name = (local_name || qname.split(":", 2).last).to_s
+      else
+        # Null-namespace (HTML) attributes are lower-cased, as before.
+        @name = qname.downcase
+        @namespace_uri = nil
+        @prefix = nil
+        @local_name = @name
+      end
     end
 
     # The Element this attr is on, or nil if detached.
@@ -28,7 +48,11 @@ module Dommy
 
     def value
       if @owner
-        @owner.__node__[@name].to_s
+        if @namespace_uri
+          Backend.get_attribute_ns(@owner.__dommy_backend_node__, @namespace_uri, @local_name).to_s
+        else
+          @owner.__dommy_backend_node__[@name].to_s
+        end
       else
         @detached_value
       end
@@ -36,7 +60,11 @@ module Dommy
 
     def value=(new_value)
       if @owner
-        @owner.set_attribute(@name, new_value.to_s)
+        if @namespace_uri
+          @owner.set_attribute_ns(@namespace_uri, @name, new_value.to_s)
+        else
+          @owner.set_attribute(@name, new_value.to_s)
+        end
       else
         @detached_value = new_value.to_s
       end
@@ -52,42 +80,77 @@ module Dommy
         @name
       when "nodeValue"
         value
+      when "textContent"
+        # Node.textContent for an Attr returns its value (WHATWG DOM).
+        value
       when "ownerElement"
         @owner
       when "localName"
-        @name
+        @local_name
       when "namespaceURI"
-        nil
+        @namespace_uri
+      when "prefix"
+        @prefix
       when "nodeType"
         2
+      when "specified"
+        # Legacy/useless attribute — always true (WHATWG DOM).
+        true
       end
     end
 
     def __js_set__(key, val)
       case key
-      when "value", "nodeValue"
+      when "value", "nodeValue", "textContent"
         self.value = val
+      else
+        return Bridge::UNHANDLED
       end
 
       nil
     end
 
-    def __js_call__(method, _args)
+    include Bridge::Methods
+    js_methods %w[cloneNode isSameNode getRootNode hasChildNodes normalize compareDocumentPosition
+      appendChild insertBefore removeChild replaceChild
+      addEventListener removeEventListener dispatchEvent]
+    def __js_call__(method, args)
       case method
       when "cloneNode"
-        Attr.new(@name, owner: nil, value: value)
+        Attr.new(@name, owner: nil, value: value,
+                        namespace_uri: @namespace_uri, prefix: @prefix, local_name: @local_name)
+      when "isSameNode"
+        is_same_node(args[0])
+      when "getRootNode"
+        get_root_node(args[0])
+      when "compareDocumentPosition"
+        compare_document_position(args[0])
+      when "appendChild", "insertBefore"
+        raise DOMException::HierarchyRequestError, "an Attr may not have children"
+      when "removeChild", "replaceChild"
+        raise DOMException::NotFoundError, "the node to be removed is not a child of this node"
+      when "hasChildNodes"
+        false
+      when "normalize"
+        nil
+      when "addEventListener"
+        add_event_listener(args[0], args[1], args[2])
+      when "removeEventListener"
+        remove_event_listener(args[0], args[1], args[2])
+      when "dispatchEvent"
+        dispatch_event(args[0])
       end
     end
 
     # Internal: called by Element when the attr is being transferred
     # to (or detached from) an Element.
-    def __attach__(element)
+    def __internal_attach__(element)
       @owner = element
       @detached_value = ""
       nil
     end
 
-    def __detach__
+    def __internal_detach__
       cached = value
       @owner = nil
       @detached_value = cached
@@ -106,49 +169,134 @@ module Dommy
 
     def initialize(element)
       @element = element
+      # Attr-node identity cache, keyed by [namespace_or_nil, localName].
+      # Every accessor (item / index / getNamedItem(NS)) returns the SAME
+      # Attr object for a given underlying attribute, per the DOM.
+      @attrs = {}
     end
 
     def length
-      @element.__node__.attribute_nodes.size
+      Backend.attribute_nodes(@element.__dommy_backend_node__).size
     end
 
     alias size length
 
     def item(index)
-      name = @element.__node__.attribute_nodes[index.to_i]&.name
-      name && Attr.new(name, owner: @element)
+      node = Backend.attribute_nodes(@element.__dommy_backend_node__)[index.to_i]
+      node && attr_for(node)
+    end
+
+    # Return the cached Attr for a backend attribute node, creating (and
+    # caching) one on first access so DOM node identity holds.
+    def attr_for(attr_node)
+      info = Backend.attribute_ns_info(attr_node)
+      key = [info[:namespace_uri], info[:local_name]]
+      cached = @attrs[key]
+      return cached if cached && cached.owner_element.equal?(@element)
+
+      attr = Attr.new(info[:qualified_name], owner: @element,
+                                             namespace_uri: info[:namespace_uri],
+                                             prefix: info[:prefix],
+                                             local_name: info[:local_name])
+      @attrs[key] = attr
+      attr
     end
 
     def get_named_item(name)
       key = name.to_s.downcase
-      return nil unless @element.__node__.key?(key)
-
-      Attr.new(key, owner: @element)
+      node = Backend.attribute_nodes(@element.__dommy_backend_node__).find do |a|
+        Backend.attribute_ns_info(a)[:qualified_name] == key
+      end
+      node && attr_for(node)
     end
 
     def set_named_item(attr)
-      return nil unless attr.is_a?(Attr)
-
-      key = attr.name
-      val = attr.value
-      attr.__attach__(@element)
-      @element.set_attribute(key, val)
-      attr
+      set_attribute_node(attr)
     end
 
     def remove_named_item(name)
       key = name.to_s.downcase
-      return nil unless @element.__node__.key?(key)
+      node = Backend.attribute_nodes(@element.__dommy_backend_node__).find do |a|
+        Backend.attribute_ns_info(a)[:qualified_name] == key
+      end
+      return nil unless node
 
-      attr = Attr.new(key, owner: nil, value: @element.__node__[key].to_s)
+      removed = attr_for(node)
       @element.remove_attribute(key)
-      attr
+      removed
+    end
+
+    def each
+      Backend.attribute_nodes(@element.__dommy_backend_node__).each do |a|
+        yield attr_for(a)
+      end
+    end
+
+    # WHATWG "set an attribute" / "set attribute node". Adopts `attr` (the
+    # exact object — identity is preserved), replacing any attribute with the
+    # same (namespace, localName) and returning the previous Attr (detached),
+    # or nil. Throws InUseAttributeError if `attr` is bound to another element.
+    def set_attribute_node(attr)
+      return nil unless attr.is_a?(Attr)
+
+      owner = attr.owner_element
+      if owner && !owner.equal?(@element)
+        raise DOMException::InUseAttributeError, "attribute is in use by another element"
+      end
+
+      ns = attr.namespace_uri
+      local = attr.local_name
+      old = get_named_item_ns(ns, local)
+      return attr if old && old.equal?(attr)
+
+      value = attr.value
+      key = [ns, local]
+      if old
+        old.__internal_detach__
+        @attrs.delete(key)
+      end
+      attr.__internal_attach__(@element)
+      if ns
+        @element.set_attribute_ns(ns, attr.name, value)
+      else
+        @element.set_attribute(attr.name, value)
+      end
+      @attrs[key] = attr
+      old
+    end
+
+    # Detach and evict the cached Attr for (namespace, localName), if any —
+    # called by Element after the underlying attribute is removed so a held
+    # reference reports `ownerElement === null`.
+    def __internal_evict__(namespace, local_name)
+      key = [namespace.to_s.empty? ? nil : namespace.to_s, local_name.to_s]
+      attr = @attrs.delete(key)
+      attr&.__internal_detach__
+      nil
     end
 
-    def each(&blk)
-      @element.__node__.attribute_nodes.each do |a|
-        yield Attr.new(a.name, owner: @element)
+    # ----- Namespaced named-item access (getNamedItemNS etc.) -----
+
+    def get_named_item_ns(namespace, local_name)
+      node = Backend.attribute_nodes(@element.__dommy_backend_node__).find do |a|
+        info = Backend.attribute_ns_info(a)
+        info[:local_name] == local_name.to_s &&
+          (info[:namespace_uri] || nil) == (namespace.to_s.empty? ? nil : namespace.to_s)
       end
+      node && attr_for(node)
+    end
+
+    # setNamedItemNS shares the "set an attribute" algorithm with setNamedItem.
+    def set_named_item_ns(attr)
+      set_attribute_node(attr)
+    end
+
+    def remove_named_item_ns(namespace, local_name)
+      existing = get_named_item_ns(namespace, local_name)
+      return nil unless existing
+
+      @element.remove_attribute_ns(namespace, local_name)
+      existing
     end
 
     # Property-style access — `el.attributes.id`, `el.attributes["class"]`.
@@ -175,6 +323,17 @@ module Dommy
       end
     end
 
+    # WebIDL "supported property names" for NamedNodeMap: the qualified name of
+    # each attribute, in order (the indexed names are reflected separately).
+    def __js_named_props__
+      Backend.attribute_nodes(@element.__dommy_backend_node__).map do |a|
+        Backend.attribute_ns_info(a)[:qualified_name]
+      end
+    end
+
+    include Bridge::Methods
+    js_methods %w[item getNamedItem setNamedItem removeNamedItem
+                  getNamedItemNS setNamedItemNS removeNamedItemNS]
     def __js_call__(method, args)
       case method
       when "item"
@@ -185,6 +344,12 @@ module Dommy
         set_named_item(args[0])
       when "removeNamedItem"
         remove_named_item(args[0])
+      when "getNamedItemNS"
+        get_named_item_ns(args[0], args[1])
+      when "setNamedItemNS"
+        set_named_item_ns(args[0])
+      when "removeNamedItemNS"
+        remove_named_item_ns(args[0], args[1])
       end
     end
 
@@ -194,7 +359,7 @@ module Dommy
     end
 
     def respond_to_missing?(name, include_private = false)
-      @element.__node__.key?(name.to_s.downcase) || super
+      @element.__dommy_backend_node__.key?(name.to_s.downcase) || super
     end
   end
 end

data/lib/dommy/backend/nokogiri_adapter.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Dommy
+  module Backend
+    # Nokogiri (libxml2-based) backend. Mature, full XML namespace
+    # support. Default backend.
+    module Nokogiri
+      # Class references for `is_a?` / type-checking from Dommy internals.
+      Element = ::Nokogiri::XML::Element
+      Document = ::Nokogiri::XML::Document
+      Text = ::Nokogiri::XML::Text
+      Comment = ::Nokogiri::XML::Comment
+      DocumentFragment = ::Nokogiri::XML::DocumentFragment
+      Node = ::Nokogiri::XML::Node
+
+      module_function
+
+      def parse(html)
+        ::Nokogiri::HTML5(html.to_s, max_errors: 0)
+      end
+
+      # Parse an XML string into an XML document (DOMParser "text/xml" etc.).
+      def parse_xml(xml)
+        ::Nokogiri::XML(xml.to_s)
+      end
+
+      def fragment(html, owner_doc:)
+        # owner_doc is unused by Nokogiri — the fragment carries its
+        # own document. The Parser layer copies nodes into the target.
+        ::Nokogiri::HTML5.fragment(html.to_s, max_errors: 0)
+      end
+
+      def create_element(name, doc)
+        ::Nokogiri::XML::Node.new(name, doc)
+      end
+
+      def create_text(content, doc)
+        ::Nokogiri::XML::Text.new(content, doc)
+      end
+
+      def create_comment(content, doc)
+        ::Nokogiri::XML::Comment.new(doc, content)
+      end
+
+      def create_cdata(content, doc)
+        ::Nokogiri::XML::CDATA.new(doc, content.to_s)
+      end
+
+      def cdata_class = ::Nokogiri::XML::CDATA
+
+      def namespace_of(node)
+        node.namespace
+      end
+
+      def add_namespace_definition(node, prefix, href)
+        node.add_namespace_definition(prefix, href)
+      end
+
+      # ----- Namespaced attributes -----
+
+      def get_attribute_ns(node, namespace, local_name)
+        find_attr_ns(node, namespace, local_name)&.value
+      end
+
+      def has_attribute_ns?(node, namespace, local_name)
+        !find_attr_ns(node, namespace, local_name).nil?
+      end
+
+      def set_attribute_ns(node, namespace, prefix, local_name, qualified_name, value)
+        # WHATWG "set an attribute value": when an attribute with this
+        # (namespace, localName) already exists, only its value changes —
+        # the existing prefix/qualified name is preserved, not replaced by
+        # the one in this call.
+        existing = find_attr_ns(node, namespace, local_name)
+        if existing
+          existing.value = value.to_s
+          return value.to_s
+        end
+
+        if namespace.nil? || namespace.to_s.empty?
+          node[qualified_name] = value.to_s
+          return value.to_s
+        end
+
+        # Defining the namespace before the qualified-name assignment lets
+        # libxml2 bind the prefix to it (verified behavior). Reuse an existing
+        # matching definition so repeated sets don't pile up declarations.
+        node.namespace_definitions.find { |d| d.href == namespace.to_s && d.prefix == prefix } ||
+          node.add_namespace_definition(prefix, namespace.to_s)
+        node[qualified_name] = value.to_s
+        value.to_s
+      end
+
+      def remove_attribute_ns(node, namespace, local_name)
+        find_attr_ns(node, namespace, local_name)&.remove
+        nil
+      end
+
+      def attribute_ns_info(attr_node)
+        ns = attr_node.namespace
+        {
+          namespace_uri: ns&.href,
+          prefix: ns&.prefix,
+          local_name: attr_node.name,
+          qualified_name: ns&.prefix ? "#{ns.prefix}:#{attr_node.name}" : attr_node.name,
+          value: attr_node.value,
+        }
+      end
+
+      def attribute_nodes(node)
+        node.attribute_nodes
+      end
+
+      # Finds the attribute node matching (namespace, localName). A null
+      # namespace matches only the un-namespaced attribute of that local name.
+      def find_attr_ns(node, namespace, local_name)
+        if namespace.nil? || namespace.to_s.empty?
+          node.attribute_nodes.find { |a| a.namespace.nil? && a.name == local_name.to_s }
+        else
+          node.attribute_with_ns(local_name.to_s, namespace.to_s)
+        end
+      end
+    end
+  end
+end