moxml 0.5.30 → 0.5.32

data/lib/moxml/adapter/leptris.rb

@@ -23,6 +23,58 @@ module Moxml
       # the adapter no longer carries accommodation paths for them.
       MINIMUM_BINDING_VERSION = "1.9.32"
 
+      # leptris_parse_html_string shipped in bindings 1.9.80
+      # (libleptris 1.9.75, engine #659) as Leptris::XML.parse_html.
+      HTML_PARSE_SUPPORTED =
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.80")
+
+      # Attribute-node xpath results carry proper wrappers since
+      # 1.9.105 (leptris-ruby#153: ResultAttr with name/value);
+      # before that the native gate routed them to the Ruby engine.
+      ATTR_RESULT_NATIVE =
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.105")
+
+      # Native C14N delegation probe: the engine's C14N must
+      # byte-match the Ruby reference (ported from canon) on a
+      # namespace-sorting + attributes + comments shape before
+      # Moxml::C14n hands the default path to it. The engine
+      # currently emits namespace declarations in document order
+      # instead of lexicographic (filed leptris/leptris#881); the
+      # probe auto-adopts the native path once a fixed build lands —
+      # no moxml release needed.
+      # Lazy, not load-time: the probe exercises the wrapper layer
+      # (Document/serialize/C14n), which is circular while THIS
+      # adapter file is still loading — the load-time form rescued
+      # to false on every build and masked a landed engine fix.
+      def self.native_c14n_byte_safe?
+        return @native_c14n_byte_safe unless @native_c14n_byte_safe.nil?
+
+        @native_c14n_byte_safe = begin
+          probe_xml = %(<?xml version="1.0"?><doc xmlns:p="urn:p" xmlns="urn:d" b="2" a="1"><e p:x="v" z="w">t &amp; u</e><!-- c --></doc>)
+          native_doc = ::Leptris::XML::Document.parse(probe_xml)
+          native = native_doc.root.canonicalize(
+            ::Leptris::XML::FFI::C14N_1_0, nil,
+            mode: ::Leptris::XML::FFI::C14N_MODE_CANONICAL
+          )
+          wrapper = Moxml::Document.new(native_doc, Moxml::Context.new(:leptris))
+          reference = Moxml::C14n::Inclusive10.new.canonicalize(wrapper.root)
+          native == reference
+        rescue StandardError
+          false
+        end
+      end
+
+      # Bumped whenever a document's :entity_markers flag is written
+      # (parse, parse_html, entity-reference mint) so wrapper-level
+      # entity_bearing? memos invalidate.
+      def self.serialize_generation
+        @serialize_generation ||= 0
+      end
+
+      def self.bump_serialize_generation
+        @serialize_generation = serialize_generation + 1
+      end
+
       # leptris-ruby#103: prefixed attribute tests inside predicates
       # stopped resolving through the document's in-scope declarations
       # on released 1.9.37–1.9.39; 1.9.40 (engine 1.9.14+) restored
@@ -108,6 +160,39 @@ module Moxml
           doc.root = element
         end
 
+        def bare_set_qname_safe?
+          true
+        end
+
+        def bare_get_qname_safe?
+          true
+        end
+
+        # Expanded-name (URI + local) attribute VALUE lookup on the
+        # engine — the same match rule as the resolver (xmlns
+        # declarations invisible, no-namespace never matches a
+        # prefixed name), without materializing the attribute list.
+        def expanded_attr_value(element, uri, local)
+          element.attribute_ns(uri, local)
+        end
+
+        # Fast bare-name read: the binding call plus marker
+        # restoration when the document carries them (entity-free
+        # documents — the common case — skip the scan; parentless
+        # iterparse elements are never bearing).
+        def bare_attr_value(element, name)
+          value = element[name.to_s]
+          if value.is_a?(String) && entity_bearing?(element)
+            restore_entities(value)
+          else
+            value
+          end
+        end
+
+        def native_identity_stable?
+          true
+        end
+
         def parse(xml, options = {}, _context = nil)
           xml_string = xml.is_a?(IO) || xml.is_a?(StringIO) ? xml.read : xml.to_s
           # The marker flag rides preprocess's own `&` scan — no
@@ -153,11 +238,59 @@ module Moxml
 
           record_source_declaration(native_doc, processed)
           attachments.set(native_doc, :entity_markers, entity_markers)
+          bump_serialize_generation
           attachments.set(native_doc, :parse_errors, recover_errors) if recover_errors
 
           doc
         end
 
+        # Tolerant HTML4/5 parsing into the standard DOM (engine
+        # leptris/leptris#659): implied end tags, void elements,
+        # raw-text script/style, case-insensitive lowercased names,
+        # the HTML named-entity table, synthesized html/head/body.
+        # The engine decodes HTML entities directly into text — no
+        # marker pipeline, so the marker split scan is stood down.
+        # Incremental parse (libleptris v1.6/#586): yields completed
+        # elements as the parse runs; each prior subtree is released.
+        # Yielded elements are parentless (document nil) and valid
+        # only inside the block — the wrapper mirrors that lifetime.
+        def iterparse(xml, mode = :top_level, _context = nil, &block)
+          raise ArgumentError, "iterparse requires a block" unless block
+
+          ctx = _context || Context.new(:leptris)
+          ::Leptris::XML::Iterparse.parse(xml, mode: mode) do |element|
+            yield(Node.wrap(element, ctx))
+          end
+        end
+
+        def iterparse_file(path, mode = :top_level, _context = nil, &block)
+          raise ArgumentError, "iterparse_file requires a block" unless block
+
+          ctx = _context || Context.new(:leptris)
+          ::Leptris::XML::Iterparse.parse_file(path, mode: mode) do |element|
+            yield(Node.wrap(element, ctx))
+          end
+        end
+
+        def parse_html(html, _options = {}, _context = nil)
+          unless HTML_PARSE_SUPPORTED
+            raise Moxml::AdapterError.new(
+              "HTML parsing requires leptris >= 1.9.80 (have #{::Leptris::VERSION})",
+              adapter: name, operation: "parse_html",
+            )
+          end
+
+          html_string = html.is_a?(IO) || html.is_a?(StringIO) ? html.read : html.to_s
+          native_doc = begin
+            ::Leptris::XML.parse_html(html_string)
+          rescue ::Leptris::XML::ParseError => e
+            raise Moxml::ParseError.new(e.message)
+          end
+          attachments.set(native_doc, :entity_markers, false)
+          bump_serialize_generation
+          Document.new(native_doc, _context || Context.new(:leptris))
+        end
+
         # nil when no parse flag is requested — the binding treats a
         # nil options hash as plain defaults (matching libxml2/
         # Nokogiri semantics: blanks kept, no ATTLIST defaults).
@@ -393,7 +526,7 @@ module Moxml
           when ::Leptris::XML::Element then :element
           when ::Leptris::XML::CDATA then :cdata
           when ::Leptris::XML::Text, CustomizedLeptris::TextSegment then :text
-          when ::Leptris::XML::Attr then :attribute
+          when ::Leptris::XML::Attr, ::Leptris::XML::ResultAttr then :attribute
           when ::Leptris::XML::Comment then :comment
           when ::Leptris::XML::ProcessingInstruction, CustomizedLeptris::DocumentPI then :processing_instruction
           when ::Leptris::XML::Document then :document
@@ -455,7 +588,8 @@ module Moxml
             # dominates cold children cost. Cross-document moves of
             # marker-bearing text into an entity-free document degrade
             # to literal text.
-            return natives if attachments.get(node.document, :entity_markers) == false
+            return natives if node.document.nil? ||
+              attachments.get(node.document, :entity_markers) == false
 
             split_entity_markers(natives, node)
           end
@@ -561,6 +695,7 @@ module Moxml
               marker = parent.document.create_text_node("#{Entity::MARKER}#{child.name};")
               parent.add_child(marker)
               attachments.set(parent.document, :entity_markers, true)
+              bump_serialize_generation
               return child
             end
             child = parent.document.create_text_node(child) if child.is_a?(String)
@@ -772,8 +907,10 @@ module Moxml
                    end
           case result
           when ::Leptris::XML::NodeSet
-            nodes = result.to_a
-            first_only ? nodes.first : nodes
+            # The binding's #to_a mints one Ruby wrapper per result
+            # node; hand the native set through so .size/.first stay
+            # native-side (LazyNodeSet holds it unmaterialized).
+            first_only ? result.first : result.extend(Moxml::LazyNodeSet)
           else
             result
           end
@@ -785,6 +922,10 @@ module Moxml
         end
 
         def native_context_node?(node)
+          # Parentless elements (iterparse yields) have no document
+          # handle for the compiled eval — the Ruby engine owns them.
+          return false if node.is_a?(::Leptris::XML::Element) && node.document.nil?
+
           node.is_a?(::Leptris::XML::Document) ||
             node.is_a?(::Leptris::XML::Element)
         end
@@ -815,6 +956,12 @@ module Moxml
             next false if uses_xmlns_prefix?(ast)
             next false if !PREFIXED_ATTR_PREDICATES_NATIVE && prefixed_attribute_test?(ast)
 
+            # Attribute-node results are native since 1.9.105
+            # (leptris-ruby#153: ResultAttr wrappers with name/value);
+            # older bindings returned generic Node wrappers whose
+            # #name raised, so the Ruby engine owned them.
+            next true if selects_attribute_results?(ast) && ATTR_RESULT_NATIVE
+
             !selects_attribute_results?(ast)
           end
         rescue XPath::SyntaxError

data/lib/moxml/adapter/libxml.rb

@@ -923,12 +923,23 @@ module Moxml
           native.name
         end
 
+        # libxml-ruby 5.x exposes no external/system ID accessor on
+        # the DTD node — the DOCTYPE source text is the only source,
+        # so re-derive from it (same DOCTYPE_RE as the parse path).
         def doctype_external_id(native)
-          native.external_id
+          if native.is_a?(DoctypeWrapper)
+            native.external_id
+          else
+            native.to_s[DOCTYPE_RE, 2]
+          end
         end
 
         def doctype_system_id(native)
-          native.system_id
+          if native.is_a?(DoctypeWrapper)
+            native.system_id
+          else
+            native.to_s[DOCTYPE_RE, 3] || native.to_s[DOCTYPE_RE, 4]
+          end
         end
 
         def xpath(node, expression, namespaces = nil)

data/lib/moxml/adapter/nokogiri.rb

@@ -12,12 +12,50 @@ module Moxml
           @attachments ||= Moxml::NativeAttachment.new
         end
 
+        def bare_set_qname_safe?
+          true
+        end
+
+        # Qualified-name reads are clean on this engine (verified by
+        # the expanded-name specs); markers restore in-line when the
+        # parse recorded them.
+        def bare_get_qname_safe?
+          true
+        end
+
+        # Fast bare-name read for Element#[]: the native call plus,
+        # only when the parse recorded entity markers, their
+        # restoration (the resolver path's other real semantic).
+        # The marker flag is constant per document — a WeakMap on
+        # the adapter beats the per-read document fetch + attachment
+        # hash chain.
+        def doc_entity_markers?(doc)
+          cache = (@doc_markers ||= ObjectSpace::WeakMap.new)
+          cached = cache[doc]
+          return cached unless cached.nil?
+
+          cache[doc] = attachments.get(doc, :entity_markers) == true
+        end
+
+        def bare_attr_value(element, name)
+          value = element[name.to_s]
+          if value.is_a?(String) && doc_entity_markers?(element.document)
+            restore_entities(value)
+          else
+            value
+          end
+        end
+
+        def native_identity_stable?
+          true
+        end
+
         def set_root(doc, element)
           doc.root = element
         end
 
         def parse(xml, options = {}, _context = nil)
-          processed_xml = preprocess_entities(xml)
+          processed_xml, entity_markers = Entity.preprocess_with_marker_flag(xml)
 
           # preprocess_entities always returns UTF-8, so tell Nokogiri to
           # parse as UTF-8 regardless of any original encoding option.
@@ -42,9 +80,20 @@ module Moxml
 
           # Use provided context if available, otherwise create new one
           ctx = _context || Context.new(:nokogiri)
+          attachments.set(native_doc, :entity_markers, entity_markers)
           Document.new(native_doc, ctx)
         end
 
+        # Tolerant HTML parsing through libxml2's HTML mode: implied
+        # html/head/body structure, void elements, lowercased names,
+        # the HTML named-entity table. Recovery is inherent —
+        # malformed input never raises.
+        def parse_html(html, _options = {}, _context = nil)
+          html_string = html.is_a?(IO) || html.is_a?(StringIO) ? html.read : html.to_s
+          native_doc = ::Nokogiri::HTML(html_string)
+          Document.new(native_doc, _context || Context.new(:nokogiri))
+        end
+
         # Nokogiri parses with `config.recover` unless strict, so
         # recoverable syntax errors land on `doc.errors` instead of
         # raising (issue #147).
@@ -386,9 +435,11 @@ module Moxml
 
         def xpath(node, expression, namespaces = nil)
           result = node.xpath(expression, namespaces)
-          # Adapter contract: Array<native> | scalar (count(),
-          # string-length(), boolean functions return scalars).
-          result.is_a?(Enumerable) ? result.to_a : result
+          # Adapter contract: Array<native> | LazyNodeSet | scalar
+          # (count(), string-length(), boolean functions return
+          # scalars). The native node-set passes through lazily —
+          # to_a would materialize every result wrapper up front.
+          result.is_a?(Enumerable) ? result.extend(Moxml::LazyNodeSet) : result
         rescue ::Nokogiri::XML::XPath::SyntaxError => e
           raise Moxml::XPathError.new(
             e.message,

data/lib/moxml/adapter/ox.rb

@@ -15,6 +15,14 @@ module Moxml
           @attachments ||= Moxml::NativeAttachment.new
         end
 
+        def bare_set_qname_safe?
+          true
+        end
+
+        def native_identity_stable?
+          true
+        end
+
         def set_root(doc, element)
           existing_root = root(doc)
           element.parent = doc if element.is_a?(::Ox::Node)

data/lib/moxml/adapter/rexml.rb

@@ -14,6 +14,14 @@ module Moxml
           @attachments ||= Moxml::NativeAttachment.new
         end
 
+        def bare_set_qname_safe?
+          true
+        end
+
+        def native_identity_stable?
+          true
+        end
+
         def parse(xml, options = {}, _context = nil)
           xml = "" if xml.nil?
 

data/lib/moxml/attribute_resolver.rb

@@ -29,6 +29,27 @@ module Moxml
     module_function
 
     # @return [Moxml::Attribute, nil] the matching attribute wrapper
+    # Value-only prefixed resolution for Element#[]: prefix
+    # resolution is the resolver's real work; the match step goes to
+    # the engine's expanded-name lookup where the adapter offers it,
+    # skipping the attribute-list materialization and per-attr URI
+    # probes. Bare names take Element#'s adapter fast path instead.
+    def resolve_value(element, name)
+      prefix, local = name.split(":", 2)
+      return nil if prefix == "xmlns"
+
+      uri = prefix_uri(element, prefix)
+      return nil if uri.nil?
+
+      adapter = element.context.config.adapter
+      if adapter.is_a?(Moxml::Adapter::Leptris)
+        return adapter.expanded_attr_value(element.native, uri, local)
+      end
+
+      attr = resolve(element, name)
+      attr&.value
+    end
+
     def resolve(element, name)
       name = name.to_s
       if name.include?(":")
@@ -91,6 +112,20 @@ module Moxml
         return value
       end
 
+      # Fast path: every adapter's set_attribute writes by qualified
+      # name, and XML cannot namespace an unprefixed attribute — so
+      # a bare-name set replaces only the no-namespace attribute and
+      # can never touch a namespaced p:<local> sibling. The full
+      # expanded-name resolve (wrap every attribute, resolve each
+      # prefix against in-scope namespaces) is only needed for
+      # prefixed names; it dominated programmatic-builder attribute
+      # writes.
+      if !name.include?(":") && adapter.bare_set_qname_safe?
+        adapter.set_attribute(element.native, name, value)
+        element.invalidate_attribute_cache!
+        return value
+      end
+
       existing = resolve(element, name)
       if existing
         existing.value = value

data/lib/moxml/c14n.rb

@@ -39,6 +39,11 @@ module Moxml
     #   :exclusive10  Exclusive C14N 1.0 (W3C REC-xml-exc-c14n-20020718)
     def self.canonicalize(node_or_xml, with_comments: false,
                           algorithm: :inclusive10, inclusive_namespaces: [])
+      if (native = native_inclusive10(node_or_xml, with_comments,
+                                      inclusive_namespaces))
+        return native
+      end
+
       engine_for(algorithm).canonicalize(
         node_or_xml,
         with_comments: with_comments,
@@ -46,6 +51,31 @@ module Moxml
       )
     end
 
+    # The leptris engine canonicalizes in C — 23x the Ruby reference.
+    # Delegated only for the exact default shape (Inclusive 1.0, no
+    # comments, no InclusiveNamespace prefix list) on wrappers whose
+    # adapter passed the NATIVE_C14N_BYTE_SAFE load probe; every
+    # other combination keeps the Ruby engine (node-set subsets,
+    # xml:base fixup, exclusive, 1.1 stay on the ported
+    # implementation regardless).
+    def self.native_inclusive10(node_or_xml, with_comments, inclusive_namespaces)
+      return nil if with_comments || !inclusive_namespaces.empty?
+      return nil unless algorithm_shape_inclusive10?(node_or_xml)
+
+      adapter = node_or_xml.context.config.adapter
+      return nil unless adapter == Moxml::Adapter::Leptris &&
+        Moxml::Adapter::Leptris.native_c14n_byte_safe?
+
+      node_or_xml.native.canonicalize(
+        ::Leptris::XML::FFI::C14N_1_0, nil,
+        mode: ::Leptris::XML::FFI::C14N_MODE_CANONICAL
+      )
+    end
+
+    def self.algorithm_shape_inclusive10?(node_or_xml)
+      node_or_xml.is_a?(Moxml::Element) || node_or_xml.is_a?(Moxml::Document)
+    end
+
     def self.canonicalize_inclusive10(node_or_xml, with_comments: false)
       Inclusive10.new.canonicalize(node_or_xml, with_comments: with_comments)
     end

data/lib/moxml/context.rb

@@ -2,6 +2,10 @@
 
 module Moxml
   class Context
+    # Opal's default runtime excludes ObjectSpace entirely; the weak
+    # registry needs WeakMap, so the strong Hash (with its
+    # wholesale-clear valve) covers that platform.
+    WEAK_WRAPPERS = !defined?(ObjectSpace::WeakMap).nil?
     attr_reader :config
 
     def initialize(adapter = nil)
@@ -14,7 +18,12 @@ module Moxml
       # the same wrapper instead of allocating a fresh one per
       # access. Keyed by object identity; re-keyed by
       # Node#refresh_native! when an adapter swaps a native.
-      @wrappers = {}.compare_by_identity
+      # WeakMap where available: entries die with their native —
+      # parse-and-drop workloads release wrappers, natives, and (via
+      # the binding's finalizer) the C subtrees, instead of pinning
+      # up to the old 65,536 wholesale-clear valve which also
+      # destroyed identity for live wrappers when it fired.
+      @wrappers = WEAK_WRAPPERS ? ObjectSpace::WeakMap.new : {}.compare_by_identity
     end
 
     def wrapper_for(native)
@@ -22,18 +31,26 @@ module Moxml
     end
 
     def register_wrapper(native, wrapper)
-      # Safety valve + adapter opt-in. Adapters whose natives are
-      # recreated per access (libxml mints fresh Ruby objects for the
-      # same C node) opt out so the map does not accumulate dead
-      # entries; the default is opt-in.
+      # Adapter opt-in. Adapters whose natives are recreated per
+      # access (libxml mints fresh Ruby objects for the same C node)
+      # opt out so the map does not accumulate dead entries; the
+      # default is opt-in.
       return if @config&.adapter&.wrappers_recyclable? == false
 
-      @wrappers.clear if @wrappers.size >= 65_536
+      # The strong fallback (Opal) needs the wholesale-clear valve;
+      # the WeakMap registry is self-cleaning.
+      @wrappers.clear if @wrappers.is_a?(Hash) && @wrappers.size >= 65_536
       @wrappers[native] = wrapper
     end
 
+    # WeakMap has no delete — a nil value tombstones the entry (reads
+    # as a miss) and dies with the native like any other.
     def unregister_wrapper(native)
-      @wrappers.delete(native)
+      if WEAK_WRAPPERS
+        @wrappers[native] = nil
+      else
+        @wrappers.delete(native)
+      end
     end
 
     def namespace_scope_generation
@@ -74,6 +91,29 @@ module Moxml
       doc
     end
 
+    # Tolerant HTML4/5 parsing into the standard DOM: implied end
+    # tags, void elements, case-insensitive lowercased names, the
+    # HTML named-entity table, synthesized html/head/body. Supported
+    # by adapters with an engine HTML mode (leptris >= 1.9.80,
+    # nokogiri); others raise Moxml::AdapterError.
+    def parse_html(html, options = {})
+      config.adapter.parse_html(html, options, self)
+    end
+
+    # Streaming incremental parse (leptris): yields each completed
+    # element while parsing — :top_level yields the root's children,
+    # :full_document every element in completion (post-order) order.
+    # Memory stays bounded by the largest subtree, not the document
+    # (iterparse_file streams the file C-side). Yielded elements are
+    # parentless and valid only inside the block.
+    def iterparse(xml, mode: :top_level, &block)
+      config.adapter.iterparse(xml, mode, self, &block)
+    end
+
+    def iterparse_file(path, mode: :top_level, &block)
+      config.adapter.iterparse_file(path, mode, self, &block)
+    end
+
     # Parse then flatten in one call — see Moxml::Materializer
     # (issue #132). Yields records; returns an Enumerator when no
     # block is given.
@@ -128,6 +168,26 @@ module Moxml
       Builder.new(self).build(&block)
     end
 
+    # Frozen serialization defaults, memoized per context — Node#to_xml
+    # merged these from live config reads on every call (bulk element
+    # serialization pays a hash build + 4 chain derefs per element).
+    def default_serialize_options
+      @default_serialize_options ||= {
+        encoding: config.default_encoding,
+        indent: config.default_indent,
+        line_ending: config.default_line_ending,
+        expand_empty: true,
+      }.freeze
+    end
+
+    # The argless element.to_xml form resolves every option statically
+    # (no declaration for non-document nodes, context defaults for the
+    # rest) — this prebuilt frozen hash makes that path allocation-free.
+    def default_element_serialize_options
+      @default_element_serialize_options ||=
+        default_serialize_options.merge(no_declaration: true).freeze
+    end
+
     private
 
     def build_entity_registry

data/lib/moxml/document.rb

@@ -131,11 +131,11 @@ module Moxml
       # Handle different result types:
       # - Scalar values (from functions): return directly
       # - NodeSet: already wrapped, return directly
-      # - Array: wrap in NodeSet
+      # - Array / LazyNodeSet: wrap in NodeSet
       case result
       when NodeSet, Float, String, TrueClass, FalseClass, NilClass
         result
-      when Array
+      when Array, LazyNodeSet
         NodeSet.new(result, context)
       else
         # For other types, try to wrap in NodeSet

data/lib/moxml/element.rb

@@ -46,7 +46,9 @@ module Moxml
     # attributes only; prefixed names replace by namespace URI and
     # require a declared prefix. Cache coherence is the resolver's.
     def []=(name, value)
-      context.bump_namespace_scope_generation
+      # Every assign path (native set or value=) ends in
+      # invalidate_attribute_cache!, which bumps the generation —
+      # a leading bump here was one per write.
       Moxml::AttributeResolver.assign(self, name, normalize_xml_value(value))
     end
 
@@ -54,12 +56,25 @@ module Moxml
     # bare names match only no-namespace attributes; prefixed names
     # resolve through in-scope declarations to expanded names.
     def [](name)
-      cache = attribute_read_cache
       key = name.to_s
+      # Bare names on qualified-name engines: one adapter call with
+      # the adapter's own marker restoration (bare_attr_value). The
+      # resolver's expanded-name semantics only pay for prefixed
+      # names, where resolution is real work.
+      adapter = self.adapter
+      if !key.include?(":") && adapter.bare_get_qname_safe?
+        return adapter.bare_attr_value(@native, key)
+      end
+
+      cache = attribute_read_cache
       unless cache.key?(key)
-        cache[key] = Moxml::AttributeResolver.resolve(self, key)
+        cache[key] = if key.include?(":")
+                       Moxml::AttributeResolver.resolve_value(self, key)
+                     else
+                       Moxml::AttributeResolver.resolve(self, key)&.value
+                     end
       end
-      cache[key]&.value
+      cache[key]
     end
 
     def attribute(name)
@@ -92,11 +107,41 @@ module Moxml
     end
 
     def remove_attribute(name)
-      context.bump_namespace_scope_generation
+      # Both remove paths end in invalidate_attribute_cache!, which
+      # bumps the generation.
       Moxml::AttributeResolver.remove(self, name)
       self
     end
 
+    # Append a raw XML fragment's top-level nodes as children.
+    #
+    # Bulk construction rides the engine's parser instead of
+    # per-node create/attach calls — measured 2.0x faster than
+    # per-node building through the same adapter, and faster than
+    # per-node building on Nokogiri (the parse is C; the per-node
+    # path pays an FFI crossing per node).
+    #
+    # The fragment must be namespace-self-contained (declarations
+    # inside it ride along with the moved subtrees; prefixes relying
+    # on THIS element's scope must be spelled out in the fragment)
+    # and well-formed as the content of a single wrapper element —
+    # declarations and doctypes raise ParseError.
+    #
+    # @return [Moxml::Element] self
+    def append_xml(fragment)
+      if context.config.adapter_name == :ox
+        raise Moxml::AdapterError.new(
+          "append_xml is not supported by the Ox adapter (its customized node wrappers do not survive cross-document attachment)",
+          adapter: "Ox", operation: "append_xml",
+        )
+      end
+
+      wrapper = context.parse("<m>#{fragment}</m>")
+      children = wrapper.root.children.to_a
+      children.each { |child| add_child(child) }
+      self
+    end
+
     def add_namespace(prefix, uri)
       adapter.create_namespace(@native, prefix, uri,
                                namespace_validation_mode: context.config.namespace_validation_mode)