moxml 0.1.15 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41df5c029544cf0136de3a87a60a1926df913b973b2653f7bb56c2e3725176b8
-  data.tar.gz: 59ef11350181ac4b5ddec209128f26cc17e629cb778776b6a198df6853a5ce22
+  metadata.gz: bbd69145e9a360635af848bf0bdda2883e35760b2763021f6bf6f1d6dca9827e
+  data.tar.gz: aa492e21514fd80a01f98709eddf8c3aa323b584210d56534ad5e2c2b467df18
 SHA512:
-  metadata.gz: c1e5e7f0a5a036bc900bd2d13522ff381cdb01fdc02d501aac6b328816bf4c2a953a0f47721665b1a209b9cdf89f29081a6410b286d6f4bdab7389b411e5475e
-  data.tar.gz: 7d05e346a9b0e32da8de5e26b29500dee443fed6c356ba12a3dafc4247b9fb2be454a02d41105e370d91c363f6bfd8445fa79c664003fa1e8f7eca8adb8da31e
+  metadata.gz: 1cdb7d6c934f1ea788a40d81d987c97d4c1fc21ad71d22eaac73abf45d093680667f3303b35934378b8cce0d99e3fc9db47c85632678247426527d7fb3491bed
+  data.tar.gz: 79c352eb8df9b86831d554e17538abd4da8a6dfce61b4e566bc236334601e43bff7c670894ea05c72abac40bb1b3b90375ef8caaf6b488a9c43bc33fc70d6785

data/.gitignore

@@ -28,6 +28,9 @@ libxml_*.txt
 # Generated benchmark reports (machine-specific)
 /benchmarks/PERFORMANCE_REPORT.md
 
+# Local TODO tracking (kept locally, not committed)
+TODO*
+
 # IDE and editor files
 .vscode/
 .idea/
@@ -49,3 +52,6 @@ libxml_*.txt
 /_site
 /docs/_site
 /docs/.jekyll-cache
+
+# Utility scripts (local only)
+/scripts/

data/.rubocop_todo.yml

@@ -1,97 +1,46 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-22 01:41:34 UTC using RuboCop version 1.86.0.
+# on 2026-04-23 07:48:23 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: 18
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
-
-# Offense count: 14
+# Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
+Layout/EmptyLineAfterGuardClause:
   Exclude:
-    - 'lib/moxml/adapter/ox.rb'
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
-    - 'spec/moxml/lazy_parse_spec.rb'
-    - 'spec/moxml/node_cache_spec.rb'
+    - 'lib/moxml/adapter/customized_rexml/formatter.rb'
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/entity_registry.rb'
 
-# Offense count: 7
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
+# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
+Layout/EmptyLineBetweenDefs:
   Exclude:
     - 'lib/moxml/adapter/ox.rb'
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
-    - 'spec/moxml/lazy_parse_spec.rb'
-    - 'spec/moxml/node_cache_spec.rb'
 
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-Layout/ClosingParenthesisIndentation:
-  Exclude:
-    - 'spec/moxml/allocation_guard_spec.rb'
-
-# Offense count: 3
-# 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:
-    - 'spec/moxml/allocation_guard_spec.rb'
-
-# Offense count: 13
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
-# SupportedStylesAlignWith: start_of_line, relative_to_receiver
-Layout/IndentationWidth:
+Layout/EmptyLines:
   Exclude:
     - 'lib/moxml/adapter/ox.rb'
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
-    - 'spec/moxml/lazy_parse_spec.rb'
-    - 'spec/moxml/node_cache_spec.rb'
 
-# Offense count: 307
+# Offense count: 330
 # 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: 3
-# This cop supports safe autocorrection (--autocorrect).
-Layout/MultilineBlockLayout:
-  Exclude:
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
-
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: symmetrical, new_line, same_line
-Layout/MultilineMethodCallBraceLayout:
-  Exclude:
-    - 'spec/moxml/allocation_guard_spec.rb'
-
-# Offense count: 3
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/MultilineOperationIndentation:
   Exclude:
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'lib/moxml/adapter/ox.rb'
 
 # Offense count: 7
 # Configuration parameters: AllowedMethods.
@@ -101,7 +50,7 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/sax_spec.rb'
 
-# Offense count: 8
+# Offense count: 10
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
@@ -110,8 +59,9 @@ Lint/DuplicateBranch:
     - 'lib/moxml/adapter/libxml.rb'
     - 'lib/moxml/adapter/ox.rb'
     - 'lib/moxml/document.rb'
+    - 'lib/moxml/entity_registry.rb'
 
-# Offense count: 4
+# Offense count: 5
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/moxml/config.rb'
@@ -138,6 +88,11 @@ Lint/EmptyWhen:
   Exclude:
     - 'lib/moxml/xpath/compiler.rb'
 
+# Offense count: 3
+Lint/HashCompareByIdentity:
+  Exclude:
+    - 'lib/moxml/native_attachment.rb'
+
 # Offense count: 1
 Lint/IneffectiveAccessModifier:
   Exclude:
@@ -156,28 +111,28 @@ Lint/NoReturnInBeginEndBlocks:
   Exclude:
     - 'examples/api_client/api_client.rb'
 
-# Offense count: 100
+# Offense count: 104
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 7
+# Offense count: 8
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 90
 
-# Offense count: 5
+# Offense count: 7
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 70
+# Offense count: 76
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 182
+# Offense count: 186
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
@@ -187,19 +142,11 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 7
 
-# Offense count: 47
+# Offense count: 52
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 2
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyleForLeadingUnderscores.
-# SupportedStylesForLeadingUnderscores: disallowed, required, optional
-Naming/MemoizedInstanceVariableName:
-  Exclude:
-    - 'lib/moxml/element.rb'
-
 # Offense count: 16
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
@@ -233,12 +180,6 @@ Naming/VariableNumber:
     - 'spec/moxml/allocation_guard_spec.rb'
     - 'spec/support/allocation_helper.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Performance/TimesMap:
-  Exclude:
-    - 'spec/support/allocation_helper.rb'
-
 # Offense count: 5
 RSpec/BeforeAfterAll:
   Exclude:
@@ -264,12 +205,12 @@ RSpec/ContextWording:
     - 'spec/moxml/xpath/parser_spec.rb'
     - 'spec/performance/benchmark_spec.rb'
 
-# Offense count: 23
+# Offense count: 24
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 271
+# Offense count: 295
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 64
@@ -305,7 +246,7 @@ RSpec/LeakyConstantDeclaration:
 RSpec/MessageSpies:
   EnforcedStyle: receive
 
-# Offense count: 356
+# Offense count: 390
 RSpec/MultipleExpectations:
   Max: 10
 
@@ -326,12 +267,6 @@ RSpec/NoExpectationExample:
   Exclude:
     - 'spec/performance/xpath_benchmark_spec.rb'
 
-# Offense count: 6
-RSpec/PendingWithoutReason:
-  Exclude:
-    - 'spec/moxml/xpath/functions/position_functions_spec.rb'
-    - 'spec/moxml/xpath/functions/special_functions_spec.rb'
-
 # Offense count: 4
 RSpec/RepeatedExample:
   Exclude:
@@ -371,21 +306,6 @@ Security/Eval:
   Exclude:
     - 'spec/moxml/xpath/ruby/generator_spec.rb'
 
-# Offense count: 11
-# 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/ox.rb'
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
-    - 'spec/moxml/lazy_parse_spec.rb'
-    - 'spec/moxml/node_cache_spec.rb'
-
 # Offense count: 1
 Style/DocumentDynamicEvalDefinition:
   Exclude:
@@ -404,25 +324,17 @@ Style/HashLikeCase:
     - 'lib/moxml/adapter/customized_rexml/formatter.rb'
     - 'lib/moxml/adapter/ox.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/MapToHash:
-  Exclude:
-    - 'spec/moxml/node_cache_spec.rb'
-
 # Offense count: 1
 Style/MissingRespondToMissing:
   Exclude:
     - 'lib/moxml/xpath/ruby/node.rb'
 
 # Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
-# SupportedStyles: predicate, comparison
-Style/NumericPredicate:
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMethodComparison, ComparisonsThreshold.
+Style/MultipleComparison:
   Exclude:
-    - 'spec/**/*'
-    - 'lib/moxml/node_set.rb'
+    - 'lib/moxml/xpath/compiler.rb'
 
 # Offense count: 5
 # Configuration parameters: AllowedClasses.
@@ -440,16 +352,20 @@ Style/OptionalBooleanParameter:
     - 'lib/moxml/adapter/libxml.rb'
     - 'lib/moxml/xpath/compiler.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/SelectByKind:
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantAssignment:
   Exclude:
     - 'lib/moxml/adapter/ox.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
+Style/RedundantConstantBase:
   Exclude:
-    - 'spec/moxml/lazy_parse_spec.rb'
+    - 'spec/moxml/adapter/headed_ox_spec.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/SelectByKind:
+  Exclude:
+    - 'spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb'

data/README.adoc

@@ -887,6 +887,18 @@ The Ox adapter provides maximum parsing speed but has XPath limitations.
 doc.xpath("//book").find { |book| book["id"] == "123" }
 ----
 
+**Upstream Ox gem limitations:**
+
+These limitations exist in the Ox gem itself and cannot be worked around in Moxml
+without changes to the Ox C extension:
+
+* *Namespace introspection* — Ox stores `xmlns` attributes but does not expose
+  namespace accessors on `Ox::Element`. Methods like `node.namespace`,
+  `node.namespaces`, and namespace inheritance are unavailable.
+* *Parent node reparenting* — Ox has no method to change a node's parent after
+  creation, preventing `node.parent=` functionality. Nodes are immutable with
+  respect to their parent relationship.
+
 For complete Ox adapter documentation including all limitations and workarounds,
 see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
 
@@ -912,6 +924,12 @@ comprehensive pure Ruby XPath 1.0 engine.
 * Prefer pure Ruby XPath for debugging
 * Basic namespace queries are sufficient
 
+**Inherited Ox limitations:**
+
+HeadedOx inherits the upstream Ox gem limitations described above (namespace
+introspection and parent node reparenting). Additionally, some sibling axes
+are not fully supported due to Ox's tree structure.
+
 [source,ruby]
 ----
 # Use HeadedOx adapter

data/Rakefile

@@ -10,6 +10,37 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 namespace :spec do
+  desc "Validate XML fixtures are well-formed (requires xmllint)"
+  task :validate_fixtures do
+    fixtures = Dir.glob("spec/fixtures/**/*.xml")
+    if fixtures.empty?
+      abort "No XML fixtures found in spec/fixtures/"
+    end
+
+    unless system("which xmllint > /dev/null 2>&1")
+      abort "xmllint not found. Install with: brew install libxml2 (macOS) or apt install libxml2-utils (Linux)"
+    end
+
+    # Intentionally malformed fixtures (W3C test cases for error handling)
+    exemptions = %w[
+      spec/fixtures/w3c/namespaces/1.0/035.xml
+    ]
+
+    errors = []
+    fixtures.each do |path|
+      next if exemptions.include?(path)
+
+      output = `xmllint --noout "#{path}" 2>&1`
+      errors << "#{path}: #{output.strip}" unless $?.success?
+    end
+
+    if errors.empty?
+      puts "#{fixtures.size} XML fixtures validated OK"
+    else
+      abort "Invalid fixtures:\n#{errors.join("\n")}"
+    end
+  end
+
   desc "Run unit tests only"
   RSpec::Core::RakeTask.new(:unit) do |t|
     t.pattern = "spec/unit/**/*_spec.rb"

data/benchmarks/generate_report.rb

@@ -488,7 +488,7 @@ class MoxmlBenchmarkReport
     f.puts "- Can accept 99.20% pass rate (16 documented Ox limitations)"
     f.puts ""
     f.puts "**Note:** HeadedOx = Ox parsing speed + full XPath features."
-    f.puts "See docs/HEADED_OX_LIMITATIONS.md for complete details."
+    f.puts "See docs/_pages/headed-ox-limitations.adoc for complete details."
     f.puts ""
   end
 

data/lib/moxml/adapter/base.rb

@@ -8,9 +8,54 @@ module Moxml
     class Base
       # include XmlUtils
 
+      # Entity marker for adapters that resolve entities during parsing.
+      # U+FFFC (Object Replacement Character) + U+FEFF (BOM) is a two-character
+      # sentinel chosen because this exact sequence followed by a valid entity
+      # name pattern is vanishingly unlikely in real XML content.
+      # Non-standard entities like © are converted to this marker before
+      # parsing, then restored during serialization.
+      # Standard XML entities (& < > " ') are NOT converted.
+      ENTITY_MARKER = "\u{FFFC}\u{FEFF}"
+      ENTITY_NAME_PATTERN = "[a-zA-Z_][\\w.:-]*"
+      ENTITY_NAME_RE = /&(#{ENTITY_NAME_PATTERN});/
+      ENTITY_MARKER_RE = /\u{FFFC}\u{FEFF}(#{ENTITY_NAME_PATTERN});/
+      SERIALIZED_ENTITY_MARKER_RE = /(#{ENTITY_NAME_PATTERN});/
+      STANDARD_ENTITIES = %w[amp lt gt quot apos].freeze
+
       class << self
         include XmlUtils
 
+        # Replace non-standard entity references with markers before parsing.
+        # Always returns a UTF-8 encoded string.
+        def preprocess_entities(xml)
+          return "" if xml.nil?
+
+          str = if xml.encoding == Encoding::BINARY
+                  # Binary strings are assumed to be UTF-8. If the bytes are
+                  # 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)
+                elsif xml.encoding == Encoding::UTF_8
+                  xml
+                else
+                  xml.encode("UTF-8")
+                end
+          str.gsub(ENTITY_NAME_RE) do |match|
+            STANDARD_ENTITIES.include?(::Regexp.last_match(1)) ? match : "#{ENTITY_MARKER}#{::Regexp.last_match(1)};"
+          end
+        end
+
+        # Restore entity markers back to named entity references.
+        def restore_entities(text)
+          return text unless text.is_a?(String)
+
+          # Force UTF-8 encoding since markers are UTF-8 characters
+          str = text.encoding == Encoding::UTF_8 ? text : text.dup.force_encoding("UTF-8")
+          result = str.gsub(ENTITY_MARKER_RE, '&\1;')
+          result.gsub(SERIALIZED_ENTITY_MARKER_RE, '&\1;')
+        end
+
         def set_root(_doc, _element)
           raise Moxml::NotImplementedError.new(
             "set_root not implemented",
@@ -149,6 +194,40 @@ namespace_validation_mode: :strict)
           node
         end
 
+        # Check if the native document has an XML declaration
+        # @param native_doc the native document object
+        # @param wrapper [Moxml::Document] the wrapper with has_xml_declaration flag
+        # @return [Boolean]
+        def has_declaration?(_native_doc, wrapper)
+          wrapper.has_xml_declaration
+        end
+
+        # Return the actual native node after an add_child operation.
+        # Override for adapters where node identity may change (e.g., LibXML doc.root=).
+        def actual_native(child_native, _parent_native)
+          child_native
+        end
+
+        # Returns all namespaces in scope for this element, including
+        # inherited from ancestors. Adapters with native support (Nokogiri)
+        # override this. Default walks the ancestor chain.
+        def in_scope_namespaces(element)
+          namespaces = {}
+          node = element
+
+          while node
+            break unless node_type(node) == :element
+
+            namespace_definitions(node).each do |ns|
+              prefix = namespace_prefix(ns)
+              namespaces[prefix] = ns unless namespaces.key?(prefix)
+            end
+            node = parent(node)
+          end
+
+          namespaces.values
+        end
+
         protected
 
         def create_native_element(_name, _owner_doc = nil)
@@ -222,14 +301,6 @@ namespace_validation_mode: :strict)
             adapter: name,
           )
         end
-
-        def in_scope_namespaces(_element)
-          raise Moxml::NotImplementedError.new(
-            "in_scope_namespaces not implemented",
-            feature: "in_scope_namespaces",
-            adapter: name,
-          )
-        end
       end
     end
   end

data/lib/moxml/adapter/customized_libxml/declaration.rb

@@ -9,7 +9,7 @@ module Moxml
       # are read-only after creation. This wrapper allows mutation by
       # storing values internally and regenerating XML when needed.
       class Declaration
-        attr_accessor :version, :encoding
+        attr_accessor :version, :encoding, :removed, :parent_doc
         attr_reader :native
 
         def initialize(native_doc, version = nil, encoding = nil,

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

@@ -7,12 +7,13 @@ module Moxml
     module CustomizedRexml
       # Custom REXML formatter that fixes indentation and wrapping issues
       class Formatter < ::REXML::Formatters::Pretty
-        def initialize(indentation: 2, self_close_empty: false)
+        def initialize(indentation: 2, self_close_empty: false, adapter: nil)
           @indentation = " " * indentation
           @level = 0
           @compact = true
           @width = -1 # Disable line wrapping
           @self_close_empty = self_close_empty
+          @adapter = adapter
         end
 
         def write(node, output)
@@ -31,7 +32,13 @@ module Moxml
           output << "<#{node.expanded_name}"
           write_attributes(node, output)
 
-          if node.children.empty? && @self_close_empty
+          # Check for entity refs stored in adapter attachments
+          entity_refs = @adapter&.attachments&.get(node, :entity_refs)
+          child_sequence = @adapter&.attachments&.get(node, :child_sequence)
+
+          has_no_children = node.children.empty? && !(entity_refs && !entity_refs.empty?)
+
+          if has_no_children && @self_close_empty
             output << "/>"
             return
           end
@@ -44,26 +51,41 @@ module Moxml
           mixed = has_text && has_elements
 
           # Handle children based on content type
-          unless node.children.empty?
+          all_children_empty = node.children.empty? && !(entity_refs && !entity_refs.empty?)
+          unless all_children_empty
             @level += @indentation.length unless mixed
 
-            node.children.each_with_index do |child, _index|
-              # Skip insignificant whitespace
-              next if child.is_a?(::REXML::Text) &&
-                child.to_s.strip.empty? &&
-                !(child.next_sibling.nil? && child.previous_sibling.nil?)
-
-              # Indent non-text nodes in non-mixed content
-              # if !mixed && !child.is_a?(::REXML::Text)
-              #   output << ' ' * @level
-              # end
-
-              write(child, output)
-
-              # Add newlines between elements in non-mixed content
-              # if !mixed && !child.is_a?(::REXML::Text) && index < node.children.size - 1
-              #   output << "\n"
-              # end
+            if entity_refs && !entity_refs.empty? && child_sequence
+              # Interleave native children with entity refs using tracked sequence
+              eref_idx = 0
+              native_idx = 0
+              child_sequence.each do |type|
+                case type
+                when :native
+                  if native_idx < node.children.size
+                    child = node.children[native_idx]
+                    native_idx += 1
+                    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
+                  if eref_idx < entity_refs.size
+                    write(entity_refs[eref_idx], output)
+                    eref_idx += 1
+                  end
+                end
+              end
+            else
+              node.children.each_with_index do |child, _index|
+                # Skip insignificant whitespace
+                next if child.is_a?(::REXML::Text) &&
+                  child.to_s.strip.empty? &&
+                  !(child.next_sibling.nil? && child.previous_sibling.nil?)
+
+                write(child, output)
+              end
             end
 
             # Reset indentation for closing tag in non-mixed content