lutaml-model 0.8.5 → 0.8.6

data/lib/lutaml/xml/adapter/nokogiri_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "moxml"
 require "moxml/adapter/nokogiri"
 require_relative "base_adapter"
@@ -6,1116 +8,9 @@ module Lutaml
   module Xml
     module Adapter
       class NokogiriAdapter < BaseAdapter
-        extend DocTypeExtractor
-        extend AdapterHelpers
-
-        TEXT_CLASSES = [Moxml::Text, Moxml::Cdata].freeze
-
-        def self.parse(xml, options = {})
-          enc = encoding(xml, options)
-          parsed = Moxml::Adapter::Nokogiri.parse(xml, encoding: enc)
-          root_element = parsed.root
-
-          # Validate that we have a root element
-          if root_element.nil?
-            raise Lutaml::Model::InvalidFormatError.new(
-              :xml,
-              "Document has no root element. " \
-              "The XML may be empty, contain only whitespace, " \
-              "or consist only of an XML declaration.",
-            )
-          end
-
-          # Extract DOCTYPE information from raw XML
-          # (Moxml doesn't directly expose DOCTYPE)
-          doctype_info = extract_doctype_from_xml(xml)
-
-          # Extract XML declaration for preservation
-          xml_decl_info = DeclarationHandler.extract_xml_declaration(xml)
-
-          @root = NokogiriElement.new(root_element)
-          @root.processing_instructions = extract_document_processing_instructions(parsed)
-          new(@root, enc, doctype: doctype_info,
-                          xml_declaration: xml_decl_info)
-        end
-
-        def to_xml(options = {})
-          # Accept xml_declaration from options if present (for model serialization)
-          @xml_declaration = options[:xml_declaration] if options[:xml_declaration]
-
-          builder_options = {}
-          encoding = determine_encoding(options)
-          builder_options[:encoding] = encoding if encoding
-
-          builder = Builder::Nokogiri.build(builder_options) do |xml|
-            if root.is_a?(Lutaml::Xml::NokogiriElement)
-              # Case A: Old parsed XML (from NokogiriElement) - use build_xml
-              root.build_xml(xml)
-            else
-              # Cases B & C: XmlElement or Model instance
-              # ARCHITECTURE: Normalize to XmlElement, then use single rendering path
-
-              # Determine the source (XmlElement or model instance)
-              original_model = nil
-
-              xml_element = if root.is_a?(Lutaml::Xml::DataModel::XmlElement)
-                              # Case B: Already an XmlElement
-                              root
-                            else
-                              # Case C: Model instance - transform to XmlElement
-                              original_model = root
-                              mapper_class = options[:mapper_class] || root.class
-                              transformation = mapper_class.transformation_for(
-                                :xml, @register
-                              )
-                              transformation.transform(root, options)
-                            end
-
-              # Collect original namespace URIs for namespace alias support.
-              # This enables round-trip fidelity when XML uses alias URIs.
-              original_ns_uris = {}
-              stored_plan = nil
-              if original_model
-                # Case C: Model instance was transformed to XmlElement
-                mapping_for_original = options[:mapper_class]&.mappings_for(:xml) || original_model.class.mappings_for(:xml)
-                original_ns_uris = collect_original_namespace_uris(
-                  original_model, mapping_for_original
-                )
-                # Get stored declaration plan from model for PRESERVATION phase
-                if original_model.is_a?(Lutaml::Model::Serialize)
-                  stored_plan = original_model.import_declaration_plan
-                end
-              elsif xml_element.is_a?(Lutaml::Xml::DataModel::XmlElement)
-                # Case B: XmlElement from transformation may have @__xml_original_namespace_uri
-                original_ns_uri = xml_element.original_namespace_uri
-                if original_ns_uri
-                  # Get mapping from the mapper_class (model class) not from XmlElement
-                  mapper_klass = options[:mapper_class] || xml_element.class
-                  xml_mapping = begin
-                    mapper_klass.mappings_for(:xml)
-                  rescue StandardError
-                    nil
-                  end
-                  if xml_mapping&.namespace_class
-                    canonical_uri = xml_mapping.namespace_class.uri
-                    if canonical_uri != original_ns_uri
-                      original_ns_uris[canonical_uri] =
-                        original_ns_uri
-                    end
-                  end
-                end
-              end
-              options_with_original_ns = options.merge(__original_namespace_uris: original_ns_uris)
-              if stored_plan
-                options_with_original_ns[:stored_xml_declaration_plan] =
-                  stored_plan
-              end
-
-              mapper_class = options[:mapper_class] || xml_element.class
-              mapping = mapper_class.mappings_for(:xml)
-
-              # Phase 1: Collect namespace needs from XmlElement tree
-              collector = NamespaceCollector.new(@register)
-              needs = collector.collect(xml_element, mapping,
-                                        mapper_class: mapper_class)
-
-              # Phase 2: Plan namespace declarations (builds ElementNode tree)
-              planner = DeclarationPlanner.new(@register)
-              plan = planner.plan(xml_element, mapping, needs,
-                                  options: options_with_original_ns)
-
-              # Phase 3: Render using XmlElement + DeclarationPlan
-              # Pass original model for custom method invocation
-              render_options = options.merge(is_root_element: true)
-              render_options[:original_model] = original_model if original_model
-              build_xml_element_with_plan(xml, xml_element, plan,
-                                          render_options)
-            end
-          end
-
-          xml_data = builder.to_xml
-
-          # Transcode to target encoding if needed
-          target_encoding = encoding || options[:encoding]
-          if target_encoding && target_encoding.upcase != "UTF-8"
-            xml_data = xml_data.encode(target_encoding)
-          end
-
-          result = ""
-
-          # Handle XML declaration based on Issue #1: XML Declaration Preservation
-          # Include declaration when encoding is specified OR when declaration is requested
-          if (options[:encoding] && !options[:encoding].nil?) || should_include_declaration?(options)
-            result += generate_declaration(options)
-          end
-
-          # Add DOCTYPE if present - use DeclarationHandler method
-          doctype_to_use = options[:doctype] || @doctype
-          if doctype_to_use && !options[:omit_doctype]
-            result += generate_doctype_declaration(doctype_to_use)
-          end
-
-          result += xml_data
-
-          # Post-process: Fix OOXML format issues (opt-in)
-          result = fix_ooxml_format(result) if options[:fix_boolean_elements]
-
-          result
-        end
-
-        def attributes_hash(element)
-          result = Lutaml::Model::MappingHash.new
-
-          element.attributes_each_value do |attr|
-            if attr.name == "schemaLocation"
-              result["__schema_location"] = {
-                namespace: attr.namespace,
-                prefix: attr.namespace.prefix,
-                schema_location: attr.value,
-              }
-            else
-              result[self.class.namespaced_attr_name(attr)] = attr.value
-            end
-          end
-
-          result
-        end
-
-        # NOTE: name_of, prefixed_name_of, namespaced_attr_name, namespaced_name_of
-        # are provided by AdapterHelpers module via extend
-
-        def self.text_of(element)
-          element.text
-        end
-
-        def order
-          children.filter_map do |child|
-            if child.text?
-              next if child.text.nil?
-
-              Element.new("Text", "text", text_content: child.text)
-            elsif child.comment?
-              Element.new("Comment", "comment",
-                          text_content: child.content,
-                          node_type: :comment)
-            else
-              Element.new("Element", child.unprefixed_name)
-            end
-          end
-        end
-
-        def self.order_of(element)
-          element.children.each do |node|
-            if node.is_a?(Moxml::ProcessingInstruction)
-              return [Element.new("ProcessingInstruction", node.name)]
-            end
-          end
-          super
-        end
-
-        # Build element using prepared namespace declaration plan
-        #
-        # @param xml [Builder] the XML builder
-        # @param element [Object] the model instance
-        # @param plan [Hash] the declaration plan from DeclarationPlanner
-        # @param options [Hash] serialization options
-        def build_element_with_plan(xml, element, plan, options = {})
-          # Provide default empty plan if nil (e.g., for custom methods)
-          plan ||= DeclarationPlan.empty
-
-          mapper_class = options[:mapper_class] || element.class
-
-          # New: Handle simple types that don't have mappings
-          unless mapper_class.is_a?(Class) && mapper_class.include?(Lutaml::Model::Serialize)
-            tag_name = options[:tag_name] || "element"
-            xml.create_and_add_element(tag_name) do |inner_xml|
-              inner_xml.text(element.to_s)
-            end
-            return xml
-          end
-
-          mapping = mapper_class.mappings_for(:xml)
-          return xml unless mapping
-
-          # TYPE-ONLY MODELS: No element wrapper, serialize children directly
-          # BUT if we have a tag_name in options, that means parent wants a wrapper
-          if mapping.namespace_class
-            # Check if this element's namespace is explicitly :blank
-            # This happens when the model uses 'namespace :blank' in its xml block
-            # We can detect this through the plan - but since we're inside build_element_with_plan,
-            # we need to check the mapping directly
-            # Actually, the element itself won't have explicit_blank in its namespace resolution
-            # because it's the element's OWN namespace. We need to skip this for the element itself.
-            # The xmlns="" handling is for CHILD elements, not the parent element.
-            # So this section is actually not needed here - it's needed in add_simple_value
-            # But it reads:
-            # @mapping.namespace_class
-            # element.ns_info_for(repository_name, mapping.xml_namespace)
-          end
-
-          # Use xmlns declarations from plan
-          attributes = {}
-          attributes.merge!(NamespaceDeclarationBuilder.build_xmlns_attributes(plan))
-
-          # Collect attribute custom methods to call after element creation
-          attribute_custom_methods = []
-
-          # Add regular attributes (non-xmlns)
-          mapping.attributes.each do |attribute_rule|
-            next if options[:except]&.include?(attribute_rule.to)
-
-            # Collect custom methods for later execution (after element is created)
-            if attribute_rule.custom_methods[:to]
-              attribute_custom_methods << attribute_rule
-              next
-            end
-
-            mapping_rule_name = if attribute_rule.multiple_mappings?
-                                  attribute_rule.name.first
-                                else
-                                  attribute_rule.name
-                                end
-
-            attr = attribute_definition_for(element, attribute_rule,
-                                            mapper_class: mapper_class)
-            value = attribute_rule.to_value_for(element)
-
-            # Handle as_list and delimiter BEFORE serialization for array values
-            # These features convert arrays to delimited strings before serialization
-            if value.is_a?(Array)
-              if attribute_rule.as_list && attribute_rule.as_list[:export]
-                value = attribute_rule.as_list[:export].call(value)
-              elsif attribute_rule.delimiter
-                value = value.join(attribute_rule.delimiter)
-              end
-            end
-
-            value = attr.serialize(value, :xml, @register) if attr
-            value = ExportTransformer.call(value, attribute_rule, attr,
-                                           format: :xml)
-
-            if render_element?(attribute_rule, element, value)
-              # Resolve attribute namespace using extracted module
-              ns_info = AttributeNamespaceResolver.resolve(
-                rule: attribute_rule,
-                attribute: attr,
-                plan: plan,
-                mapper_class: mapper_class,
-                register: @register,
-              )
-
-              # Build qualified attribute name based on W3C semantics
-              attr_name = AttributeNamespaceResolver.build_qualified_name(
-                ns_info,
-                mapping_rule_name,
-                attribute_rule,
-              )
-              attributes[attr_name] = value ? value.to_s : value
-
-              # Add local xmlns declaration if needed
-              if ns_info[:needs_local_declaration]
-                attributes[ns_info[:local_xmlns_attr]] =
-                  ns_info[:local_xmlns_uri]
-              end
-            end
-          end
-
-          # Add schema_location attribute from ElementNode if present
-          # This is for the plan-based path where schema_location_attr is computed during planning
-          attributes.merge!(plan.root_node.schema_location_attr) if plan&.root_node&.schema_location_attr
-
-          # Determine prefix from plan using extracted module
-          prefix_info = ElementPrefixResolver.resolve(mapping: mapping,
-                                                      plan: plan)
-          prefix = prefix_info[:prefix]
-          ns_decl = prefix_info[:ns_decl]
-
-          # Check if element's own namespace needs local declaration (out of scope)
-          if ns_decl&.local_on_use?
-            # FIX: Handle both default (nil prefix) and prefixed namespaces
-            xmlns_attr = if prefix
-                           "xmlns:#{prefix}"
-                         else
-                           "xmlns"
-                         end
-            attributes[xmlns_attr] = ns_decl.uri
-          end
-
-          # W3C COMPLIANCE: Detect if element needs xmlns="" using extracted module
-          if BlankNamespaceHandler.needs_xmlns_blank?(mapping: mapping,
-                                                      options: options)
-            attributes["xmlns"] = ""
-          end
-
-          # Native type inheritance fix: handle local_on_use xmlns="" even if parents uses default format
-          xmlns_prefix = nil
-          xmlns_ns = nil
-          if mapping&.namespace_class && plan
-            xmlns_ns = plan.namespace_for_class(mapping.namespace_class)
-            xmlns_prefix = xmlns_ns&.prefix
-          end
-          if xmlns_ns&.local_on_use? && !mapping.namespace_uri
-            attributes["xmlns:#{xmlns_prefix}"] =
-              xmlns_ns&.uri || mapping.namespace_uri
-          end
-
-          tag_name = options[:tag_name] || mapping.root_element
-          return if options[:except]&.include?(tag_name)
-
-          # Track if THIS element uses default namespace format
-          # Children will need this info to know if they should add xmlns=""
-          this_element_uses_default_ns = mapping.namespace_class &&
-            plan.namespace_for_class(mapping.namespace_class)&.default_format?
-
-          # Get element_form_default from this element's namespace for children
-          parent_element_form_default = mapping.namespace_class&.element_form_default
-
-          xml.create_and_add_element(tag_name, attributes: attributes,
-                                               prefix: prefix) do |xml|
-            # Call attribute custom methods now that element is created
-            attribute_custom_methods.each do |attribute_rule|
-              mapper_class.new.send(attribute_rule.custom_methods[:to],
-                                    element, xml.parent, xml)
-            end
-
-            if ordered?(element, options.merge(mapper_class: mapper_class))
-              build_ordered_element_with_plan(xml, element, plan,
-                                              options.merge(
-                                                mapper_class: mapper_class,
-                                                parent_prefix: prefix,
-                                                parent_uses_default_ns: this_element_uses_default_ns,
-                                                parent_element_form_default: parent_element_form_default,
-                                                parent_ns_decl: ns_decl,
-                                              ))
-            else
-              build_unordered_children_with_plan(xml, element, plan,
-                                                 options.merge(
-                                                   mapper_class: mapper_class,
-                                                   parent_prefix: prefix,
-                                                   parent_uses_default_ns: this_element_uses_default_ns,
-                                                   parent_element_form_default: parent_element_form_default,
-                                                   parent_ns_decl: ns_decl,
-                                                 ))
-            end
-          end
-        end
-
-        # Build element children in the original order (for ordered content)
-        #
-        # This method preserves the order of elements as they appeared in the
-        # original XML, using element.element_order to iterate through elements.
-        #
-        # @param xml [Builder] XML builder
-        # @param element [Object] model instance
-        # @param plan [DeclarationPlan] namespace declaration plan
-
-        # NOTE: build_unordered_children_with_plan and build_ordered_element_with_plan
-        # are inherited from BaseAdapter - no need to override
-
-        def build_nested_element_with_plan(xml, value, element_rule,
-    attribute_def, plan, options, parent_plan: nil)
-          if value.is_a?(Lutaml::Model::Collection)
-            items = value.collection
-            attr_type = attribute_def.type(@register)
-
-            if attr_type <= Lutaml::Model::Type::Value
-              # Simple types - serialize each item
-              items.each do |val|
-                build_element_value_with_plan(xml, element_rule, val, attribute_def,
-                                              plan: plan, mapping: nil, options: options.merge(element: val))
-              end
-            else
-              # Model types - build elements
-              items.each do |val|
-                # For polymorphic collections, use each item's actual class
-                item_mapper_class = if polymorphic_value?(attribute_def, val)
-                                      val.class
-                                    else
-                                      attr_type
-                                    end
-
-                # Collect and plan for each item
-                item_mapping = item_mapper_class.mappings_for(:xml)
-                if item_mapping
-                  collector = NamespaceCollector.new(@register)
-                  item_needs = collector.collect(val, item_mapping)
-
-                  planner = DeclarationPlanner.new(@register)
-                  item_plan = planner.plan(val, item_mapping, item_needs,
-                                           parent_plan: plan, options: options)
-                else
-                  item_plan = plan
-                end
-
-                # Performance: Use dup with direct assignment to avoid merge allocations
-                # when mapper_class differs from current
-                if options[:mapper_class] == item_mapper_class
-                  item_options = options
-                else
-                  item_options = options.dup
-                  item_options[:mapper_class] = item_mapper_class
-                end
-                if item_plan
-                  build_element_with_plan(xml, val, item_plan, item_options)
-                else
-                  build_element(xml, val, item_options)
-                end
-              end
-            end
-          else
-            # Single Serialize instance
-            # Performance: Use dup with direct assignment
-            child_mapper = attribute_def.type(@register)
-            if options[:mapper_class] == child_mapper
-              child_options = options
-            else
-              child_options = options.dup
-              child_options[:mapper_class] = child_mapper
-            end
-            build_element_with_plan(xml, value, plan, child_options)
-          end
-        end
-
-        # Build simple element value with plan
-        #
-        # @param xml [Builder] XML builder
-        # @param element_rule [MappingRule] element mapping rule
-        # @param value [Object] value to serialize
-        # @param attribute_def [Attribute] attribute definition
-        # @param plan [DeclarationPlan] namespace plan
-        # @param mapping [Xml::Mapping] optional mapping
-        # @param options [Hash] serialization options
-        def build_element_value_with_plan(xml, element_rule, value,
-    attribute_def, plan:, mapping: nil, options: {})
-          # Handle array values by creating multiple elements
-          if value.is_a?(Array)
-            value.each do |val|
-              build_element_value_with_plan(xml, element_rule, val, attribute_def,
-                                            plan: plan, mapping: mapping, options: options)
-            end
-            return
-          end
-
-          return unless render_element?(element_rule, options[:element], value)
-
-          # Get namespace info for this element
-          mapping_local = mapping || options[:mapper_class]&.mappings_for(:xml)
-          ns_info = if mapping_local
-                      # Try to resolve namespace using local mapping
-                      begin
-                        NamespaceResolver.new(@register).resolve_for_element(
-                          element_rule, attribute_def, mapping_local, plan, options
-                        )
-                      rescue StandardError
-                        # Fallback to default behavior
-                        { prefix: nil, ns_info: nil }
-                      end
-                    else
-                      { prefix: nil, ns_info: nil }
-                    end
-
-          prefix = ns_info[:prefix]
-
-          # Get child's plan if available
-          child_plan = plan&.child_plan(element_rule.to)
-
-          if value.is_a?(Lutaml::Model::Serialize)
-            # Nested Serialize object
-            child_mapper_class = value.class
-            child_mapper_class.mappings_for(:xml)
-
-            # Performance: Use dup with direct assignment to avoid merge allocations
-            if options[:mapper_class] == child_mapper_class
-              child_options = options
-            else
-              child_options = options.dup
-              child_options[:mapper_class] = child_mapper_class
-            end
-
-            if child_plan
-              build_element_with_plan(xml, value, child_plan, child_options)
-            else
-              build_element(xml, value, child_options)
-            end
-          elsif value.nil? && element_rule.render_nil?
-            # Render nil value
-            element_name = element_rule.multiple_mappings? ? element_rule.name.first : element_rule.name
-            xml.create_and_add_element(element_name,
-                                       prefix: prefix) do |inner_xml|
-              inner_xml.text("")
-            end
-          elsif value
-            # Simple string value
-            element_name = element_rule.multiple_mappings? ? element_rule.name.first : element_rule.name
-            xml.create_and_add_element(element_name,
-                                       prefix: prefix) do |inner_xml|
-              if element_rule.cdata
-                inner_xml.cdata(value.to_s)
-              else
-                inner_xml.text(value.to_s)
-              end
-            end
-          end
-        end
-
-        # Build XML from XmlDataModel::XmlElement structure
-        #
-        # @param xml [Builder] XML builder
-        # @param element [XmlDataModel::XmlElement] element to build
-        # @param parent_uses_default_ns [Boolean] parent uses default namespace format
-        # @param parent_element_form_default [Symbol] parent's element_form_default
-        # @param parent_namespace_class [Class] parent's namespace class
-        def build_xml_element(xml, element, parent_uses_default_ns: false,
-    parent_element_form_default: nil, parent_namespace_class: nil)
-          # Prepare attributes hash
-          attributes = {}
-
-          # Determine if attributes should be qualified based on element's namespace
-          element_ns_class = element.namespace_class
-          attribute_form_default = element_ns_class&.attribute_form_default || :unqualified
-          element_prefix = element_ns_class&.prefix_default
-
-          # Get element_form_default for children
-          # Only set when explicitly configured, not when defaulted to :unqualified
-          this_element_form_default = if element_ns_class&.element_form_default_set?
-                                        element_ns_class.element_form_default
-                                      end
-
-          # Add regular attributes
-          element.attributes.each do |attr|
-            # Determine attribute name with namespace consideration
-            attr_name = if attr.namespace_class
-                          # Check if attribute is in SAME namespace as element
-                          if attr.namespace_class == element_ns_class && attribute_form_default == :unqualified
-                            # Same namespace + unqualified → NO prefix (W3C rule)
-                            attr.name
-                          else
-                            # Different namespace OR qualified → use prefix
-                            attr_prefix = attr.namespace_class.prefix_default
-                            attr_prefix ? "#{attr_prefix}:#{attr.name}" : attr.name
-                          end
-                        elsif attribute_form_default == :qualified && element_prefix
-                          # Attribute inherits element's namespace when qualified
-                          "#{element_prefix}:#{attr.name}"
-                        else
-                          # Unqualified attribute
-                          attr.name
-                        end
-            attributes[attr_name] = attr.value
-          end
-
-          # Determine element name with namespace prefix
-          tag_name = element.name
-          # CRITICAL FIX: element_form_default: :qualified means child elements inherit parent's namespace PREFIX
-          # even when child has NO explicit namespace_class
-          prefix = if element_ns_class && element_prefix
-                     # Element has explicit prefix_default - use prefix format
-                     element_prefix
-                   elsif !element_ns_class && parent_element_form_default == :qualified && parent_namespace_class&.prefix_default
-                     # Child has NO namespace, but parent has :qualified form_default
-                     # Child should INHERIT parent's namespace PREFIX
-                     parent_namespace_class.prefix_default
-                   else
-                     # No prefix (default format or no parent namespace)
-                     nil
-                   end
-
-          # Track if THIS element uses default namespace format for children
-          this_element_uses_default_ns = false
-
-          # Add namespace declaration if element has namespace
-          if element.namespace_class
-            ns_uri = element.namespace_class.uri
-
-            if prefix
-              attributes["xmlns:#{prefix}"] = ns_uri
-              # W3C Compliance: When parent uses default namespace and child declares
-              # a DIFFERENT prefixed namespace, child must also add xmlns="" to prevent
-              # its children from inheriting parent's default namespace
-              if parent_uses_default_ns
-                attributes["xmlns"] = ""
-              end
-            else
-              attributes["xmlns"] = ns_uri
-              this_element_uses_default_ns = true
-            end
-          elsif parent_uses_default_ns
-            # W3C Compliance: Element has no namespace (blank namespace)
-            # Check if should inherit parent's namespace based on element_form_default
-            # Parent uses default namespace format
-            if parent_element_form_default == :qualified
-              # Child should INHERIT parent's namespace - no xmlns="" needed
-              # The child is in parent namespace (qualified)
-            elsif parent_element_form_default == :unqualified
-              # Parent's element_form_default is :unqualified - child should be in blank namespace
-              # WITHOUT xmlns="" (no xmlns attribute at all). The child is simply
-              # not in any namespace, which is the correct W3C behavior for unqualified.
-            else
-              # element_form_default is not set (nil/default :unqualified)
-              # Child needs xmlns="" to explicitly opt out of parent's default namespace
-              attributes["xmlns"] = ""
-            end
-          end
-
-          # Check if element was created from nil value with render_nil option
-          # Add xsi:nil="true" attribute for W3C compliance
-          if element.respond_to?(:xsi_nil) && element.xsi_nil
-            attributes["xsi:nil"] = true
-          end
-
-          # Create element
-          xml.create_and_add_element(tag_name, attributes: attributes,
-                                               prefix: prefix) do |inner_xml|
-            # Add text content if present
-            if element.text_content
-              # Check if content should be wrapped in CDATA
-              if element.cdata
-                inner_xml.cdata(element.text_content)
-              else
-                add_text_with_entities(inner_xml.parent,
-                                       element.text_content.to_s, inner_xml.doc)
-              end
-            end
-
-            # Recursively build child elements, passing namespace context
-            element.children.each do |child|
-              if child.is_a?(Lutaml::Xml::DataModel::XmlElement)
-                build_xml_element(inner_xml, child,
-                                  parent_uses_default_ns: this_element_uses_default_ns,
-                                  parent_element_form_default: this_element_form_default,
-                                  parent_namespace_class: element_ns_class)
-              elsif child.is_a?(String)
-                inner_xml.text(child)
-              end
-            end
-          end
-        end
-
-        # Build XML from XmlDataModel::XmlElement using DeclarationPlan tree (PARALLEL TRAVERSAL)
-        #
-        # Constructs Moxml node tree for XML serialization.
-        #
-        # @param xml [Builder] XML builder (provides doc access)
-        # @param xml_element [XmlDataModel::XmlElement] Element content
-        # @param plan [DeclarationPlan] Declaration plan with tree structure
-        # @param options [Hash] Serialization options
-        def build_xml_element_with_plan(xml, xml_element, plan, options = {})
-          moxml_doc = xml.doc
-
-          root_node = build_xml_node(xml_element, plan.root_node, moxml_doc,
-                                     plan.global_prefix_registry, nil, options: options, plan: plan)
-          moxml_doc.root = root_node
-
-          # Add processing instructions before the root element.
-          # reverse_each + add_previous_sibling maintains original order:
-          # each PI is inserted before the root (and before previously-inserted PIs).
-          xml_element.processing_instructions.reverse_each do |pi|
-            pi_node = moxml_doc.create_processing_instruction(pi.target,
-                                                              pi.content)
-            root_node.add_previous_sibling(pi_node)
-          end
-        end
-
-        private
-
-        # Override BaseAdapter hook to preserve entity references.
-        def add_text_nodes(element, text, doc)
-          add_text_with_entities(element, text, doc)
-        end
-
-        # Builds Moxml node tree from XmlDataModel::XmlElement content and
-        # DeclarationPlan decisions (PARALLEL TRAVERSAL).
-        #
-        # Uses Moxml APIs for all DOM operations:
-        # - doc.create_element for document-aware node creation
-        # - element.in_scope_namespaces for in-scope namespace query
-        # - element.namespace= for namespace assignment
-        # - doc.create_text/create_cdata/create_entity_reference for child nodes
-        #
-        # @param xml_element [XmlDataModel::XmlElement] Content
-        # @param element_node [ElementNode] Decisions
-        # @param doc [Moxml::Document] Document
-        # @param global_registry [Hash] Global prefix registry (URI => prefix)
-        # @param parent [Moxml::Element, nil] Parent element for namespace inheritance
-        # @param options [Hash] Serialization options
-        # @param plan [DeclarationPlan] Declaration plan with original namespace URIs
-        # @param previous_sibling_had_xmlns_blank [Boolean] Previous sibling had xmlns="" for W3C optimization
-        # @return [Moxml::Element] Created node
-        def build_xml_node(xml_element, element_node, doc,
-    global_registry, parent = nil, options: {}, plan: nil, previous_sibling_had_xmlns_blank: false)
-          qualified_name = element_node.qualified_name
-
-          # Split qualified_name to get prefix and local_name
-          # IMPORTANT: Only split on SINGLE colon (namespace prefix separator),
-          # not on double colon (::) which is a Ruby module path separator.
-          # e.g., "prefix:name" should split to ["prefix", "name"]
-          # but "Module::Class" should NOT be split (use whole name as local_name)
-          if qualified_name.include?(":") && !qualified_name.include?("::")
-            _, local_name = qualified_name.split(":", 2)
-          else
-            local_name = qualified_name
-          end
-
-          element = doc.create_element(local_name)
-
-          # Add xmlns declarations FIRST (before adding to parent!)
-          # This ensures the element's own namespace is declared before it can inherit parent's
-          # Keys: nil = default namespace, "prefix" = prefixed namespace
-          original_ns_uris = plan&.original_namespace_uris || {}
-          use_prefix_option = options[:use_prefix]
-          element_node.hoisted_declarations.each do |key, uri|
-            next if uri == "http://www.w3.org/XML/1998/namespace"
-
-            # Convert FPI to URN if necessary (Nokogiri requires valid URI)
-            # Only apply original_ns_uris conversion when preserving original format.
-            # When use_prefix is explicitly set, we're using system's format preferences.
-            effective_uri = if self.class.fpi?(uri)
-                              self.class.fpi_to_urn(uri)
-                            elsif use_prefix_option.nil?
-                              # Preserving original format - use alias URIs from original
-                              original_ns_uris[uri] || uri
-                            else
-                              # Using explicit format preference - use canonical URIs
-                              uri
-                            end
-
-            if key.nil?
-              # Default namespace (xmlns="uri")
-              element.add_namespace(nil, effective_uri)
-            else
-              # Prefixed namespace (xmlns:prefix="uri")
-              element.add_namespace(key, effective_uri)
-            end
-          end
-
-          # NOW set element's namespace (before adding to parent)
-          # This ensures the element uses its own namespace, not inherited from parent
-          # CRITICAL: Use the decision's namespace_class from element_node, not the element's namespace_class
-          # The decision's namespace_class may be nil (blank namespace) even if the element has a namespace_class
-          # set during transformation (e.g., when form: :unqualified is set)
-          #
-          # IMPORTANT: Use xml_element's namespace_class for the namespace decision
-          # The element_node (DeclarationPlan::ElementNode) doesn't have namespace_class
-          # because namespace decisions are stored in the xml_element during transformation
-          #
-          # IMPORTANT: When xml_element.namespace_class is nil, check if this is an explicit decision
-          # (blank namespace) or if no decision was made. We can tell by checking if the element has
-          # a form attribute set to :unqualified.
-          target_namespace_class = xml_element.namespace_class
-          # Check if this is an explicit "blank namespace" decision (form: :unqualified)
-          # If so, don't fall back to any namespace_class
-          if target_namespace_class.nil? && xml_element.respond_to?(:form) && xml_element.form == :unqualified
-            # Explicit blank namespace decision - don't set any namespace
-            target_namespace_class = nil
-          end
-          # Note: If no explicit decision, we keep target_namespace_class as nil
-          # and don't fall back to anything (no default namespace_class)
-
-          if target_namespace_class && target_namespace_class != :blank
-            # Use the prefix to find the namespace when available.
-            # This is more reliable than matching by URI because hoisted_declarations
-            # may contain canonical URIs while the actual namespace was added using
-            # alias URIs (via original_ns_uris conversion).
-            target_prefix = element_node.use_prefix
-            target_uri = target_namespace_class.uri
-            ns = if target_prefix
-                   # Find namespace by prefix (most reliable - prefix is unique per element)
-                   element.in_scope_namespaces.find do |n|
-                     n.prefix == target_prefix
-                   end
-                 else
-                   # Fall back to URI-based lookup for default namespace
-                   element.in_scope_namespaces.find do |n|
-                     n.uri == target_uri && n.prefix.nil?
-                   end
-                 end
-            if ns
-              element.namespace = ns
-            elsif target_prefix
-              # CRITICAL FIX: Check if namespace is declared on parent before adding locally
-              # When parent declares the namespace with the SAME format (prefix or default),
-              # child should use parent's namespace declaration without re-declaring it.
-              # Also check namespace aliases: if parent declared alias URI and child uses
-              # canonical URI (or vice versa), the namespace is already established on parent.
-              target_prefix = element_node.use_prefix
-              parent_has_namespace = parent_has_matching_namespace?(parent, target_uri,
-                                                                    target_namespace_class)
-
-              if parent_has_namespace
-                # Parent has the namespace declared - find the matching namespace object
-                # Must check all URIs (canonical + aliases) since parent may have declared
-                # with an alias URI while child uses canonical (or vice versa)
-                matching_uris = if target_namespace_class.respond_to?(:all_uris)
-                                  target_namespace_class.all_uris
-                                else
-                                  [target_uri]
-                                end
-                parent_ns = if target_prefix
-                              parent.in_scope_namespaces.find do |n|
-                                matching_uris.include?(n.uri) && n.prefix == target_prefix
-                              end
-                            else
-                              parent.in_scope_namespaces.find do |n|
-                                matching_uris.include?(n.uri) && n.prefix.nil?
-                              end
-                            end
-
-                if parent_ns
-                  # Parent has the SAME format declaration - use parent's namespace
-                  # Defer setting until after add_child so element is in the tree.
-                  @deferred_namespace = parent_ns
-                  nil
-                else
-                  # Parent has different format - add namespace declaration locally
-                  if target_prefix.nil?
-                    # Default format: add xmlns="uri" declaration
-                    element.add_namespace(nil, target_uri)
-                    # Find the newly added namespace and set it
-                    ns = element.in_scope_namespaces.find do |n|
-                      n.uri == target_uri
-                    end
-                  else
-                    # Prefix format: add xmlns:prefix="uri" declaration
-                    element.add_namespace(target_prefix, target_uri)
-                    # Find the newly added namespace and set it
-                    ns = element.in_scope_namespaces.find do |n|
-                      n.uri == target_uri && n.prefix == target_prefix
-                    end
-                  end
-                  element.namespace = ns if ns
-                end
-              elsif target_prefix.nil?
-                # Default format: add xmlns="uri" declaration
-                element.add_namespace(nil, target_uri)
-                # Find the newly added namespace and set it
-                ns = element.in_scope_namespaces.find do |n|
-                  n.uri == target_uri
-                end
-                element.namespace = ns if ns
-              else
-                # Prefix format: add xmlns:prefix="uri" declaration
-                element.add_namespace(target_prefix, target_uri)
-                # Find the newly added namespace and set it
-                ns = element.in_scope_namespaces.find do |n|
-                  n.uri == target_uri && n.prefix == target_prefix
-                end
-                element.namespace = ns if ns
-              end
-            end
-          end
-
-          # Add to parent AFTER namespace is set
-          # This prevents the element from inheriting parent's namespace before declaring its own
-          parent&.add_child(element)
-
-          # CRITICAL FIX: Set deferred namespace after adding to parent
-          # This allows the element to use parent's namespace declaration without re-declaring it
-          if @deferred_namespace
-            element.namespace = @deferred_namespace
-            @deferred_namespace = nil
-          end
-
-          # CRITICAL FIX: Handle blank namespace elements
-          # When element has no namespace_class, it should remain in blank namespace
-          # Even if parent uses prefix format, the child should NOT inherit parent's namespace
-          # Also applies when form: :unqualified is set (element should be in blank namespace)
-          if !xml_element.namespace_class || xml_element.namespace_class == :blank ||
-              (xml_element.respond_to?(:form) && xml_element.form == :unqualified)
-            # Explicitly set element to blank namespace (no namespace)
-            # This prevents the child from inheriting parent's namespace
-            element.namespace = nil
-          end
-
-          # W3C Compliance: Add xmlns="" if element is in blank namespace
-          # and needs to opt out of parent's default namespace
-          # W3C Optimization: Only first sibling needs xmlns="", subsequent inherit
-          # Only apply optimization when pretty: true is set
-          if element_node.needs_xmlns_blank && (options[:pretty] ? !previous_sibling_had_xmlns_blank : true)
-            # Add xmlns="" as an attribute (Nokogiri-specific)
-            element["xmlns"] = ""
-          end
-
-          # Add regular attributes (PARALLEL TRAVERSAL by index)
-          apply_plan_attributes(xml_element, element_node, element)
-
-          # Check if element was created from nil value with render_nil option
-          # Add xsi:nil="true" attribute for W3C compliance
-          if xml_element.respond_to?(:xsi_nil) && xml_element.xsi_nil
-            element["xsi:nil"] = true
-          end
-
-          # Add schema_location attribute from ElementNode if present
-          element_node.schema_location_attr&.each do |attr_name, attr_value|
-            element[attr_name] = attr_value
-          end
-
-          # Handle raw content (map_all directive)
-          # If @raw_content exists, parse and add as XML fragment
-          # NOTE: We do NOT return early here because the element may have
-          # children that also need to be processed. Raw content should be
-          # added alongside children, not replace them.
-          if xml_element.respond_to?(:raw_content)
-            raw_content = xml_element.raw_content
-            if raw_content && !raw_content.to_s.empty?
-              # Parse raw XML content and add as children using moxml
-              # Use inner_xml= approach: parse wrapper, then move children to element
-              parsed_fragment = doc.context.parse("<__root__>#{raw_content}</__root__>")
-              parsed_fragment.root&.children&.each do |child_node|
-                element.add_child(child_node)
-              end
-              # Do NOT return early - continue to process element's children
-            end
-          end
-
-          # Recursively build children (PARALLEL TRAVERSAL by index)
-          # Pass THIS element as parent so children can inherit namespaces
-          child_element_index = 0
-          previous_sibling_had_xmlns_blank = false
-          xml_element.children.each do |xml_child| # rubocop:disable Metrics/BlockLength
-            # Entity reference nodes are preserved via the marker
-            # preprocessing approach in NokogiriAdapter.parse.
-            if xml_child.is_a?(Lutaml::Xml::NokogiriElement) &&
-                xml_child.adapter_node.respond_to?(:entity_reference?) &&
-                xml_child.adapter_node.entity_reference?
-              entity_node = doc.create_entity_reference(xml_child.adapter_node.name)
-              element.add_child(entity_node)
-              next
-            elsif xml_child.is_a?(Lutaml::Xml::DataModel::XmlElement)
-              child_node = element_node.element_nodes[child_element_index]
-              child_element_index += 1
-
-              # Recurse - child auto-adds itself to element (parent)
-              # Pass previous_sibling_had_xmlns_blank for W3C optimization
-              build_xml_node(xml_child, child_node, doc, global_registry, element,
-                             options: options, plan: plan,
-                             previous_sibling_had_xmlns_blank: previous_sibling_had_xmlns_blank)
-              # Track if this child had xmlns="" for next sibling
-              # Blank namespace children get xmlns="" to opt out of parent's default namespace
-              if !xml_child.namespace_class && xml_element.namespace_class
-                previous_sibling_had_xmlns_blank = true
-              end
-            elsif xml_child.is_a?(String)
-              add_content_node(element, xml_child, doc,
-                               cdata: xml_element.cdata && !xml_child.strip.empty?)
-            elsif xml_child.is_a?(::Lutaml::Xml::DataModel::XmlComment)
-              comment_node = doc.create_comment(xml_child.content)
-              element.add_child(comment_node)
-            end
-          end
-
-          # Add text content AFTER child elements
-          if xml_element.text_content
-            add_content_node(element, xml_element.text_content.to_s,
-                             doc, cdata: xml_element.cdata)
-          end
-
-          element
-        end
-
-        # Standard XML predefined entities — these are always resolved by the
-        # XML parser and must NOT be turned into EntityReference nodes during
-        # serialization.  If we created an EntityReference for e.g. "lt", the
-        # output would render as `<` instead of preserving the literal text
-        # `&lt;`, which corrupts double-encoded content like `&amp;lt;`.
-        STANDARD_XML_ENTITIES = %w[lt gt amp apos quot].freeze
-
-        # Add text content to an element, preserving entity reference patterns.
-        # Only non-standard named entities (e.g. &copy;, &nbsp;, &mdash;) are
-        # promoted to EntityReference nodes.  Standard XML entities, numeric
-        # character references, and all other text are added as plain text nodes
-        # so the XML serializer handles proper escaping.
-        #
-        # Uses Moxml's doc.create_text/create_entity_reference for node creation.
-        #
-        # @param element [Moxml::Element] Target element
-        # @param text [String] Text content possibly containing entity references
-        # @param doc [Moxml::Document] Document for node creation
-        def add_text_with_entities(element, text, doc)
-          entity_pattern = /(&(?:\w+|#\d+|#x[\da-fA-F]+);)/
-          parts = text.to_s.split(entity_pattern, -1)
-          parts.each do |part|
-            next if part.empty?
-
-            # Only non-standard named entities become EntityReference nodes.
-            # Standard XML entities (lt, gt, amp, apos, quot) and numeric
-            # character references (&#NNN;, &#xHHH;) must remain as text so
-            # the serializer escapes them correctly (e.g. &lt; → &amp;lt;).
-            # Entity names must start with a letter per the XML specification,
-            # so patterns like &1; are NOT entity references.
-            # NOTE: use #match (not #match?) because match? does not set $1.
-            if (m = part.match(/\A&([a-zA-Z]\w*);\z/)) && !STANDARD_XML_ENTITIES.include?(m[1])
-              entity_name = m[1]
-              entity_node = doc.create_entity_reference(entity_name)
-              element.add_child(entity_node)
-            else
-              text_node = doc.create_text(part)
-              element.add_child(text_node)
-            end
-          end
-        end
-
-        # Check if parent element has a matching namespace declaration in scope.
-        # Uses Moxml's in_scope_namespaces for namespace query.
-        def parent_has_matching_namespace?(parent, target_uri,
-target_namespace_class)
-          return false unless parent
-
-          parent_uris = parent.in_scope_namespaces.map(&:uri)
-
-          # Check exact match first
-          return true if parent_uris.include?(target_uri)
-
-          # Check if parent declared an alias URI for the same namespace
-          if target_namespace_class.respond_to?(:all_uris)
-            all_ns_uris = target_namespace_class.all_uris
-            return parent_uris.any? { |href| all_ns_uris.include?(href) }
-          end
-
-          false
-        end
-
-        # Post-process XML string to fix OOXML format issues.
-        # Handles two normalization rules:
-        # 1. Boolean elements: <w:elem w:val="true"/> -> <w:elem/>
-        # 2. XML namespace attribute: <w:t w:xml:space=...> -> <w:t xml:space=...>
-        #
-        # @param xml [String] The XML string to process
-        # @return [String] The processed XML string
-        # OOXML boolean element names: self-closing elements where presence = true.
-        # This is a whitelist of known boolean element names to avoid incorrectly
-        # transforming non-boolean elements like numId, colSpan, etc.
-        OOXML_BOOLEAN_ELEMENTS = %w[
-          b i strike bCs iCs smallCaps caps vanish noProof
-          shadow emboss imprint keepNext keepLines outline
-          tblHeader cantSplit contextualSpacing highlight
-          rPr pPr trPr tcPr
-        ].freeze
-
-        def fix_ooxml_format(xml)
-          # Build regex pattern that only matches known boolean element names
-          bool_elem_pattern = OOXML_BOOLEAN_ELEMENTS.join("|")
-
-          # Fix self-closing: <ns:elem w:val="true"/> or <ns:elem w:val="1"/>
-          # Only for known boolean elements
-          xml = xml.gsub(
-            /<([a-zA-Z][a-zA-Z0-9]*):(#{bool_elem_pattern})(\s+w:val=")(true|1)("\s*\/?>)/,
-          ) { "<#{$1}:#{$2}/>" }
-
-          # Fix with content: <ns:elem w:val="true">true</ns:elem> or <ns:elem w:val="1">1</ns:elem>
-          xml = xml.gsub(
-            /<([a-zA-Z][a-zA-Z0-9]*):(#{bool_elem_pattern})(\s+w:val=")(true|1)(">)true<\/\1:\2>/,
-          ) { "<#{$1}:#{$2}>" }
-
-          # Fix content-only: <ns:elem>true</ns:elem> -> <ns:elem/>
-          # For elements that serialize boolean value as text content
-          xml = xml.gsub(
-            /<([a-zA-Z][a-zA-Z0-9]*):(#{bool_elem_pattern})>true<\/\1:\2>/,
-          ) { "<#{$1}:#{$2}/>" }
-
-          # Fix xml:space attribute: <w:t w:xml:space=...> -> <w:t xml:space=...>
-          # The xml: attribute belongs to the xml: namespace, not w:
-          xml.gsub(/\bw:xml:space=/, "xml:space=")
-        end
+        MOXML_ADAPTER = Moxml::Adapter::Nokogiri
+        BUILDER_CLASS = Builder::Nokogiri
+        PARSED_ELEMENT_CLASS = Lutaml::Xml::NokogiriElement
       end
     end
   end