moxml 0.1.17 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbd69145e9a360635af848bf0bdda2883e35760b2763021f6bf6f1d6dca9827e
-  data.tar.gz: aa492e21514fd80a01f98709eddf8c3aa323b584210d56534ad5e2c2b467df18
+  metadata.gz: 76508cc0d2699469ade87f48e38ea73289abc4f95cb7a313f6d71548477248f3
+  data.tar.gz: 1752cb433953a869cedd1d88fc565c53f77bd08201c5977247150e1e7b75a386
 SHA512:
-  metadata.gz: 1cdb7d6c934f1ea788a40d81d987c97d4c1fc21ad71d22eaac73abf45d093680667f3303b35934378b8cce0d99e3fc9db47c85632678247426527d7fb3491bed
-  data.tar.gz: 79c352eb8df9b86831d554e17538abd4da8a6dfce61b4e566bc236334601e43bff7c670894ea05c72abac40bb1b3b90375ef8caaf6b488a9c43bc33fc70d6785
+  metadata.gz: a4219577f2e00a9e4f00f1ce1bbaf4f03d6c841dfe8adb9983162a6389b1e276725984dc010f451cac55fbd8049a81451d641fc073fc1cf8417f90ee6e50cdf5
+  data.tar.gz: 44f3e08b174e2689fed3a60ee3ef0b805fdc14cbeeb905ebde15e5241be3e3f168441dc95afe99dd244fc1047c581fce912ec3e061299e4e101f63329f00def9

data/README.adoc

@@ -33,7 +33,7 @@ Moxml supports the following XML libraries:
 REXML:: https://github.com/ruby/rexml[REXML], a pure Ruby XML parser
 distributed with standard Ruby. Not the fastest, but always available.
 
-Nokogiri:: (default) https://github.com/sparklemotion/nokogiri[Nokogiri], a
+Nokogiri:: https://github.com/sparklemotion/nokogiri[Nokogiri], a
 widely used implementation which wraps around the performant
 https://github.com/GNOME/libxml2[libxml2] C library.
 
@@ -47,6 +47,29 @@ LibXML:: https://github.com/xml4r/libxml-ruby[libxml-ruby], Ruby bindings
 for the performant https://github.com/GNOME/libxml2[libxml2] C library.
 Alternative to Nokogiri with similar performance characteristics.
 
+==== Default adapter selection
+
+When no adapter is explicitly specified, Moxml selects one automatically based on
+the runtime environment:
+
+. If running on Opal (`RUBY_ENGINE == "opal"`), Oga is used (pure Ruby, no C extensions)
+. Otherwise, Moxml detects already-loaded XML libraries in this order:
+  .. Nokogiri
+  .. Ox
+  .. Oga
+. If none of the above are loaded, Nokogiri is the fallback default
+
+[source,ruby]
+----
+# Automatic detection — picks the best available adapter
+ctx = Moxml.new
+ctx.config.adapter_name  # => :nokogiri (or :oga on Opal)
+
+# Explicit override — always takes precedence
+ctx = Moxml.new(:ox)
+ctx.config.adapter_name  # => :ox
+----
+
 === Feature table
 
 Moxml exercises its best effort to provide a consistent interface across basic

data/lib/moxml/adapter/libxml.rb

@@ -294,9 +294,6 @@ module Moxml
           result = []
           if native_node.children?
             native_node.each_child do |child|
-              # Skip whitespace-only text nodes
-              next if child.text? && child.content.to_s.strip.empty?
-
               result << patch_node(child)
             end
           end

data/lib/moxml/adapter/nokogiri.rb

@@ -182,11 +182,7 @@ module Moxml
         end
 
         def children(node)
-          node.children.reject do |child|
-            child.text? && child.content.strip.empty? &&
-              !(child.previous_sibling.nil? && child.next_sibling.nil?) &&
-              !adjacent_to_entity_reference?(child)
-          end
+          node.children
         end
 
         def adjacent_to_entity_reference?(node)

data/lib/moxml/adapter/oga.rb

@@ -193,12 +193,18 @@ module Moxml
 
           return all_children unless node.is_a?(::Oga::XML::Node) || node.is_a?(::Oga::XML::Document)
 
-          all_children + node.children.reject do |child|
-            child.is_a?(::Oga::XML::Text) &&
-              child.text.strip.empty? &&
-              !(child.previous.nil? && child.next.nil?) &&
-              !adjacent_to_entity_reference?(child)
+          child_nodes = node.children.to_a
+          # Filter out whitespace-only text nodes at document level only.
+          # Document-level whitespace (between <?xml?> and <root>) is
+          # formatting, not content, and differs across adapters.
+          # Whitespace inside elements (e.g. "FigureA.1" spacing) is
+          # meaningful and must be preserved.
+          if node.is_a?(::Oga::XML::Document)
+            child_nodes = child_nodes.reject do |child|
+              child.is_a?(::Oga::XML::Text) && child.text.strip.empty?
+            end
           end
+          all_children + child_nodes
         end
 
         def adjacent_to_entity_reference?(node)

data/lib/moxml/adapter/rexml.rb

@@ -177,12 +177,8 @@ module Moxml
         def children(node)
           return [] unless node.is_a?(::REXML::Parent)
 
-          # Get all children and filter out empty text nodes between elements
-          result = node.children.reject do |child|
-            child.is_a?(::REXML::Text) &&
-              child.to_s.strip.empty? &&
-              !(child.next_sibling.nil? && child.previous_sibling.nil?)
-          end
+          # Return all children preserving whitespace text nodes
+          result = node.children.dup
 
           # Include any EntityReference wrappers stored alongside native children
           entity_refs = attachments.get(node, :entity_refs)

data/lib/moxml/config.rb

@@ -3,7 +3,8 @@
 module Moxml
   class Config
     VALID_ADAPTERS = %i[nokogiri oga rexml ox headed_ox libxml].freeze
-    DEFAULT_ADAPTER = VALID_ADAPTERS.first
+    DEFAULT_ADAPTER = :nokogiri
+    OPAL_DEFAULT_ADAPTER = :oga
 
     # Entity loading modes:
     # - :required - Must load entities, raise error if unavailable (default)
@@ -20,7 +21,21 @@ module Moxml
       end
 
       def default_adapter
-        @default_adapter ||= DEFAULT_ADAPTER
+        @default_adapter || runtime_default_adapter
+      end
+
+      def runtime_default_adapter
+        return OPAL_DEFAULT_ADAPTER if RUBY_ENGINE == "opal"
+
+        detect_loaded_adapter || DEFAULT_ADAPTER
+      end
+
+      def detect_loaded_adapter
+        return :nokogiri if Object.const_defined?(:Nokogiri)
+        return :ox if Object.const_defined?(:Ox)
+        return :oga if Object.const_defined?(:Oga)
+
+        nil
       end
     end
 

data/lib/moxml/native_attachment/native.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Moxml
+  class NativeAttachment
+    # Stores Moxml-specific state associated with native adapter objects
+    # without polluting their internals.
+    #
+    # Uses object_id as key with GC finalizer cleanup to prevent memory leaks.
+    # Thread-safe via Monitor (reentrant-safe).
+    #
+    # Replaces the anti-pattern of using instance_variable_set/get on
+    # foreign library objects (Nokogiri, REXML, Oga, Ox, LibXML nodes).
+    #
+    # @example
+    #   attachments = NativeAttachment.new
+    #   attachments.set(native_element, :entity_refs, [])
+    #   refs = attachments.get(native_element, :entity_refs)
+    #   attachments.key?(native_element, :doctype) #=> false
+    class Native
+      def initialize
+        @data = {}
+        @finalizer_registered = {}
+        @monitor = Monitor.new
+      end
+
+      def get(native, key)
+        @monitor.synchronize { @data[native.object_id]&.[](key) }
+      end
+
+      def set(native, key, value)
+        id = native.object_id
+        @monitor.synchronize do
+          @data[id] ||= {}
+          @data[id][key] = value
+          register_finalizer(native, id) unless @finalizer_registered[id]
+        end
+      end
+
+      def key?(native, key)
+        @monitor.synchronize { @data[native.object_id]&.key?(key) || false }
+      end
+
+      def delete(native, key)
+        @monitor.synchronize { @data[native.object_id]&.delete(key) }
+      end
+
+      private
+
+      def register_finalizer(native, id)
+        @finalizer_registered[id] = true
+        ObjectSpace.define_finalizer(native, finalizer_for(id))
+      end
+
+      def finalizer_for(id)
+        data = @data
+        registered = @finalizer_registered
+        # Finalizers must NOT use Mutex/Monitor (can't be called from trap context).
+        # Direct Hash operations are safe here since finalizers run sequentially
+        # and the GC'd object's id won't be accessed by any other thread.
+        proc do
+          data.delete(id)
+          registered.delete(id)
+        end
+      end
+    end
+  end
+end

data/lib/moxml/native_attachment/opal.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Moxml
+  class NativeAttachment
+    # Opal adapter nodes are Ruby objects, so instance variables are sufficient
+    # for Moxml-owned attachments without relying on Monitor/Thread support.
+    class Opal
+      def get(native, key)
+        native.instance_variable_get(attachment_ivar_name(key))
+      end
+
+      def set(native, key, value)
+        native.instance_variable_set(attachment_ivar_name(key), value)
+      end
+
+      def key?(native, key)
+        native.instance_variable_defined?(attachment_ivar_name(key))
+      end
+
+      def delete(native, key)
+        ivar_name = attachment_ivar_name(key)
+        return unless native.instance_variable_defined?(ivar_name)
+
+        native.remove_instance_variable(ivar_name)
+      end
+
+      private
+
+      def attachment_ivar_name(key)
+        :"@moxml_attachment_#{key}"
+      end
+    end
+  end
+end

data/lib/moxml/native_attachment.rb

@@ -1,65 +1,35 @@
 # frozen_string_literal: true
 
 module Moxml
-  # Stores Moxml-specific state associated with native adapter objects
-  # without polluting their internals.
-  #
-  # Uses object_id as key with GC finalizer cleanup to prevent memory leaks.
-  # Thread-safe via Monitor (reentrant-safe).
-  #
-  # Replaces the anti-pattern of using instance_variable_set/get on
-  # foreign library objects (Nokogiri, REXML, Oga, Ox, LibXML nodes).
-  #
-  # @example
-  #   attachments = NativeAttachment.new
-  #   attachments.set(native_element, :entity_refs, [])
-  #   refs = attachments.get(native_element, :entity_refs)
-  #   attachments.key?(native_element, :doctype) #=> false
   class NativeAttachment
-    def initialize
-      @data = {}
-      @finalizer_registered = {}
-      @monitor = Monitor.new
+    autoload :Opal, "moxml/native_attachment/opal"
+    autoload :Native, "moxml/native_attachment/native"
+
+    def self.default_backend
+      constant = RUBY_ENGINE == "opal" ? :Opal : :Native
+      const_get(constant).new
+    end
+
+    attr_reader :backend
+
+    def initialize(backend: self.class.default_backend)
+      @backend = backend
     end
 
     def get(native, key)
-      @monitor.synchronize { @data[native.object_id]&.[](key) }
+      @backend.get(native, key)
     end
 
     def set(native, key, value)
-      id = native.object_id
-      @monitor.synchronize do
-        @data[id] ||= {}
-        @data[id][key] = value
-        register_finalizer(native, id) unless @finalizer_registered[id]
-      end
+      @backend.set(native, key, value)
     end
 
     def key?(native, key)
-      @monitor.synchronize { @data[native.object_id]&.key?(key) || false }
+      @backend.key?(native, key)
     end
 
     def delete(native, key)
-      @monitor.synchronize { @data[native.object_id]&.delete(key) }
-    end
-
-    private
-
-    def register_finalizer(native, id)
-      @finalizer_registered[id] = true
-      ObjectSpace.define_finalizer(native, finalizer_for(id))
-    end
-
-    def finalizer_for(id)
-      data = @data
-      registered = @finalizer_registered
-      # Finalizers must NOT use Mutex/Monitor (can't be called from trap context).
-      # Direct Hash operations are safe here since finalizers run sequentially
-      # and the GC'd object's id won't be accessed by any other thread.
-      proc do
-        data.delete(id)
-        registered.delete(id)
-      end
+      @backend.delete(native, key)
     end
   end
 end

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.1.17"
+  VERSION = "0.1.19"
 end

data/spec/integration/shared_examples/edge_cases.rb

@@ -167,6 +167,91 @@ RSpec.shared_examples "Moxml Edge Cases" do
     end
   end
 
+  describe "whitespace text node preservation" do
+    # Ox/HeadedOx do not generate whitespace-only text nodes in their parser,
+    # so these tests only apply to adapters that do (Nokogiri, OGA, REXML, LibXML)
+    let(:preserves_ws) { !%i[ox headed_ox].include?(context.config.adapter_name) }
+
+    it "preserves whitespace-only text nodes between sibling elements" do
+      unless preserves_ws
+        skip "Ox/HeadedOx parser does not generate whitespace-only text nodes"
+      end
+
+      xml = <<~XML
+        <root>
+          <a>1</a>
+          <b>2</b>
+          <c>3</c>
+        </root>
+      XML
+
+      doc = context.parse(xml)
+      children = doc.root.children
+
+      # Should have whitespace text nodes between elements
+      expect(children.size).to be > 3
+
+      # Whitespace text nodes should be Text nodes
+      ws_nodes = children.select { |c| c.is_a?(Moxml::Text) && c.content.strip.empty? }
+      expect(ws_nodes).not_to be_empty
+
+      # Element children should still be accessible
+      elements = children.select { |c| c.is_a?(Moxml::Element) }
+      expect(elements.map(&:name)).to eq(%w[a b c])
+    end
+
+    it "preserves inline whitespace text nodes between text and elements" do
+      xml = "<p>Figure <sub>A</sub>.1</p>"
+      doc = context.parse(xml)
+
+      children = doc.root.children
+      expect(children.size).to eq(3)
+
+      # First child: "Figure " text node
+      expect(children[0]).to be_a(Moxml::Text)
+      expect(children[0].content).to eq("Figure ")
+
+      # Second child: <sub> element
+      expect(children[1]).to be_a(Moxml::Element)
+      expect(children[1].name).to eq("sub")
+      expect(children[1].text).to eq("A")
+
+      # Third child: ".1" text node
+      expect(children[2]).to be_a(Moxml::Text)
+      expect(children[2].content).to eq(".1")
+    end
+
+    it "preserves space-only text node as meaningful content" do
+      xml = "<p>Hello <b>world</b>!</p>"
+      doc = context.parse(xml)
+
+      children = doc.root.children
+      expect(children.size).to eq(3)
+
+      expect(children[0].content).to eq("Hello ")
+      expect(children[1]).to be_a(Moxml::Element)
+      expect(children[2].content).to eq("!")
+    end
+
+    it "distinguishes whitespace text nodes from element children" do
+      unless preserves_ws
+        skip "Ox/HeadedOx parser does not generate whitespace-only text nodes"
+      end
+
+      xml = "<root>  <child/>  </root>"
+      doc = context.parse(xml)
+
+      children = doc.root.children
+      # "  " before child, "  " after child
+      expect(children.size).to eq(3)
+      expect(children[0]).to be_a(Moxml::Text)
+      expect(children[0].content).to eq("  ")
+      expect(children[1]).to be_a(Moxml::Element)
+      expect(children[2]).to be_a(Moxml::Text)
+      expect(children[2].content).to eq("  ")
+    end
+  end
+
   describe "document structure edge cases" do
     it "handles deeply nested elements" do
       doc = context.create_document

data/spec/integration/shared_examples/entity_reference_whitespace.rb

@@ -104,7 +104,7 @@ RSpec.shared_examples "Entity Reference Whitespace Preservation" do
   end
 
   describe "structural whitespace filtering" do
-    it "still filters whitespace between elements" do
+    it "preserves whitespace text nodes between elements" do
       xml = <<~XML
         <root>
           <child1/>
@@ -115,8 +115,10 @@ RSpec.shared_examples "Entity Reference Whitespace Preservation" do
       doc = context.parse(xml)
       children = doc.root.children
 
-      expect(children.length).to eq(2)
-      expect(children.all?(Moxml::Element)).to be true
+      # Whitespace text nodes between elements are preserved
+      elements = children.select { |c| c.is_a?(Moxml::Element) }
+      expect(elements.length).to eq(2)
+      expect(elements.map(&:name)).to eq(%w[child1 child2])
     end
   end
 end

data/spec/integration/shared_examples/high_level/document_builder_behavior.rb

@@ -32,12 +32,14 @@ RSpec.shared_examples "Moxml::DocumentBuilder" do
 
       expect(doc.root.namespaces.count).to eq(1)
       expect(doc.root.namespaces.first.uri).to eq("http://example.org")
-      expect(doc.root.children[0]).to be_a(Moxml::Comment)
-      expect(doc.root.children[1]).to be_a(Moxml::Element)
-      expect(doc.root.children[1].name).to eq("child")
-      expect(doc.root.children[1]["id"]).to eq("1")
-      expect(doc.root.children[1].children.first).to be_a(Moxml::Cdata)
-      expect(doc.root.children[2]).to be_a(Moxml::ProcessingInstruction)
+      # Whitespace text nodes are preserved between elements
+      non_ws_children = doc.root.children.reject { |c| c.is_a?(Moxml::Text) && c.content.strip.empty? }
+      expect(non_ws_children[0]).to be_a(Moxml::Comment)
+      expect(non_ws_children[1]).to be_a(Moxml::Element)
+      expect(non_ws_children[1].name).to eq("child")
+      expect(non_ws_children[1]["id"]).to eq("1")
+      expect(non_ws_children[1].children.find { |c| c.is_a?(Moxml::Cdata) }).to be_a(Moxml::Cdata)
+      expect(non_ws_children[2]).to be_a(Moxml::ProcessingInstruction)
     end
   end
 end

data/spec/integration/shared_examples/integration_workflows.rb

@@ -113,7 +113,7 @@ RSpec.shared_examples "Moxml Integration" do
       expect(attr).to eq("value")
 
       # Test namespace override
-      deeper = a_element.children.first
+      deeper = a_element.children.find { |c| c.is_a?(Moxml::Element) }
       expect(deeper.namespace.uri).to eq("http://other.org")
     end
   end

data/spec/integration/shared_examples/node_wrappers/node_set_behavior.rb

@@ -41,7 +41,9 @@ RSpec.shared_examples "Moxml::NodeSet" do
       end
 
       it "compares nodes" do
-        expect(doc.xpath("//child")).to eq(doc.root.children)
+        xpath_results = doc.xpath("//child")
+        element_children = doc.root.children.select { |c| c.is_a?(Moxml::Element) }
+        expect(xpath_results.map(&:native)).to eq(element_children.map(&:native))
       end
     end
 

data/spec/moxml/lazy_parse_spec.rb

@@ -86,7 +86,7 @@ RSpec.describe "Moxml lazy parse" do
 
       it "round-trips through serialize" do
         doc = ctx.parse(xml)
-        serialized = doc.to_xml
+        serialized = doc.to_xml(indent: 0)
         doc2 = ctx.parse(serialized)
         expect(doc2.root.name).to eq("root")
         expect(doc2.root.children.to_a.size).to eq(2)

data/spec/moxml/moxml_spec.rb

@@ -23,7 +23,6 @@ RSpec.describe Moxml do
 
   describe ".configure" do
     around do |example|
-      # preserve the original config because it may be changed in examples
       described_class.with_config { example.run }
     end
 
@@ -47,4 +46,10 @@ RSpec.describe Moxml do
       expect(context.config.default_encoding).to eq("US-ASCII")
     end
   end
+
+  describe "Config.runtime_default_adapter" do
+    it "returns a valid adapter for the current runtime" do
+      expect(Moxml::Config::VALID_ADAPTERS).to include(Moxml::Config.runtime_default_adapter)
+    end
+  end
 end

data/spec/moxml/native_attachment/native_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "shared_examples"
+
+RSpec.describe Moxml::NativeAttachment::Native do
+  it_behaves_like "an attachment backend"
+
+  it "stores attachments outside native object instance variables" do
+    attachments = described_class.new
+    native = Object.new
+
+    attachments.set(native, :entity_refs, ["amp"])
+
+    aggregate_failures do
+      expect(attachments.get(native, :entity_refs)).to eq(["amp"])
+      expect(native.instance_variables).to be_empty
+    end
+  end
+
+  it "registers one finalizer per native object that clears sidecar storage" do
+    attachments = described_class.new
+    native = Object.new
+    other_native = Object.new
+    finalizers = {}.compare_by_identity
+
+    expect(ObjectSpace).to receive(:define_finalizer)
+      .with(native, kind_of(Proc)).once do |object, finalizer|
+        finalizers[object] = finalizer
+      end
+    expect(ObjectSpace).to receive(:define_finalizer)
+      .with(other_native, kind_of(Proc)).once do |object, finalizer|
+        finalizers[object] = finalizer
+      end
+
+    attachments.set(native, :entity_refs, ["amp"])
+    attachments.set(native, :doctype, "html")
+    attachments.set(other_native, :entity_refs, ["lt"])
+
+    native_id = native.object_id
+    data = attachments.instance_variable_get(:@data)
+    registered = attachments.instance_variable_get(:@finalizer_registered)
+
+    aggregate_failures do
+      expect(data).to have_key(native_id)
+      expect(registered).to have_key(native_id)
+    end
+
+    finalizers.fetch(native).call
+
+    aggregate_failures do
+      expect(data).not_to have_key(native_id)
+      expect(registered).not_to have_key(native_id)
+      expect(attachments.get(other_native, :entity_refs)).to eq(["lt"])
+    end
+  end
+end

data/spec/moxml/native_attachment/opal_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "shared_examples"
+
+RSpec.describe Moxml::NativeAttachment::Opal do
+  it_behaves_like "an attachment backend"
+
+  it "stores attachments in Moxml-owned instance variables" do
+    attachments = described_class.new
+    native = Object.new
+
+    attachments.set(native, :entity_refs, ["amp"])
+
+    expect(native.instance_variable_get(:@moxml_attachment_entity_refs))
+      .to eq(["amp"])
+  end
+
+  it "removes the attachment instance variable on delete" do
+    attachments = described_class.new
+    native = Object.new
+
+    attachments.set(native, :entity_refs, ["amp"])
+    attachments.delete(native, :entity_refs)
+
+    expect(native.instance_variable_defined?(:@moxml_attachment_entity_refs))
+      .to be(false)
+  end
+end

data/spec/moxml/native_attachment/shared_examples.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "an attachment backend" do
+  subject(:attachments) { described_class.new }
+
+  let(:native) { Object.new }
+  let(:other_native) { Object.new }
+
+  it "stores and reads attachments by native object and key" do
+    attachments.set(native, :entity_refs, ["amp"])
+    attachments.set(native, :doctype, "html")
+    attachments.set(other_native, :entity_refs, ["lt"])
+
+    aggregate_failures do
+      expect(attachments.get(native, :entity_refs)).to eq(["amp"])
+      expect(attachments.get(native, :doctype)).to eq("html")
+      expect(attachments.get(other_native, :entity_refs)).to eq(["lt"])
+      expect(attachments.key?(native, :entity_refs)).to be(true)
+      expect(attachments.key?(native, :missing)).to be(false)
+    end
+  end
+
+  it "preserves explicit nil attachments" do
+    attachments.set(native, :xml_declaration, nil)
+
+    aggregate_failures do
+      expect(attachments.get(native, :xml_declaration)).to be_nil
+      expect(attachments.key?(native, :xml_declaration)).to be(true)
+    end
+  end
+
+  it "deletes attachments" do
+    attachments.set(native, :entity_refs, ["amp"])
+
+    expect(attachments.delete(native, :entity_refs)).to eq(["amp"])
+
+    aggregate_failures do
+      expect(attachments.get(native, :entity_refs)).to be_nil
+      expect(attachments.key?(native, :entity_refs)).to be(false)
+      expect(attachments.delete(native, :entity_refs)).to be_nil
+    end
+  end
+end

data/spec/moxml/native_attachment_spec.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+require "spec_helper"
+
+RSpec.describe Moxml::NativeAttachment do
+  describe ".default_backend" do
+    it "uses the Opal backend under Opal" do
+      stub_const("RUBY_ENGINE", "opal")
+
+      expect(described_class.default_backend).to be_a(described_class::Opal)
+    end
+
+    it "uses the native backend under non-Opal Ruby engines" do
+      stub_const("RUBY_ENGINE", "ruby")
+
+      expect(described_class.default_backend).to be_a(described_class::Native)
+    end
+  end
+
+  describe "facade" do
+    subject(:attachments) { described_class.new }
+
+    let(:native) { Object.new }
+
+    it "delegates storage calls to the configured backend" do
+      backend = Class.new do
+        attr_reader :calls
+
+        def initialize
+          @calls = []
+        end
+
+        def get(native, key)
+          @calls << [:get, native, key]
+          :stored_value
+        end
+
+        def set(native, key, value)
+          @calls << [:set, native, key, value]
+        end
+
+        def key?(native, key)
+          @calls << [:key?, native, key]
+          true
+        end
+
+        def delete(native, key)
+          @calls << [:delete, native, key]
+          :stored_value
+        end
+      end.new
+      attachments = described_class.new(backend: backend)
+
+      expect(attachments.get(native, :entity_refs)).to eq(:stored_value)
+      attachments.set(native, :entity_refs, ["amp"])
+      expect(attachments.key?(native, :entity_refs)).to be(true)
+      expect(attachments.delete(native, :entity_refs)).to eq(:stored_value)
+
+      expect(backend.calls).to eq(
+        [
+          [:get, native, :entity_refs],
+          [:set, native, :entity_refs, ["amp"]],
+          [:key?, native, :entity_refs],
+          [:delete, native, :entity_refs],
+        ],
+      )
+    end
+
+    it "uses the selected runtime backend" do
+      expected_class = if RUBY_ENGINE == "opal"
+                         described_class::Opal
+                       else
+                         described_class::Native
+                       end
+
+      expect(attachments.backend).to be_a(expected_class)
+    end
+  end
+
+  describe "loader" do
+    let(:lib_dir) { File.expand_path("../../lib", __dir__) }
+    let(:ruby) { RbConfig.ruby }
+
+    it "loads NativeAttachment through the top-level moxml entrypoint" do
+      stdout, stderr, status = Open3.capture3(
+        ruby,
+        "-I",
+        lib_dir,
+        "-e",
+        'require "moxml"; puts Moxml::NativeAttachment.new.respond_to?(:set)',
+      )
+
+      expect(status.success?).to be(true), stderr
+      expect(stdout).to eq("true\n")
+    end
+
+    it "loads NativeAttachment through the internal facade file" do
+      stdout, stderr, status = Open3.capture3(
+        ruby,
+        "-I",
+        lib_dir,
+        "-e",
+        'require "moxml/native_attachment"; puts Moxml::NativeAttachment.new.respond_to?(:set)',
+      )
+
+      expect(status.success?).to be(true), stderr
+      expect(stdout).to eq("true\n")
+    end
+
+    it "registers backend implementations with require-style autoload paths" do
+      stdout, stderr, status = Open3.capture3(
+        ruby,
+        "-I",
+        lib_dir,
+        "-e",
+        <<~RUBY,
+          require "moxml/native_attachment"
+
+          puts Moxml::NativeAttachment.autoload?(:Opal)
+          puts Moxml::NativeAttachment.autoload?(:Native)
+        RUBY
+      )
+
+      expect(status.success?).to be(true), stderr
+      expect(stdout).to eq(
+        "moxml/native_attachment/opal\n" \
+        "moxml/native_attachment/native\n",
+      )
+    end
+
+    it "loads the native backend lazily when selected" do
+      stdout, stderr, status = Open3.capture3(
+        ruby,
+        "-I",
+        lib_dir,
+        "-e",
+        <<~'RUBY',
+          require "moxml/native_attachment"
+
+          puts $LOADED_FEATURES.grep(%r{/native_attachment/native\.rb\z}).empty?
+          puts Moxml::NativeAttachment.new.backend.class
+          puts !$LOADED_FEATURES.grep(%r{/native_attachment/native\.rb\z}).empty?
+          puts $LOADED_FEATURES.grep(%r{/native_attachment/opal\.rb\z}).empty?
+        RUBY
+      )
+
+      expect(status.success?).to be(true), stderr
+      expect(stdout).to eq(
+        "true\n" \
+        "Moxml::NativeAttachment::Native\n" \
+        "true\n" \
+        "true\n",
+      )
+    end
+
+    it "does not load the native backend when Opal is selected" do
+      stdout, stderr, status = Open3.capture3(
+        ruby,
+        "-I",
+        lib_dir,
+        "-e",
+        <<~'RUBY',
+          Object.send(:remove_const, :RUBY_ENGINE)
+          RUBY_ENGINE = "opal"
+
+          require "moxml/native_attachment"
+
+          puts Moxml::NativeAttachment.autoload?(:Native)
+          puts Moxml::NativeAttachment.new.backend.class
+          puts $LOADED_FEATURES.grep(%r{/native_attachment/native\.rb\z}).empty?
+        RUBY
+      )
+
+      expect(status.success?).to be(true), stderr
+      expect(stdout).to eq(
+        "moxml/native_attachment/native\n" \
+        "Moxml::NativeAttachment::Opal\n" \
+        "true\n",
+      )
+    end
+  end
+end

data/spec/moxml/xpath/functions/node_functions_spec.rb

@@ -127,7 +127,7 @@ RSpec.describe "XPath Node Functions" do
     it "inherits language from parent element" do
       ast = Moxml::XPath::Parser.parse('lang("en")')
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
-      child = doc_with_lang.root.children.first
+      child = doc_with_lang.root.children.select { |c| c.is_a?(Moxml::Element) }.first
       result = proc.call(child)
 
       expect(result).to be true
@@ -136,7 +136,8 @@ RSpec.describe "XPath Node Functions" do
     it "uses closest xml:lang attribute" do
       ast = Moxml::XPath::Parser.parse('lang("fr")')
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
-      other = doc_with_lang.root.children[1]
+      elements = doc_with_lang.root.children.select { |c| c.is_a?(Moxml::Element) }
+      other = elements[1]
       result = proc.call(other)
 
       expect(result).to be true

data/spec/performance/benchmark_spec.rb

@@ -27,10 +27,10 @@ RSpec.shared_examples "Performance Examples" do
         {
           nokogiri: { parser: 15, serializer: 1000 },
           oga: { parser: 10, serializer: 100 },
-          rexml: { parser: 0, serializer: 60 },
+          rexml: { parser: 0, serializer: 5 },
           ox: { parser: 2, serializer: 1000 },
           headed_ox: { parser: 2, serializer: 1000 },
-          libxml: { parser: 10, serializer: 30 },
+          libxml: { parser: 2, serializer: 3 },
         }
       end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.1.17
+  version: 0.1.19
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -141,6 +141,8 @@ files:
 - lib/moxml/error.rb
 - lib/moxml/namespace.rb
 - lib/moxml/native_attachment.rb
+- lib/moxml/native_attachment/native.rb
+- lib/moxml/native_attachment/opal.rb
 - lib/moxml/node.rb
 - lib/moxml/node_set.rb
 - lib/moxml/processing_instruction.rb
@@ -325,6 +327,10 @@ files:
 - spec/moxml/moxml_spec.rb
 - spec/moxml/namespace_spec.rb
 - spec/moxml/namespace_uri_validation_spec.rb
+- spec/moxml/native_attachment/native_spec.rb
+- spec/moxml/native_attachment/opal_spec.rb
+- spec/moxml/native_attachment/shared_examples.rb
+- spec/moxml/native_attachment_spec.rb
 - spec/moxml/node_cache_spec.rb
 - spec/moxml/node_set_cache_spec.rb
 - spec/moxml/node_set_spec.rb