moxml 0.1.18 → 0.1.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1daf227e9effc582c66e780516135481aa48e467226a4267974633a4673f786
-  data.tar.gz: 5b230e79a208eb4b1c5e32175df364e5b42f9e766c4c8189eb18fcad09bb79bf
+  metadata.gz: 0633c51783a25d02190769345f0c6a4af79c29665b180e5b46fc28f0b6eeee31
+  data.tar.gz: b3d9d706cc185c2d045ed8d3c9a62bb884196cc2cc520cd51fd17cecb07cd897
 SHA512:
-  metadata.gz: e39941f6f51567655c246f1e8d6225c6ab572c68958fd9ca4a74ca191af4493e1bf74ff0feed84792cc87e5681cce1d8ae291533e992d07b70fdfb1063d96a67
-  data.tar.gz: 41ca4a3954bf2e713703124758309e5d1e056d44826cdacf3b4693c5bf37c463579462a6c0ecb3aa65e4c3cafaeef1e2ad0d8a5af9ebe2e1b9f4a695e7678ff4
+  metadata.gz: 6626a13b9dda295113caa1e1d99085afd20776b1d3d4f156bbdf63efcefccef59cd1ea37d14439aa7487f3f617ed65ac1003ec775b22e77614a4b0082c832307
+  data.tar.gz: 68b26d50fa35b206835f633dfd7b26f6c389fc3507a524a84784929b089e0c699d1361af8838d86e5fcec0e8031f81ca82e2e799b544737cc1616a3da5d15707

data/.rubocop_todo.yml

@@ -1,11 +1,65 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-23 07:48:23 UTC using RuboCop version 1.86.0.
+# on 2026-05-03 12:53:32 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/moxml/adapter/base.rb'
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/builder.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
+  Exclude:
+    - 'lib/moxml/xpath/compiler.rb'
+
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/integration/shared_examples/edge_cases.rb'
+    - 'spec/integration/shared_examples/high_level/document_builder_behavior.rb'
+    - 'spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb'
+    - 'spec/moxml/xpath/functions/node_functions_spec.rb'
+
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/integration/shared_examples/edge_cases.rb'
+    - 'spec/integration/shared_examples/high_level/document_builder_behavior.rb'
+    - 'spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb'
+    - 'spec/moxml/xpath/functions/node_functions_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'lib/moxml/adapter/oga.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ElseAlignment:
+  Exclude:
+    - 'lib/moxml/adapter/base.rb'
+
 # Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
 Layout/EmptyLineAfterGuardClause:
@@ -27,13 +81,67 @@ Layout/EmptyLines:
   Exclude:
     - 'lib/moxml/adapter/ox.rb'
 
-# Offense count: 330
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLinesAroundMethodBody:
+  Exclude:
+    - 'lib/moxml/adapter/ox.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/moxml/adapter/base.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'lib/moxml/adapter/oga.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/moxml/builder.rb'
+
+# Offense count: 20
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/moxml/adapter/base.rb'
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/integration/shared_examples/edge_cases.rb'
+    - 'spec/integration/shared_examples/high_level/document_builder_behavior.rb'
+    - 'spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb'
+    - 'spec/moxml/xpath/functions/node_functions_spec.rb'
+
+# Offense count: 344
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'lib/moxml/adapter/oga.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
@@ -42,6 +150,17 @@ Layout/MultilineOperationIndentation:
   Exclude:
     - 'lib/moxml/adapter/ox.rb'
 
+# Offense count: 10
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/moxml/adapter/base.rb'
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'lib/moxml/builder.rb'
+    - 'lib/moxml/xpath/compiler.rb'
+
 # Offense count: 7
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
@@ -61,11 +180,10 @@ Lint/DuplicateBranch:
     - 'lib/moxml/document.rb'
     - 'lib/moxml/entity_registry.rb'
 
-# Offense count: 5
+# Offense count: 4
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/moxml/config.rb'
-    - 'lib/moxml/element.rb'
     - 'lib/moxml/node.rb'
 
 # Offense count: 4
@@ -91,7 +209,7 @@ Lint/EmptyWhen:
 # Offense count: 3
 Lint/HashCompareByIdentity:
   Exclude:
-    - 'lib/moxml/native_attachment.rb'
+    - 'lib/moxml/native_attachment/native.rb'
 
 # Offense count: 1
 Lint/IneffectiveAccessModifier:
@@ -127,12 +245,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 76
+# Offense count: 75
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 186
+# Offense count: 188
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
@@ -180,6 +298,12 @@ Naming/VariableNumber:
     - 'spec/moxml/allocation_guard_spec.rb'
     - 'spec/support/allocation_helper.rb'
 
+# Offense count: 1
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - 'lib/moxml/xpath/compiler.rb'
+
 # Offense count: 5
 RSpec/BeforeAfterAll:
   Exclude:
@@ -205,12 +329,12 @@ RSpec/ContextWording:
     - 'spec/moxml/xpath/parser_spec.rb'
     - 'spec/performance/benchmark_spec.rb'
 
-# Offense count: 24
+# Offense count: 25
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 295
+# Offense count: 328
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 64
@@ -240,13 +364,13 @@ RSpec/LeakyConstantDeclaration:
     - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/sax_spec.rb'
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: .
 # SupportedStyles: have_received, receive
 RSpec/MessageSpies:
   EnforcedStyle: receive
 
-# Offense count: 390
+# Offense count: 414
 RSpec/MultipleExpectations:
   Max: 10
 
@@ -306,6 +430,22 @@ Security/Eval:
   Exclude:
     - 'spec/moxml/xpath/ruby/generator_spec.rb'
 
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/integration/shared_examples/edge_cases.rb'
+    - 'spec/integration/shared_examples/high_level/document_builder_behavior.rb'
+    - 'spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb'
+    - 'spec/moxml/xpath/functions/node_functions_spec.rb'
+
 # Offense count: 1
 Style/DocumentDynamicEvalDefinition:
   Exclude:
@@ -329,6 +469,18 @@ Style/MissingRespondToMissing:
   Exclude:
     - 'lib/moxml/xpath/ruby/node.rb'
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/moxml/builder.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineTernaryOperator:
+  Exclude:
+    - 'lib/moxml/adapter/base.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowMethodComparison, ComparisonsThreshold.
@@ -365,7 +517,25 @@ Style/RedundantConstantBase:
     - 'spec/moxml/adapter/headed_ox_spec.rb'
 
 # Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantParentheses:
+  Exclude:
+    - 'lib/moxml/xpath/compiler.rb'
+
+# Offense count: 8
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/SelectByKind:
   Exclude:
+    - 'spec/integration/shared_examples/edge_cases.rb'
+    - 'spec/integration/shared_examples/entity_reference_whitespace.rb'
     - 'spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb'
+    - 'spec/integration/shared_examples/node_wrappers/node_set_behavior.rb'
+    - 'spec/moxml/xpath/functions/node_functions_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, MinSize.
+# SupportedStyles: percent, brackets
+Style/SymbolArray:
+  Exclude:
+    - 'lib/moxml/xpath/compiler.rb'

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/docs/_guides/node-api-consistency.adoc

@@ -390,6 +390,10 @@ Text nodes contain character data.
 | `#text`
 | Alias for #content
 | ✅ Yes
+
+| `#to_s`
+| Returns the text content (same as `#content`)
+| ✅ Yes
 |===
 
 ==== Identity Methods

data/lib/moxml/adapter/base.rb

@@ -35,7 +35,12 @@ module Moxml
                   # not valid UTF-8, fall back to encoding as UTF-8 with
                   # replacement to avoid raising on gsub.
                   dup = xml.dup.force_encoding("UTF-8")
-                  dup.valid_encoding? ? dup : xml.dup.encode("UTF-8", "ASCII-8BIT", invalid: :replace, undef: :replace)
+                  if dup.valid_encoding?
+                    dup
+                  else
+                    xml.dup.encode("UTF-8",
+                                   "ASCII-8BIT", invalid: :replace, undef: :replace)
+                  end
                 elsif xml.encoding == Encoding::UTF_8
                   xml
                 else

data/lib/moxml/adapter/customized_ox/text.rb

@@ -3,8 +3,21 @@
 module Moxml
   module Adapter
     module CustomizedOx
-      # Ox uses Strings, but a string cannot have a parent reference
-      class Text < ::Ox::Node; end
+      # Ox uses Strings for text content, but a String cannot carry a @parent
+      # back-reference. We subclass ::Ox::Node so a Text wrapper can hold one.
+      #
+      # ::Ox::Node subclasses that are neither ::Ox::Element nor ::Ox::Document
+      # are unknown to Ox.dump's standard XML emitter, so they fall through to
+      # Ox's generic object-marshalling format. The serializer in
+      # Moxml::Adapter::Ox#serialize special-cases this class to emit the value
+      # with proper XML escaping. The #to_s override ensures string
+      # interpolation (`"#{text}"`) produces the text content rather than the
+      # default Object representation.
+      class Text < ::Ox::Node
+        def to_s
+          value.to_s
+        end
+      end
     end
   end
 end

data/lib/moxml/adapter/customized_rexml/formatter.rb

@@ -68,6 +68,7 @@ module Moxml
                     next if child.is_a?(::REXML::Text) &&
                       child.to_s.strip.empty? &&
                       !(child.next_sibling.nil? && child.previous_sibling.nil?)
+
                     write(child, output)
                   end
                 when :eref

data/lib/moxml/adapter/libxml.rb

@@ -565,7 +565,8 @@ module Moxml
               # Set as root element
               native_elem.root = native_child
               # Flag for actual_native to refresh the wrapper's native reference
-              attachments.set(native_elem, :_pending_root_refresh, native_child.object_id)
+              attachments.set(native_elem, :_pending_root_refresh,
+                              native_child.object_id)
             elsif native_elem.root
               # Document has root, add to it instead
               import_and_add(native_elem.doc, native_elem.root, native_child)
@@ -594,6 +595,7 @@ module Moxml
         def lookup_entity_refs(doc, element)
           pairs = attachments.get(doc, :_entity_ref_pairs)
           return nil unless pairs
+
           pair = pairs.find { |elem, _| elem == element }
           pair&.last
         end
@@ -614,6 +616,7 @@ module Moxml
         def lookup_child_sequence(doc, element)
           pairs = attachments.get(doc, :_child_seq_pairs)
           return nil unless pairs
+
           pair = pairs.find { |elem, _| elem == element }
           pair&.last
         end
@@ -1481,7 +1484,9 @@ module Moxml
             # Interleave native children with entity refs using tracked sequence
             native_children = []
             if elem.children?
-              elem.each_child { |c| native_children << c unless c.text? && c.content.to_s.strip.empty? }
+              elem.each_child do |c|
+                native_children << c unless c.text? && c.content.to_s.strip.empty?
+              end
             end
 
             eref_idx = 0

data/lib/moxml/adapter/oga.rb

@@ -470,7 +470,9 @@ module Moxml
           if node.is_a?(::Oga::XML::Document)
             # Check if we should include declaration
             # Priority: explicit option > existence of xml_declaration (native or attachment)
-            effective_xml_declaration = node.xml_declaration || attachments.get(node, :xml_declaration)
+            effective_xml_declaration = node.xml_declaration || attachments.get(
+              node, :xml_declaration
+            )
             should_include_decl = if options.key?(:no_declaration)
                                     !options[:no_declaration]
                                   elsif options.key?(:declaration)
@@ -519,7 +521,9 @@ module Moxml
 
           # Default: use XmlGenerator
           # But first check if we need to handle declaration specially
-          effective_xml_declaration = node.is_a?(::Oga::XML::Document) && (node.xml_declaration || attachments.get(node, :xml_declaration))
+          effective_xml_declaration = node.is_a?(::Oga::XML::Document) && (node.xml_declaration || attachments.get(
+            node, :xml_declaration
+          ))
           if node.is_a?(::Oga::XML::Document) && effective_xml_declaration
             # Document has declaration - use custom handling to avoid duplicates
             output = []

data/lib/moxml/adapter/ox.rb

@@ -74,8 +74,7 @@ module Moxml
         end
 
         def create_native_element(name, _owner_doc = nil)
-          element = ::Ox::Element.new(name)
-          element
+          ::Ox::Element.new(name)
         end
 
         def create_native_text(content, _owner_doc = nil)
@@ -622,6 +621,12 @@ module Moxml
         end
 
         def serialize(node, options = {})
+          # CustomizedOx::Text subclasses ::Ox::Node so it can carry a @parent
+          # back-reference, but that makes it unknown to Ox.dump's XML emitter,
+          # which then falls back to generic object marshalling. Short-circuit
+          # here with proper XML escaping.
+          return escape_xml_text(node.value) if node.is_a?(CustomizedOx::Text)
+
           needs_custom = needs_custom_serialize?(node)
 
           unless needs_custom
@@ -643,7 +648,7 @@ module Moxml
             return true if attachments.get(node, :has_entity_refs)
             return true if attachments.get(node, :has_cdata_end_markers)
             return false if attachments.key?(node, :has_entity_refs) &&
-                            attachments.key?(node, :has_cdata_end_markers)
+              attachments.key?(node, :has_cdata_end_markers)
           end
 
           # Only scan tree on first call — short-circuit on first hit
@@ -694,9 +699,8 @@ module Moxml
             encoding: options[:encoding],
             no_empty: options[:expand_empty],
           }
-          result = output + ::Ox.dump(node, ox_options)
+          output + ::Ox.dump(node, ox_options)
           # Fix CDATA ]]> end markers that Ox doesn't escape
-          result
         end
 
         def tree_has_entity_references?(node)
@@ -721,9 +725,13 @@ module Moxml
           when ::Ox::CData
             node.value&.include?("]]>") || false
           when ::Ox::Element
-            node.nodes&.any? { |child| tree_has_cdata_end_markers?(child) } || false
+            node.nodes&.any? do |child|
+              tree_has_cdata_end_markers?(child)
+            end || false
           when ::Ox::Document
-            node.nodes&.any? { |child| tree_has_cdata_end_markers?(child) } || false
+            node.nodes&.any? do |child|
+              tree_has_cdata_end_markers?(child)
+            end || false
           else
             false
           end
@@ -814,7 +822,6 @@ module Moxml
           end
         end
 
-
         # Translate a subset of XPath to Ox locate() syntax
         # Supports: //element, /path/to/element, .//element, element[@attr]
         # Note: Ox locate() doesn't support namespace prefixes in the path

data/lib/moxml/builder.rb

@@ -30,12 +30,14 @@ module Moxml
     # and a valid XML tag name (XSD/RelaxNG).
     def element(name_or_attrs = nil, attributes = {}, &block)
       if name_or_attrs.is_a?(Hash)
-        return create_element_node("element", name_or_attrs, block: block, eval_block: false)
+        return create_element_node("element", name_or_attrs, block: block,
+                                                             eval_block: false)
       end
 
       raise ArgumentError, "element requires a tag name" if name_or_attrs.nil?
 
-      create_element_node(name_or_attrs, attributes, block: block, eval_block: true)
+      create_element_node(name_or_attrs, attributes, block: block,
+                                                     eval_block: true)
     end
 
     def text(content)
@@ -101,10 +103,14 @@ module Moxml
       text_content = args.first.is_a?(String) ? args.shift : nil
       attrs = args.first.is_a?(Hash) ? args.shift : {}
 
-      raise ArgumentError, "unexpected arguments for #{method_name}: #{args.inspect}" unless args.empty?
+      unless args.empty?
+        raise ArgumentError,
+              "unexpected arguments for #{method_name}: #{args.inspect}"
+      end
 
       if text_content && block
-        raise ArgumentError, "#{method_name}: cannot combine text content with a block"
+        raise ArgumentError,
+              "#{method_name}: cannot combine text content with a block"
       end
 
       # Strip trailing underscore to allow reserved Ruby method names as tags
@@ -126,7 +132,8 @@ module Moxml
     # Single method for all element creation.
     # eval_block: true  → instance_eval (build DSL context)
     # eval_block: false → yield (preserves caller's self)
-    def create_element_node(tag_name, attrs = {}, text_content: nil, block: nil, eval_block: true)
+    def create_element_node(tag_name, attrs = {}, text_content: nil,
+block: nil, eval_block: true)
       el = @document.create_element(tag_name)
 
       attrs.each do |key, value|

data/lib/moxml/config.rb

@@ -21,7 +21,7 @@ module Moxml
       end
 
       def default_adapter
-        @default_adapter ||= runtime_default_adapter
+        @default_adapter || runtime_default_adapter
       end
 
       def runtime_default_adapter

data/lib/moxml/entity_registry.rb

@@ -156,6 +156,7 @@ module Moxml
     def primary_name_for_codepoint(codepoint)
       names = @by_codepoint[codepoint]
       return nil unless names&.any?
+
       # Prefer lowercase names (e.g., "amp" over "AMP") for XML compatibility
       names.find { |n| n == n.downcase } || names.first
     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