moxml 0.5.47 → 0.5.49

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83f4ac58d2c22de225ec143ff3e78eb95e3460863b8fb1d67e8230a872bfad2a
-  data.tar.gz: c7401f4154a32e534a1c6a53f067a25406b16056de651eec8e768ac04c602dcc
+  metadata.gz: 1e7f648665fbf11423b43ed957f111cabe57a732b2037d6e7d6d718beae4e0c3
+  data.tar.gz: ec4ac686e3c83b794944c02a3f6b92aa964c9e984fb5752b49dbeb08812e0f61
 SHA512:
-  metadata.gz: d0ad7a04cbac82f8195be3be4318ee7d381974a812c7c2fce45110778875abfcb0be7ebb0c8e19339ddf2c2d8d9f4bd575254062b492a9cf4ad35072d8fe67fd
-  data.tar.gz: 301188cc44df6af9339502db3694651cc2a69238e3c222f6c0cda92393e72b80d5353cca335671be6b6560d5d64da4c32ad3bc4484f91d12239ddebf677e6aec
+  metadata.gz: ad7b15e82e237a726680c1eed20c0942abbcc74aca205a58681c745548e5a5c9c5048034079b88b1c8f91eddeb742d0eebbd5cc45daca057f852d25da48eb331
+  data.tar.gz: 834577776b64caa59e9b363a8a936db9684a20ed7793a6698adbfe0d6633a0770e17f5d24b063352c3931bea1289ac53ceb0bd8c9f7b71ad3fe2f2007ef59a5f

data/lib/moxml/adapter/base.rb

@@ -133,6 +133,22 @@ module Moxml
         # Protocol-level native equality; engines with more than one
         # wrapper class over one C node override (leptris native
         # read layer). Shared adapter examples compare through this.
+        # Extend-in-place capability (#230): an adapter whose native
+        # objects can carry the contract modules directly returns the
+        # extended native here (its @native is itself); the default
+        # mints a wrapper shell.
+        def wrap_native(_node, _type, _context)
+          nil
+        end
+
+        # Subtree walk capability: an adapter with a C-side pre-order
+        # traversal (leptris >= 1.9.174.6 visit) walks descendants in
+        # one dispatch; nil keeps the recursive children walk. Self
+        # is not yielded (each_node semantics).
+        def walk_descendants(_native, _context)
+          nil
+        end
+
         def same_node?(one, other)
           one == other
         end

data/lib/moxml/adapter/leptris.rb

@@ -85,6 +85,24 @@ module Moxml
         defined?(::Leptris::XML::NativeNode) &&
         Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.5")
 
+      # Identity mode (#230 stage 2): the contract modules extended
+      # onto natives shadow the C surface (Element#[] over
+      # NativeNode#[]), so the adapter's native fast paths speak to
+      # the native layer through these bound entries — bind_call is
+      # the same C dispatch without the shadow lookup.
+      if NATIVE_READ_LAYER
+        NN = ::Leptris::XML::NativeNode
+        NN_ATTRIBUTE = NN.instance_method(:attribute)
+        NN_NAME = NN.instance_method(:name)
+        NN_PARENT = NN.instance_method(:parent)
+        NN_NEXT_SIBLING = NN.instance_method(:next_sibling)
+        NN_CONTENT = NN.instance_method(:content)
+        NN_CHILDREN = NN.instance_method(:children)
+        NN_NODE_TYPE = NN.instance_method(:node_type)
+        NN_DOCUMENT = NN.instance_method(:document)
+        NN_ADD_CHILD = NN.instance_method(:add_child)
+      end
+
       # 1.9.163.2 moved the native bulk children into C
       # (Native.bulk_children) and fixed the 512 truncation
       # (leptris-ruby#202). The 162.6-163.1 window carries the
@@ -136,6 +154,48 @@ module Moxml
         @native_doc_roots = ObjectSpace::WeakMap.new
 
         class << self
+          # Extend-in-place mint (#230 stage 2): a TypedData native
+          # carries the contract modules on itself — the wrapper layer's
+          # 3-4 Ruby frames collapse to the module call over the C
+          # method. @native is self; every adapter method that accepts
+          # a native already handles NativeNode receivers.
+          # Extend-in-place mint (#230 stage 2): disabled by
+          # measurement. Extending TypedData natives with the
+          # contract modules works correctly (full battery + lm
+          # 5422/0 under identity mode) but each extend allocates a
+          # singleton plus per-module iclasses — the consumer
+          # pipeline regressed 4017us -> 16350us with 6x the
+          # allocations on a 900-node walk. The per-read frame
+          # savings (~50ns) cannot repay that mint cost. Revisit
+          # when the binding grows klass-injection
+          # (NativeNode.from(doc, ptr, klass:) minting the
+          # contract-carrying subclass in C) — asked upstream in the
+          # #230 thread. Wrappers mint through the Wrappers:: shells
+          # meanwhile.
+          def wrap_native(_node, _type, _context)
+            nil
+          end
+
+          NATIVE_C_WALK =
+            defined?(::Leptris::XML::NativeNode) &&
+            Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.174.6")
+
+          # One C visit walk (TODO.perf/27: post-order/abort state in
+          # the C callback, rb_yield direct — no FFI closure per
+          # node) instead of per-level children walks. Pre-order via
+          # entering; depth 0 is the receiver and stays unyielded.
+          def walk_descendants(native, context)
+            return nil unless NATIVE_C_WALK
+
+            root = to_binding(native)
+            return nil unless root.is_a?(::Leptris::XML::Element) ||
+              root.is_a?(::Leptris::XML::Document)
+
+            root.visit do |node, entering, depth|
+              yield Moxml::Node.wrap(node, context) if entering && depth.positive?
+            end
+          end
+
           def record_native_doc(root_native, doc)
             @native_doc_roots[root_native] = doc
           end
@@ -165,7 +225,7 @@ module Moxml
           def doc_for(node)
             # The 1.9.163.5 native layer exposes the owning document
             # directly; the root climb serves older bindings.
-            return node.document if NATIVE_MUTATIONS_COHERENT
+            return NN_DOCUMENT.bind_call(node) if NATIVE_MUTATIONS_COHERENT
 
             current = node
             current = current.parent while current&.parent
@@ -201,7 +261,7 @@ module Moxml
             ::Leptris::XML::FFI::C14N_1_0, nil,
             mode: ::Leptris::XML::FFI::C14N_MODE_CANONICAL
           )
-          wrapper = Moxml::Document.new(native_doc, Moxml::Context.new(:leptris))
+          wrapper = Moxml::Wrappers::Document.new(native_doc, Moxml::Context.new(:leptris))
           reference = Moxml::C14n::Inclusive10.new.canonicalize(wrapper.root)
           native == reference
         rescue StandardError
@@ -333,7 +393,14 @@ module Moxml
         # document-plus-attachment probe here cost more than the
         # read itself).
         def bare_attr_value(element, name)
-          value = element[name.to_s]
+          # Exact-name C read: bare names target no-namespace
+          # attributes (the documented contract — a bare "y" never
+          # resolves a "p:y" sibling).
+          value = if NATIVE_READ_LAYER && element.is_a?(NN)
+                    NN_ATTRIBUTE.bind_call(element, name.to_s)
+                  else
+                    element[name.to_s]
+                  end
           if !NATIVE_STRINGS_UTF8 && NATIVE_READ_LAYER &&
               element.is_a?(::Leptris::XML::NativeNode) &&
               value.is_a?(String)
@@ -376,7 +443,7 @@ module Moxml
             create_document
           end
           ctx = _context || Context.new(:leptris)
-          doc = Document.new(native_doc, ctx)
+          doc = Wrappers::Document.new(native_doc, ctx)
 
           if options[:noblanks] && !ENGINE_NOBLANKS_SAFE
             # The engine's DROP_WS_TEXT trims boundary whitespace of
@@ -451,7 +518,7 @@ module Moxml
           end
           attachments.set(native_doc, :entity_markers, false)
           bump_serialize_generation
-          Document.new(native_doc, _context || Context.new(:leptris))
+          Wrappers::Document.new(native_doc, _context || Context.new(:leptris))
         end
 
         # nil when no parse flag is requested — the binding treats a
@@ -711,13 +778,15 @@ module Moxml
         end
 
         def processing_instruction_target(node)
+          return to_binding(node).target if NATIVE_READ_LAYER && node.is_a?(NN)
+
           node.target
         end
 
         def node_type(node)
           if NATIVE_READ_LAYER &&
               node.is_a?(::Leptris::XML::NativeNode)
-            type = node.node_type
+            type = NN_NODE_TYPE.bind_call(node)
             # The native layer spells PIs :pi; the wrapper contract
             # (node_type_map) says :processing_instruction.
             return :processing_instruction if type == :pi
@@ -765,11 +834,12 @@ module Moxml
 
           if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
             # PIs expose no name through the native layer.
-            return to_binding(node).target.to_s if node.node_type == :pi
+            return to_binding(node).target.to_s if NN_NODE_TYPE.bind_call(node) == :pi
 
-            return node.name if NATIVE_STRINGS_UTF8
+            name = NN_NAME.bind_call(node)
+            return name if NATIVE_STRINGS_UTF8
 
-            node.name.dup.force_encoding(Encoding::UTF_8)
+            name.dup.force_encoding(Encoding::UTF_8)
           end
 
           node.name.to_s.dup.force_encoding("UTF-8")
@@ -808,7 +878,7 @@ module Moxml
             # the wrapper's memo supplies the flag, so deriving it
             # here costs no C parent climb per call.
             natives = if NATIVE_BULK_FIXED
-                        node.children.to_a
+                        NN_CHILDREN.bind_call(node).to_a
                       else
                         bulk_native_children(node)
                       end
@@ -864,7 +934,7 @@ module Moxml
 
         def parent(node)
           if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
-            parent = node.parent
+            parent = NN_PARENT.bind_call(node)
             return parent if parent
 
             doc = doc_for(node)
@@ -987,7 +1057,7 @@ module Moxml
         end
 
         def next_sibling(node)
-          return node.next_sibling if NATIVE_READ_LAYER &&
+          return NN_NEXT_SIBLING.bind_call(node) if NATIVE_READ_LAYER &&
             node.is_a?(::Leptris::XML::NativeNode)
 
           node.next_sibling if node.is_a?(::Leptris::XML::Node)
@@ -1114,6 +1184,12 @@ module Moxml
               bump_serialize_generation
               return child
             end
+            if NATIVE_MUTATIONS_COHERENT && parent.is_a?(NN) && child.is_a?(NN)
+              doc = NN_DOCUMENT.bind_call(parent)
+              child = doc.create_text_node(child) if child.is_a?(String)
+              return NN_ADD_CHILD.bind_call(parent, child)
+            end
+
             child = parent.document.create_text_node(child) if child.is_a?(String)
             parent.add_child(child)
           end
@@ -1200,9 +1276,10 @@ module Moxml
 
         def text_content(node)
           if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
-            return node.content if NATIVE_STRINGS_UTF8
+            content = NN_CONTENT.bind_call(node)
+            return content if NATIVE_STRINGS_UTF8
 
-            return node.content.dup.force_encoding(Encoding::UTF_8)
+            content.dup.force_encoding(Encoding::UTF_8)
           end
 
           # Frequency-ordered: elements dominate reads; they paid
@@ -1246,26 +1323,35 @@ module Moxml
         end
 
         def cdata_content(node)
+          return NN_CONTENT.bind_call(node) if NATIVE_READ_LAYER && node.is_a?(NN)
+
           node.content
         end
 
         def set_cdata_content(node, content)
+          node = to_binding(node) if NATIVE_READ_LAYER
           node.content = content.to_s
         end
 
         def comment_content(node)
+          return NN_CONTENT.bind_call(node) if NATIVE_READ_LAYER && node.is_a?(NN)
+
           node.content
         end
 
         def set_comment_content(node, content)
+          node = to_binding(node) if NATIVE_READ_LAYER
           node.content = content.to_s
         end
 
         def processing_instruction_content(node)
+          return NN_CONTENT.bind_call(node) if NATIVE_READ_LAYER && node.is_a?(NN)
+
           node.content
         end
 
         def set_processing_instruction_content(node, content)
+          node = to_binding(node) if NATIVE_READ_LAYER
           node.data = content.to_s
         end
 

data/lib/moxml/adapter/libxml.rb

@@ -152,7 +152,7 @@ module Moxml
           # any new parse-time logic only has to be added to this one
           # path; the restoration walk is just one of potentially several
           # post-processing steps and doesn't fork the construction.
-          doc = Document.new(native_doc, ctx)
+          doc = Wrappers::Document.new(native_doc, ctx)
           Entity::Restorer.new(doc).run if ctx.config.restore_entities
           doc
         end

data/lib/moxml/adapter/nokogiri.rb

@@ -80,7 +80,7 @@ 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)
+          Wrappers::Document.new(native_doc, ctx)
         end
 
         # Tolerant HTML parsing through libxml2's HTML mode: implied
@@ -90,7 +90,7 @@ module Moxml
         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))
+          Wrappers::Document.new(native_doc, _context || Context.new(:nokogiri))
         end
 
         # Nokogiri parses with `config.recover` unless strict, so

data/lib/moxml/adapter/oga.rb

@@ -54,7 +54,7 @@ module Moxml
           end
 
           ctx = _context || Context.new(:oga)
-          doc = Document.new(native_doc, ctx)
+          doc = Wrappers::Document.new(native_doc, ctx)
           Entity::Restorer.new(doc).run if ctx.config.restore_entities
           doc
         end

data/lib/moxml/adapter/ox.rb

@@ -68,7 +68,7 @@ module Moxml
           end
 
           ctx = _context || Context.new(context_adapter_name)
-          Document.new(native_doc, ctx)
+          Wrappers::Document.new(native_doc, ctx)
         end
 
         # SAX parsing implementation for Ox

data/lib/moxml/adapter/rexml.rb

@@ -49,7 +49,7 @@ module Moxml
           end
 
           ctx = _context || Context.new(:rexml)
-          doc = Document.new(native_doc, ctx)
+          doc = Wrappers::Document.new(native_doc, ctx)
           Entity::Restorer.new(doc).run if ctx.config.restore_entities
           doc
         end

data/lib/moxml/attribute.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Attribute < Node
+  module Attribute
+    include Node
+
     # Immutable between name= writes (which clear it via
     # clear_native_memo!), unlike element names that can change via
     # native adoption; the memo removes an adapter read per access.
@@ -64,7 +66,7 @@ module Moxml
 
     def namespace
       ns = adapter.namespace(@native)
-      ns && Namespace.new(ns, context)
+      ns && Wrappers::Namespace.new(ns, context)
     end
 
     def namespace=(ns)

data/lib/moxml/cdata.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Cdata < Node
+  module Cdata
+    include Node
+
     def content
       adapter.cdata_content(@native)
     end

data/lib/moxml/comment.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Comment < Node
+  module Comment
+    include Node
+
     def content
       adapter.comment_content(@native)
     end

data/lib/moxml/context.rb

@@ -77,7 +77,7 @@ module Moxml
     end
 
     def create_document(native_doc = nil)
-      Document.new(config.adapter.create_document(native_doc), self)
+      Wrappers::Document.new(config.adapter.create_document(native_doc), self)
     end
 
     def parse(xml, options = {})

data/lib/moxml/declaration.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Declaration < Node
+  module Declaration
+    include Node
+
     ALLOWED_VERSIONS = ["1.0", "1.1"].freeze
     ALLOWED_STANDALONE = %w[yes no].freeze
     ALLOWED_ATTRIBUTES = %w[version encoding standalone].freeze

data/lib/moxml/doctype.rb

@@ -13,7 +13,9 @@ module Moxml
   #   Most adapters do not currently implement these methods. If you need DOCTYPE
   #   information, consider using adapter-specific methods or parsing the serialized
   #   XML manually.
-  class Doctype < Node
+  module Doctype
+    include Node
+
     # Returns the DOCTYPE name (root element name)
     #
     # @return [String, nil] the DOCTYPE name

data/lib/moxml/document.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Document < Node
+  module Document
+    include Node
+
     attr_accessor :has_xml_declaration
 
     def initialize(native, context, adapter = nil, node_type = nil)
@@ -61,30 +63,30 @@ module Moxml
     end
 
     def create_element(name)
-      Element.new(adapter.create_element(name, owner_doc: @native), context)
+      Wrappers::Element.new(adapter.create_element(name, owner_doc: @native), context)
     end
 
     def create_text(content)
-      Text.new(adapter.create_text(content, owner_doc: @native), context)
+      Wrappers::Text.new(adapter.create_text(content, owner_doc: @native), context)
     end
 
     def create_cdata(content)
-      Cdata.new(adapter.create_cdata(content, owner_doc: @native), context)
+      Wrappers::Cdata.new(adapter.create_cdata(content, owner_doc: @native), context)
     end
 
     def create_comment(content)
-      Comment.new(adapter.create_comment(content, owner_doc: @native), context)
+      Wrappers::Comment.new(adapter.create_comment(content, owner_doc: @native), context)
     end
 
     def create_doctype(name, external_id, system_id)
-      Doctype.new(
+      Wrappers::Doctype.new(
         adapter.create_doctype(name, external_id, system_id),
         context,
       )
     end
 
     def create_processing_instruction(target, content)
-      ProcessingInstruction.new(
+      Wrappers::ProcessingInstruction.new(
         adapter.create_processing_instruction(target, content),
         context,
       )
@@ -93,11 +95,11 @@ module Moxml
     def create_declaration(version = "1.0", encoding = "UTF-8",
                            standalone = nil)
       decl = adapter.create_declaration(version, encoding, standalone)
-      Declaration.new(decl, context)
+      Wrappers::Declaration.new(decl, context)
     end
 
     def create_entity_reference(name)
-      EntityReference.new(adapter.create_entity_reference(name), context)
+      Wrappers::EntityReference.new(adapter.create_entity_reference(name), context)
     end
 
     def add_child(node)

data/lib/moxml/element.rb

@@ -120,7 +120,7 @@ module Moxml
       # mint, so the first name/value/attribute? access skips the
       # context hop and the adapter's type probe.
       @attributes ||= adapter.attributes(@native).map do |attr|
-        a = Attribute.new(attr, context, adapter, :attribute)
+        a = Wrappers::Attribute.new(attr, context, adapter, :attribute)
         a.parent_node = self
         a
       end
@@ -182,7 +182,7 @@ module Moxml
     # it's NOT the same as namespaces.first
     def namespace
       ns = adapter.namespace(@native)
-      ns && Namespace.new(ns, context)
+      ns && Wrappers::Namespace.new(ns, context)
     end
 
     # add the prefix to the element name
@@ -216,7 +216,7 @@ module Moxml
       return @namespace_definitions unless @namespace_definitions.nil?
 
       @namespace_definitions = adapter.namespace_definitions(@native).map do |ns|
-        Namespace.new(ns, context)
+        Wrappers::Namespace.new(ns, context)
       end
     end
 
@@ -225,7 +225,7 @@ module Moxml
     # scope. The shape materialize records carry (issue #138).
     def declared_namespaces
       adapter.namespace_definitions(@native).map do |ns|
-        wrapper = Namespace.new(ns, context)
+        wrapper = Wrappers::Namespace.new(ns, context)
         [wrapper.prefix, wrapper.uri]
       end
     end
@@ -236,7 +236,7 @@ module Moxml
       generation = context.namespace_scope_generation
       if @in_scope_namespaces.nil? || @in_scope_generation != generation
         @in_scope_namespaces = adapter.in_scope_namespaces(@native).map do |ns|
-          Namespace.new(ns, context)
+          Wrappers::Namespace.new(ns, context)
         end
         @in_scope_generation = generation
       end
@@ -363,7 +363,8 @@ module Moxml
     end
   end
 
-  class Element < Node
+  module Element
+    include Node
     include ElementBehavior
   end
 end

data/lib/moxml/entity/restorer.rb

@@ -78,12 +78,12 @@ module Moxml
       def append_chunk(parent, type, payload)
         case type
         when :text
-          parent.add_child(::Moxml::Text.new(
+          parent.add_child(::Moxml::Wrappers::Text.new(
                              @adapter.create_native_text(payload), @ctx
                            ))
         when :eref
           parent.add_child(
-            ::Moxml::EntityReference.new(
+            ::Moxml::Wrappers::EntityReference.new(
               @adapter.create_native_entity_reference(payload),
               @ctx,
             ),

data/lib/moxml/entity_reference.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class EntityReference < Node
+  module EntityReference
+    include Node
+
     def content
       ""
     end

data/lib/moxml/namespace.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Namespace < Node
+  module Namespace
+    include Node
+
     def prefix
       adapter.namespace_prefix(@native)
     end

data/lib/moxml/node.rb

@@ -20,15 +20,22 @@ module Moxml
     # otherwise pay the context hop and the type probe again on its
     # first access.
     def initialize(native, context, adapter = nil, node_type = nil)
+      prime_contract(native, context, adapter, node_type)
+    end
+
+    # Update native reference after identity-changing operations
+    # (e.g., LibXML doc.root= creates a new Ruby wrapper)
+    # Contract priming shared by the constructor and the extend-in-place
+    # mint (#230): an extended native IS its own @native.
+    def prime_contract(native, context, adapter = nil, node_type = nil)
       @context = context
       @native = native
       @parent_node = nil
       @adapter = adapter
       @node_type_cached = node_type
+      self
     end
 
-    # Update native reference after identity-changing operations
-    # (e.g., LibXML doc.root= creates a new Ruby wrapper)
     def refresh_native!(new_native)
       unless new_native.equal?(@native)
         context.unregister_wrapper(@native)
@@ -48,7 +55,7 @@ module Moxml
     end
 
     def document
-      Document.wrap(adapter.document(@native), context)
+      Moxml::Node.wrap(adapter.document(@native), context)
     end
 
     def parent
@@ -255,7 +262,7 @@ module Moxml
       return nil unless element?
 
       ns = adapter.namespace(@native)
-      ns && Namespace.new(ns, context)
+      ns && Wrappers::Namespace.new(ns, context)
     end
 
     # Returns all namespace definitions on this node
@@ -264,13 +271,26 @@ module Moxml
       return [] unless element?
 
       adapter.namespace_definitions(@native).map do |ns|
-        Namespace.new(ns, context)
+        Wrappers::Namespace.new(ns, context)
       end
     end
 
     # Recursively yield all descendant nodes
     # Used by XPath descendant-or-self and descendant axes
     def each_node(&block)
+      unless block
+        # Eager materialization: the leptris C-side walk rb_yields
+        # from the C callback and segfaults across fiber-suspended
+        # enumerator frames, so the no-block form never enters it.
+        nodes = []
+        each_node { |node| nodes << node }
+        return nodes.each
+      end
+
+      # Adapters with a C-side subtree walk take it in one
+      # dispatch; the recursive children walk stays the fallback.
+      return if adapter.walk_descendants(@native, context, &block)
+
       children.each do |child|
         yield child
         child.each_node(&block)
@@ -414,7 +434,7 @@ module Moxml
       # Native equality goes through the adapter: engines with a
       # native read layer hand out two wrapper classes over one C
       # node, and raw native == is false across that seam.
-      self.class == other.class &&
+      other.is_a?(Moxml::Node) &&
         adapter.same_node?(@native, other.native)
     end
 
@@ -486,7 +506,7 @@ module Moxml
 
     def prepare_node(node)
       case node
-      when String then Text.new(adapter.create_text(node), context)
+      when String then Moxml::Node.wrap(adapter.create_text(node), context)
       when Node then node
       else
         raise Moxml::DocumentStructureError.new(
@@ -512,11 +532,35 @@ module Moxml
     end
   end
 
-  class Node
+  module Node
     include NodeBehavior
 
+    # Instantiation shells per type — the contract constants
+    # (Element, Text, ...) are modules since issue #230, so wrappers
+    # mint through Wrappers::*.
     def self.node_type_map
       @node_type_map ||= {
+        element: Wrappers::Element,
+        text: Wrappers::Text,
+        cdata: Wrappers::Cdata,
+        comment: Wrappers::Comment,
+        processing_instruction: Wrappers::ProcessingInstruction,
+        document: Wrappers::Document,
+        declaration: Wrappers::Declaration,
+        doctype: Wrappers::Doctype,
+        attribute: Wrappers::Attribute,
+        entity_reference: Wrappers::EntityReference,
+      }.freeze
+    end
+
+    # The contract module for a type — what an in-place extended
+    # native carries instead of a wrapper shell.
+    def self.contract_module(type)
+      contract_modules[type]
+    end
+
+    def self.contract_modules
+      @contract_modules ||= {
         element: Element,
         text: Text,
         cdata: Cdata,
@@ -538,8 +582,17 @@ module Moxml
 
       adapter = adapter(context)
       type = adapter.node_type(node)
-      klass = node_type_map[type] || self
 
+      # Extend-in-place (issue #230): adapters whose natives can
+      # carry the contract modules directly (leptris TypedData) mint
+      # the native itself as the wrapper — @native is self.
+      if (extended = adapter.wrap_native(node, type, context))
+        extended.prime_contract(node, context, adapter, type)
+        context.register_wrapper(node, extended)
+        return extended
+      end
+
+      klass = node_type_map[type] || Wrappers::Node
       klass.new(node, context, adapter, type)
         .tap { |wrapper| context.register_wrapper(node, wrapper) }
     end

data/lib/moxml/processing_instruction.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class ProcessingInstruction < Node
+  module ProcessingInstruction
+    include Node
+
     def target
       adapter.processing_instruction_target(@native)
     end

data/lib/moxml/text.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Moxml
-  class Text < Node
+  module Text
+    include Node
+
     def content
       text = raw_content
       entity_bearing? ? adapter.restore_entities(text) : text

data/lib/moxml/version.rb

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

data/lib/moxml/wrappers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Instantiation shells (issue #230): the node-type constants are
+  # contract MODULES so leptris TypedData natives can carry them in
+  # place — wrappers are minted through these shells for native
+  # objects that cannot take the modules in place (binding-layer
+  # natives on every adapter, and all natives on non-leptris ones).
+  module Wrappers
+    Node = Class.new do
+      include Moxml::Node
+    end
+    Element = Class.new(Node) do
+      include Moxml::Element
+    end
+    Text = Class.new(Node) do
+      include Moxml::Text
+    end
+    Cdata = Class.new(Node) do
+      include Moxml::Cdata
+    end
+    Comment = Class.new(Node) do
+      include Moxml::Comment
+    end
+    ProcessingInstruction = Class.new(Node) do
+      include Moxml::ProcessingInstruction
+    end
+    Document = Class.new(Node) do
+      include Moxml::Document
+    end
+    Declaration = Class.new(Node) do
+      include Moxml::Declaration
+    end
+    Doctype = Class.new(Node) do
+      include Moxml::Doctype
+    end
+    Attribute = Class.new(Node) do
+      include Moxml::Attribute
+    end
+    EntityReference = Class.new(Node) do
+      include Moxml::EntityReference
+    end
+    Namespace = Class.new(Node) do
+      include Moxml::Namespace
+    end
+  end
+end

data/lib/moxml.rb

@@ -67,6 +67,7 @@ module Moxml
   autoload :Config, "moxml/config"
   autoload :Context, "moxml/context"
   autoload :Node, "moxml/node"
+  autoload :Wrappers, "moxml/wrappers"
   autoload :NodeSet, "moxml/node_set"
   autoload :LazyNodeSet, "moxml/lazy_node_set"
   autoload :Document, "moxml/document"

data/spec/integration/contract_parity_spec.rb

@@ -22,9 +22,8 @@
     describe "fragment parsing (issue #188)" do
       it "returns the fragment's top-level nodes uniformly" do
         nodes = ctx.parse_fragment(%(<a x="1">t1</a><b/>tail))
-        expect(nodes.map(&:class)).to eq(
-          [Moxml::Element, Moxml::Element, Moxml::Text],
-        )
+        expect(nodes.map(&:element?)).to eq([true, true, false])
+        expect(nodes.map(&:text?)).to eq([false, false, true])
         expect(nodes[0]["x"]).to eq("1")
         expect(nodes[0].text).to eq("t1")
         expect(nodes[2].content).to eq("tail")

data/spec/integration/shared_examples/entity_reference_whitespace.rb

@@ -76,12 +76,12 @@ RSpec.shared_examples "Entity Reference Whitespace Preservation" do
       end
 
       children = doc.root.children
-      types = children.map(&:class)
+      types = children.map(&:entity_reference?)
 
       expect(types).to eq([
-                            Moxml::EntityReference,
-                            Moxml::Text,
-                            Moxml::EntityReference,
+                            true,
+                            false,
+                            true,
                           ])
       expect(children[1].content).to eq(" ")
     end

data/spec/moxml/adapter/leptris_spec.rb

@@ -93,10 +93,14 @@ RSpec.describe Moxml::Adapter::Leptris do
       doc = ctx.parse('<?xml version="1.0"?><?pi-prolog before?><root/><?pi-epilog after?><!-- tail -->')
       kids = doc.children.to_a
 
-      expect(kids.map(&:class)).to eq(
-        [Moxml::ProcessingInstruction, Moxml::Element,
-         Moxml::ProcessingInstruction, Moxml::Comment],
-      )
+      shape = kids.map do |k|
+        if k.processing_instruction?
+          :pi
+        else
+          k.element? ? :element : :comment
+        end
+      end
+      expect(shape).to eq(%i[pi element pi comment])
       expect(kids.select(&:processing_instruction?).map(&:target)).to eq(%w[pi-prolog pi-epilog])
       expect(kids[0].content).to eq("before")
       expect(doc.to_xml.index("pi-epilog")).to be > doc.to_xml.index("</root>")
@@ -606,14 +610,15 @@ RSpec.describe Moxml::Adapter::Leptris do
     it "skips the marker split for entity-free documents" do
       doc = ctx.parse("<root>\n  <a>text</a>\n  <b/>\n</root>")
       kids = doc.root.children.to_a
-      expect(kids.map(&:class)).to eq([Moxml::Text, Moxml::Element, Moxml::Text, Moxml::Element, Moxml::Text])
+      shape = kids.map { |k| k.text? ? :text : :element }
+      expect(shape).to eq(%i[text element text element text])
       expect(described_class.entity_bearing?(doc.root.native)).to be(false)
     end
 
     it "splits markers when the source carries entities" do
       doc = ctx.parse("<root><a>pre&nbsp;post</a></root>")
       kids = doc.at_xpath("//a").children.to_a
-      expect(kids.map(&:class)).to include(Moxml::EntityReference)
+      expect(kids.map { |k| k.is_a?(Moxml::EntityReference) }).to include(true)
       expect(described_class.entity_bearing?(doc.root.native)).to be(true)
     end
 
@@ -631,7 +636,7 @@ RSpec.describe Moxml::Adapter::Leptris do
       er = doc.create_entity_reference("nbsp")
       doc.at_xpath("//a").add_child(er)
       expect(described_class.entity_bearing?(doc.root.native)).to be(true)
-      expect(doc.at_xpath("//a").children.to_a.map(&:class)).to include(Moxml::EntityReference)
+      expect(doc.at_xpath("//a").children.to_a.map { |k| k.is_a?(Moxml::EntityReference) }).to include(true)
     end
   end
 
@@ -702,11 +707,11 @@ RSpec.describe Moxml::Adapter::Leptris do
         expect(decl.digest).to be_nil
       end
       # comments and PIs hash in C
-      kinds = doc.root.children.map { |n| [n.class, n.digest] }
-      comment = kinds.find { |n, _| n == Moxml::Comment }
-      pi = kinds.find { |n, _| n == Moxml::ProcessingInstruction }
-      expect(comment[1]).to be_a(Integer)
-      expect(pi[1]).to be_a(Integer)
+      kinds = doc.root.children.map { |n| [n.is_a?(Moxml::Comment), n.is_a?(Moxml::ProcessingInstruction), n.digest] }
+      comment = kinds.find { |c, _, _| c }
+      pi = kinds.find { |_, p, _| p }
+      expect(comment[2]).to be_a(Integer)
+      expect(pi[2]).to be_a(Integer)
     end
   end
 end

data/spec/moxml/adapter/libxml_internals_spec.rb

@@ -113,7 +113,7 @@ RSpec.describe Moxml::Adapter::Libxml do
       doc = context.parse("<root><a/><b/></root>")
       a = doc.root.children.first
       b = doc.root.children.last
-      eref = Moxml::EntityReference.new(
+      eref = Moxml::Wrappers::EntityReference.new(
         adapter.create_native_entity_reference("amp"), context
       )
       a.add_child(eref)
@@ -125,7 +125,7 @@ RSpec.describe Moxml::Adapter::Libxml do
     it "returns [refs, sequence] when both are registered for the element" do
       doc = context.parse("<root><a>text</a></root>")
       a = doc.root.children.first
-      eref = Moxml::EntityReference.new(
+      eref = Moxml::Wrappers::EntityReference.new(
         adapter.create_native_entity_reference("amp"), context
       )
       a.add_child(eref)
@@ -144,7 +144,7 @@ RSpec.describe Moxml::Adapter::Libxml do
     it "preserves normal child indentation when entity refs are present" do
       doc = context.parse("<root><a><b/></a></root>")
       a = doc.root.children.first
-      eref = Moxml::EntityReference.new(
+      eref = Moxml::Wrappers::EntityReference.new(
         adapter.create_native_entity_reference("amp"), context
       )
       a.add_child(eref)

data/spec/moxml/node_set_spec.rb

@@ -45,7 +45,7 @@ RSpec.describe Moxml::NodeSet do
     end
 
     it "wraps through the Enumerable surface" do
-      expect(doc.root.children.map(&:class).uniq).to eq([Moxml::Element])
+      expect(doc.root.children.map { |c| c.is_a?(Moxml::Element) }.uniq).to eq([true])
     end
   end
 end

data/spec/moxml/node_spec.rb

@@ -84,7 +84,7 @@ RSpec.describe Moxml::Node do
 
   describe "#content" do
     it "returns empty string on base Node" do
-      expect(described_class.new(nil, context).content).to eq("")
+      expect(Moxml::Wrappers::Node.new(nil, context).content).to eq("")
     end
 
     it "returns text on Element" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.47
+  version: 0.5.49
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -271,6 +271,7 @@ files:
 - lib/moxml/signature/verifier.rb
 - lib/moxml/text.rb
 - lib/moxml/version.rb
+- lib/moxml/wrappers.rb
 - lib/moxml/xml_emitter.rb
 - lib/moxml/xml_utils.rb
 - lib/moxml/xml_utils/encoder.rb