moxml 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e82117ebd56032bed4f9edffbb2714dec306b7bec52999193ef69fe62835ab9
-  data.tar.gz: 824fb9a07952249c2c97e650d5610d90c53ee23f279980aa5987e2a53922d74a
+  metadata.gz: 51298c0a0ce4ed7c7868e294dc8174ada558b4a1c36c168bc18cdcfe2f728aec
+  data.tar.gz: a5e5ffce0b817e397bf98852aecfd9bb341d5154a94540f486432ea32dee8788
 SHA512:
-  metadata.gz: 845a7de92860b25e68353e14efee1cc0015abfdc5a32f526b0baf1c45870e2966c1db6560eb45267a2fd0beab62936063493ac559fcca4317feffdcd0e54042a
-  data.tar.gz: 8242097334c0d1287bcc5c61658042e095ca1a34e375ff034c1504b9607f272937d62bd3ded2c439f45e7d6ae71ea58d86f5af37992858ab9a5fbadbe31fe738
+  metadata.gz: bf7d542cb81a21f1cfa517fafa2c07bdd996b9b7665ebf98e91c4e3f87ce79a1e1fa07f0d8f19837f6f45c73c36663ee54d602b70d72228a8de6e1ccb201a764
+  data.tar.gz: b971104eebb5bb3383bdacbc895d6cd54f0b4df400126f83f9e8002d80ec3e75c0afc1d3369d2c1277732b64326a2c0c044bb156078fdb6c3bb81a1c9c9fdeab

data/lib/compat/opal/moxml_boot.rb

@@ -25,6 +25,7 @@ require "moxml/doctype"
 require "moxml/entity_reference"
 require "moxml/entity_registry"
 require "moxml/entity"
+require "moxml/entity/restorer"
 require "moxml/entity/reference"
 require "moxml/xml_emitter"
 require "moxml/adapter"
@@ -44,7 +45,6 @@ require "moxml/adapter/customized_oga/raw_value_override"
 require "moxml/adapter/customized_oga/xml_declaration"
 require "moxml/adapter/customized_oga/xml_generator"
 require "moxml/adapter/oga"
-require "moxml/document_builder"
 require "moxml/builder"
 require "moxml/context"
 require "moxml/config"

data/lib/moxml/adapter/base.rb

@@ -183,13 +183,6 @@ namespace_validation_mode: :strict)
           node
         end
 
-        def prepare_for_new_document(node, _target_doc)
-          # Hook for adapters that need special handling when moving nodes
-          # between documents (e.g., LibXML's document.import)
-          # Default: no-op for backward compatibility
-          node
-        end
-
         # Check if the native document has an XML declaration
         # @param native_doc the native document object
         # @param wrapper [Moxml::Document] the wrapper with has_xml_declaration flag

data/lib/moxml/adapter/libxml.rb

@@ -8,7 +8,6 @@ module Moxml
   module Adapter
     class Libxml < Base
       autoload :EntityRefRegistry, "moxml/adapter/libxml/entity_ref_registry"
-      autoload :EntityRestorer, "moxml/adapter/libxml/entity_restorer"
 
       # Wrapper class to store DOCTYPE information
       class DoctypeWrapper
@@ -121,10 +120,7 @@ module Moxml
 
           ctx = _context || Context.new(:libxml)
           # Single parse path: wrap libxml's already-complete C-parsed tree
-          # directly (same pattern as nokogiri/ox). The previous
-          # DocumentBuilder.build path walked the entire parsed tree and
-          # re-added every node to a fresh moxml-managed document, which
-          # made parse O(N) Ruby work on top of an already-complete parse.
+          # directly (same pattern as the other adapters).
           # Doctype/declaration/PI attachments set above remain on
           # native_doc, so the serialize path still sees them.
           #
@@ -134,7 +130,7 @@ module Moxml
           # 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)
-          EntityRestorer.new(doc).run if ctx.config.restore_entities
+          Entity::Restorer.new(doc).run if ctx.config.restore_entities
           doc
         end
 
@@ -219,7 +215,7 @@ module Moxml
           return :unknown unless node
 
           # Fast path: native libxml nodes are the vast majority during
-          # parse traversal (DocumentBuilder visits raw libxml children).
+          # parse traversal (wrapping visits raw libxml children).
           # Skip the wrapper checks below for them.
           if node.is_a?(::LibXML::XML::Node)
             return NATIVE_NODE_TYPE_MAP[node.node_type] || :unknown
@@ -1035,7 +1031,7 @@ module Moxml
         end
 
         # Shallow duplication: copies the node itself (name, attrs, namespaces)
-        # but NOT its descendants. This is what DocumentBuilder needs — it
+        # but NOT its descendants (deep duplication composes this).
         # walks the source tree and re-adds children one at a time via
         # add_child, so a deep copy here would be done only to be stripped
         # by replace_children, then rebuilt — O(N²) waste on parse.
@@ -1061,7 +1057,8 @@ module Moxml
               node
             end
           when :element
-            shallow_duplicate_element(native_node)
+            # Public dup contract: a full deep copy of the subtree
+            deep_duplicate_node(native_node)
           when :text
             ::LibXML::XML::Node.new_text(native_node.content)
           when :cdata
@@ -1106,15 +1103,6 @@ module Moxml
           end
         end
 
-        def prepare_for_new_document(node, target_doc)
-          return node unless node && target_doc
-
-          # For LibXML, we need to duplicate ALL nodes to avoid
-          # document ownership issues. Simply importing doesn't work
-          # because nodes from the parsed document still have references.
-          duplicate_node(node)
-        end
-
         def has_declaration?(native_doc, wrapper)
           decl = attachments.get(native_doc, :declaration)
           if decl

data/lib/moxml/adapter/oga.rb

@@ -40,8 +40,23 @@ module Moxml
             )
           end
 
+          # Oga parses multiple root elements leniently; the moxml
+          # contract requires a single root. to_a because the vendored
+          # fork's NodeSet#count ignores its block.
+          roots = native_doc.children.to_a.count do |child|
+            child.instance_of?(::Oga::XML::Element)
+          end
+          if roots > 1
+            raise Moxml::ParseError.new(
+              "multiple root elements",
+              source: xml.is_a?(String) ? xml[0..100] : nil,
+            )
+          end
+
           ctx = _context || Context.new(:oga)
-          DocumentBuilder.new(ctx).build(native_doc)
+          doc = Document.new(native_doc, ctx)
+          Entity::Restorer.new(doc).run if ctx.config.restore_entities
+          doc
         end
 
         # SAX parsing implementation for Oga.
@@ -239,6 +254,38 @@ module Moxml
           node.parent if node.is_a?(::Oga::XML::Node)
         end
 
+        # Oga's Node#dup shallow-copies the ivars, leaving attributes
+        # and children shared with the original; the public dup
+        # contract needs a full deep copy.
+        def duplicate_node(node)
+          case node
+          when ::Oga::XML::Element
+            copy = ::Oga::XML::Element.new(name: node.name)
+            copy.namespace_name = node.namespace_name if node.namespace_name
+            node.attributes.each do |attr|
+              copy.add_attribute(::Oga::XML::Attribute.new(
+                                   name: attr.name,
+                                   namespace_name: attr.namespace_name,
+                                   value: attr.value,
+                                 ))
+            end
+            node.children.each do |child|
+              copy.children << duplicate_node(child)
+            end
+            copy
+          when ::Oga::XML::Text
+            ::Oga::XML::Text.new(text: node.text)
+          when ::Oga::XML::Cdata
+            ::Oga::XML::Cdata.new(text: node.text)
+          when ::Oga::XML::Comment
+            ::Oga::XML::Comment.new(text: node.text)
+          when ::Oga::XML::ProcessingInstruction
+            ::Oga::XML::ProcessingInstruction.new(name: node.name, text: node.text)
+          else
+            node.dup
+          end
+        end
+
         def next_sibling(node)
           node.next
         end

data/lib/moxml/adapter/rexml.rb

@@ -41,7 +41,9 @@ module Moxml
           end
 
           ctx = _context || Context.new(:rexml)
-          DocumentBuilder.new(ctx).build(native_doc)
+          doc = Document.new(native_doc, ctx)
+          Entity::Restorer.new(doc).run if ctx.config.restore_entities
+          doc
         end
 
         def extract_encoding_from_xml(xml)

data/lib/moxml/builder.rb

@@ -75,24 +75,6 @@ module Moxml
     end
 
     # Batch element creation
-    def elements(element_specs)
-      element_specs.each do |name, content_or_attrs|
-        if content_or_attrs.is_a?(Hash)
-          element(name, content_or_attrs)
-        else
-          element(name) { text(content_or_attrs) }
-        end
-      end
-    end
-
-    # Helper for creating namespaced elements
-    def ns_element(namespace_uri, name, attributes = {}, &block)
-      el = element(name, attributes, &block)
-      prefix = @namespaces.key(namespace_uri)
-      el.namespace = { prefix => namespace_uri } if prefix
-      el
-    end
-
     # Dynamic element creation DSL.
     # xml.schema(attrs) { } creates <schema> with those attributes.
     # Uses yield so blocks preserve the caller's self context.

data/lib/moxml/config.rb

@@ -78,7 +78,6 @@ module Moxml
     attr_reader :adapter_name, :default_line_ending
     attr_accessor :strict_parsing,
                   :default_encoding,
-                  :entity_encoding,
                   :default_indent,
                   :restore_entities,
                   :preload_entity_sets,
@@ -104,7 +103,6 @@ module Moxml
       @default_encoding = default_encoding || Config.default.default_encoding
       @default_indent = 2
       @default_line_ending = LINE_ENDING_LF
-      @entity_encoding = :basic
       @restore_entities = false
       @preload_entity_sets = []
       @entity_load_mode = :required

data/lib/moxml/context.rb

@@ -10,6 +10,27 @@ module Moxml
       # compare against it so every wrapper sees changes without
       # needing wrapper identity.
       @namespace_scope_generation = 0
+      # Native → wrapper identity map: repeated traversals hand back
+      # 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
+    end
+
+    def wrapper_for(native)
+      @wrappers[native]
+    end
+
+    def register_wrapper(native, wrapper)
+      # Safety valve: adapters whose natives are recreated per access
+      # (nokogiri mints new Ruby objects for the same C node) would
+      # grow the map without bound in pathological loops.
+      @wrappers.clear if @wrappers.size >= 65_536
+      @wrappers[native] = wrapper
+    end
+
+    def unregister_wrapper(native)
+      @wrappers.delete(native)
     end
 
     def namespace_scope_generation

data/lib/moxml/document.rb

@@ -21,7 +21,7 @@ module Moxml
 
     def root
       root_element = adapter.root(@native)
-      root_element ? Element.new(root_element, context) : nil
+      root_element ? Moxml::Node.wrap(root_element, context) : nil
     end
 
     def create_element(name)

data/lib/moxml/entity/restorer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Entity
+    # Restores configured character entities into explicit
+    # Moxml::Entity::Reference nodes after a native tree has been
+    # parsed and wrapped — for adapters whose parser resolves entities
+    # during parsing (libxml, and the restore_entities option on
+    # rexml/oga).
+    class Restorer
+      def initialize(doc)
+        @doc = doc
+        @ctx = doc.context
+        @registry = @ctx.entity_registry
+        @config = @ctx.config
+        @adapter = @ctx.config.adapter
+      end
+
+      def run
+        return unless @registry && @doc.root
+
+        walk(@doc.root)
+      end
+
+      private
+
+      def walk(element)
+        # Snapshot because we may add/remove siblings during the walk.
+        element.children.to_a.each do |child|
+          if child.is_a?(::Moxml::Text)
+            restore_text_node(child)
+          elsif child.is_a?(::Moxml::Element)
+            walk(child)
+          end
+        end
+      end
+
+      # Includes the adapter limitation that adjacent native text
+      # nodes get merged.
+      def restore_text_node(text_node)
+        content = text_node.content
+        return unless content
+
+        chunks = chunk_text(content)
+        return if chunks.size == 1 && chunks.first.first == :text
+
+        parent = text_node.parent
+        return unless parent
+
+        text_node.remove
+        chunks.each { |type, payload| append_chunk(parent, type, payload) }
+      end
+
+      def chunk_text(content)
+        chunks = []
+        buffer = +""
+        restorable = @registry.restorable_codepoints
+
+        content.each_char do |char|
+          cp = char.ord
+          if restorable.include?(cp) &&
+              (name = @registry.primary_name_for_codepoint(cp)) &&
+              @registry.should_restore?(cp, config: @config)
+            unless buffer.empty?
+              chunks << [:text, buffer.dup]
+              buffer.clear
+            end
+            chunks << [:eref, name]
+          else
+            buffer << char
+          end
+        end
+
+        chunks << [:text, buffer.dup] unless buffer.empty?
+        chunks
+      end
+
+      def append_chunk(parent, type, payload)
+        case type
+        when :text
+          parent.add_child(::Moxml::Text.new(
+                             @adapter.create_native_text(payload), @ctx
+                           ))
+        when :eref
+          parent.add_child(
+            ::Moxml::EntityReference.new(
+              @adapter.create_native_entity_reference(payload),
+              @ctx,
+            ),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/moxml/entity.rb

@@ -29,6 +29,7 @@ module Moxml
   # shared, single-sourced parts.
   module Entity
     autoload :Reference, "moxml/entity/reference"
+    autoload :Restorer, "moxml/entity/restorer"
 
     # Marker for adapters that resolve entities during parsing.
     # U+FFFC (Object Replacement Character) + U+FEFF (BOM) is a

data/lib/moxml/entity_registry.rb

@@ -199,7 +199,7 @@ module Moxml
     end
 
     # Returns the set of codepoints that could potentially be restored as entities.
-    # Used by DocumentBuilder for O(1) fast-path checks.
+    # Used by Entity::Restorer for O(1) fast-path checks.
     # @return [Set<Integer>]
     def restorable_codepoints
       @restorable_codepoints ||= if @by_name.empty?

data/lib/moxml/error.rb

@@ -106,27 +106,6 @@ module Moxml
     end
   end
 
-  # Error raised when serialization fails
-  class SerializationError < Error
-    attr_reader :node, :adapter, :format
-
-    def initialize(message, node: nil, adapter: nil, format: nil)
-      @node = node
-      @adapter = adapter
-      @format = format
-      super(message)
-    end
-
-    def to_s
-      msg = super
-      msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
-      msg += "\n  Adapter: #{@adapter}" if @adapter
-      msg += "\n  Format: #{@format}" if @format
-      msg += "\n  Hint: Check that the node structure is valid for serialization"
-      msg
-    end
-  end
-
   # Error raised when document structure is invalid
   class DocumentStructureError < Error
     attr_reader :attempted_operation, :current_state
@@ -146,27 +125,6 @@ module Moxml
     end
   end
 
-  # Error raised when attribute operations fail
-  class AttributeError < Error
-    attr_reader :attribute_name, :element, :value
-
-    def initialize(message, name: nil, element: nil, value: nil)
-      @attribute_name = name
-      @element = element
-      @value = value
-      super(message)
-    end
-
-    def to_s
-      msg = super
-      msg += "\n  Attribute: #{@attribute_name}" if @attribute_name
-      msg += "\n  Element: <#{@element.name}>" if @element.is_a?(Element)
-      msg += "\n  Value: #{@value.inspect}" if @value
-      msg += "\n  Hint: Verify attribute name follows XML naming rules"
-      msg
-    end
-  end
-
   # Error raised when a feature is not implemented by an adapter
   class NotImplementedError < Error
     attr_reader :feature, :adapter

data/lib/moxml/node.rb

@@ -21,7 +21,12 @@ module Moxml
     # Update native reference after identity-changing operations
     # (e.g., LibXML doc.root= creates a new Ruby wrapper)
     def refresh_native!(new_native)
-      @native = new_native
+      unless new_native.equal?(@native)
+        context.unregister_wrapper(@native)
+        @native = new_native
+        context.register_wrapper(new_native, self)
+      end
+      self
     end
 
     def document
@@ -225,6 +230,41 @@ module Moxml
       NodeSet.new(natives, context)
     end
 
+    # Returns the siblings after this node, in document order.
+    #
+    # @return [NodeSet]
+    def following_siblings
+      parent = self.parent
+      return NodeSet.new([], context) unless parent
+
+      siblings = parent.children.to_a
+      index = siblings.index { |child| child.native.equal?(@native) }
+      return NodeSet.new([], context) if index.nil?
+
+      NodeSet.new(siblings[(index + 1)..].map(&:native), context)
+    end
+
+    # Returns the siblings before this node, in document order.
+    #
+    # @return [NodeSet]
+    def preceding_siblings
+      parent = self.parent
+      return NodeSet.new([], context) unless parent
+
+      siblings = parent.children.to_a
+      index = siblings.index { |child| child.native.equal?(@native) }
+      return NodeSet.new([], context) if index.nil?
+
+      NodeSet.new(siblings[0...index].map(&:native), context)
+    end
+
+    # Deep copy of the node (both dup and clone create deep copies for XML nodes)
+    def dup
+      Moxml::Node.wrap(adapter.duplicate_node(@native), context)
+    end
+
+    alias clone dup
+
     # Returns an XPath expression that uniquely locates this node within
     # its document. Positional predicates are emitted only when sibling
     # elements share the same qualified name, keeping paths minimal.
@@ -276,13 +316,6 @@ module Moxml
       text.strip.empty?
     end
 
-    # Deep copy of the node (both dup and clone create deep copies for XML nodes)
-    def dup
-      Moxml::Node.wrap(adapter.dup(@native), context)
-    end
-
-    alias clone dup
-
     def ==(other)
       self.class == other.class && @native == other.native
     end
@@ -325,10 +358,13 @@ module Moxml
     def self.wrap(node, context)
       return nil if node.nil?
 
+      cached = context.wrapper_for(node)
+      return cached if cached
+
       type = adapter(context).node_type(node)
       klass = node_type_map[type] || self
 
-      klass.new(node, context)
+      klass.new(node, context).tap { |wrapper| context.register_wrapper(node, wrapper) }
     end
 
     # Internal: Set the parent node for cache invalidation tracking.

data/lib/moxml/node_set.rb

@@ -64,7 +64,7 @@ module Moxml
     end
 
     def +(other)
-      self.class.new(@nodes + other.nodes, @context)
+      self.class.new(@nodes + other.nodes, @context, @parent_node)
     end
 
     def <<(node)

data/lib/moxml/version.rb

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

data/lib/moxml/xpath/compiler.rb

@@ -294,6 +294,12 @@ module Moxml
 
         handler = axis_name.gsub("-", "_")
 
+        unless respond_to?(:"on_axis_#{handler}", true)
+          raise XPath::Error.new(
+            "XPath axis #{axis_name.inspect} is not supported by this engine",
+          )
+        end
+
         send(:"on_axis_#{handler}", test, input, &block)
       end
 
@@ -362,6 +368,78 @@ module Moxml
         end
       end
 
+      # AXIS: ancestor - all ancestors up to the document
+      def on_axis_ancestor(ast, input)
+        ancestor = unique_literal(:ancestor)
+
+        document_or_node(input).if_true do
+          input.ancestors.each.add_block(ancestor) do
+            condition = process(ast, ancestor)
+            if block_given?
+              condition.if_true { yield ancestor }
+            else
+              condition.if_true { ancestor }
+            end
+          end
+        end
+      end
+
+      # AXIS: ancestor-or-self - the context node and its ancestors
+      def on_axis_ancestor_or_self(ast, input)
+        ancestor = unique_literal(:ancestor)
+
+        document_or_node(input).if_true do
+          self_result = process(ast, input)
+          self_collection = if block_given?
+                              self_result.if_true { yield input }
+                            else
+                              self_result.if_true { input }
+                            end
+          self_collection.followed_by do
+            input.ancestors.each.add_block(ancestor) do
+              condition = process(ast, ancestor)
+              if block_given?
+                condition.if_true { yield ancestor }
+              else
+                condition.if_true { ancestor }
+              end
+            end
+          end
+        end
+      end
+
+      # AXIS: following-sibling - siblings after the context node
+      def on_axis_following_sibling(ast, input)
+        sibling = unique_literal(:sibling)
+
+        document_or_node(input).if_true do
+          input.following_siblings.each.add_block(sibling) do
+            condition = process(ast, sibling)
+            if block_given?
+              condition.if_true { yield sibling }
+            else
+              condition.if_true { sibling }
+            end
+          end
+        end
+      end
+
+      # AXIS: preceding-sibling - siblings before the context node
+      def on_axis_preceding_sibling(ast, input)
+        sibling = unique_literal(:sibling)
+
+        document_or_node(input).if_true do
+          input.preceding_siblings.each.add_block(sibling) do
+            condition = process(ast, sibling)
+            if block_given?
+              condition.if_true { yield sibling }
+            else
+              condition.if_true { sibling }
+            end
+          end
+        end
+      end
+
       # AXIS: descendant-or-self - Enables // operator
       def on_axis_descendant_or_self(ast, input)
         node = unique_literal(:descendant)
@@ -623,7 +701,11 @@ module Moxml
 
       # Parent node (..)
       def on_parent(_ast, input)
-        input.parent
+        if block_given?
+          yield input.parent
+        else
+          input.parent
+        end
       end
 
       # ===== OPERATORS =====

data/lib/moxml.rb

@@ -26,7 +26,6 @@ module Moxml
         default_indent: original.default_indent,
         default_line_ending: original.default_line_ending,
         entity_load_mode: original.entity_load_mode,
-        entity_encoding: original.entity_encoding,
         restore_entities: original.restore_entities,
         namespace_validation_mode: original.namespace_validation_mode,
         entity_restoration_mode: original.entity_restoration_mode,
@@ -48,7 +47,6 @@ module Moxml
         config.default_indent = saved_values[:default_indent]
         config.default_line_ending = saved_values[:default_line_ending]
         config.entity_load_mode = saved_values[:entity_load_mode]
-        config.entity_encoding = saved_values[:entity_encoding]
         config.restore_entities = saved_values[:restore_entities]
         config.namespace_validation_mode = saved_values[:namespace_validation_mode]
         config.entity_restoration_mode = saved_values[:entity_restoration_mode]
@@ -82,7 +80,6 @@ module Moxml
   autoload :Namespace, "moxml/namespace"
   autoload :Doctype, "moxml/doctype"
   autoload :EntityReference, "moxml/entity_reference"
-  autoload :DocumentBuilder, "moxml/document_builder"
   autoload :Builder, "moxml/builder"
   autoload :Entity, "moxml/entity"
   autoload :EntityRegistry, "moxml/entity_registry"

data/spec/integration/all_adapters_spec.rb

@@ -31,7 +31,7 @@ RSpec.describe "Cross-adapter integration" do
     "Moxml::EntityReference",
     "Moxml::Context",
     "Moxml::Builder",
-    "Moxml::DocumentBuilder",
+    "Moxml::Parse Behavior",
     "Moxml Integration",
     "Moxml Edge Cases",
     "Attribute Examples",

data/spec/integration/shared_examples/high_level/{document_builder_behavior.rb → parse_behavior.rb}

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-RSpec.shared_examples "Moxml::DocumentBuilder" do
+RSpec.shared_examples "Moxml::Parse Behavior" do
   let(:context) { Moxml.new }
-  let(:builder) { Moxml::DocumentBuilder.new(context) }
 
   describe "#build" do
     it "builds a document model from native document" do

data/spec/integration/shared_examples/node_wrappers/node_behavior.rb

@@ -106,5 +106,20 @@ RSpec.shared_examples "Moxml::Node" do
         expect(node.text).to eq("1")
       end
     end
+
+    describe "duplication" do
+      it "returns an independent deep copy" do
+        doc = context.parse("<root><a id='1'>text</a></root>")
+        original = doc.at_xpath("//a")
+        copy = original.dup
+
+        expect(copy).not_to equal(original)
+        expect(copy.name).to eq("a")
+        expect(copy["id"]).to eq("1")
+        expect(copy.text).to eq("text")
+        copy["id"] = "changed"
+        expect(original["id"]).to eq("1")
+      end
+    end
   end
 end

data/spec/moxml/adapter/libxml_internals_spec.rb

@@ -154,7 +154,7 @@ RSpec.describe Moxml::Adapter::Libxml do
     end
   end
 
-  describe Moxml::Adapter::Libxml::EntityRestorer do
+  describe Moxml::Entity::Restorer do
     let(:context) { Moxml.new(:libxml) }
 
     it "restores entities through its public entry point" do

data/spec/moxml/config_spec.rb

@@ -11,7 +11,6 @@ RSpec.describe Moxml::Config do
       expect(config.default_encoding).to eq("UTF-8")
       expect(config.default_indent).to eq(2)
       expect(config.default_line_ending).to eq("\n")
-      expect(config.entity_encoding).to eq(:basic)
     end
 
     it "sets default entity_load_mode to :required" do

data/spec/moxml/context_spec.rb

@@ -39,4 +39,26 @@ RSpec.describe Moxml::Context do
       expect(doc.root.name).to eq("root")
     end
   end
+
+  describe "wrapper identity map" do
+    it "hands back the same wrapper for the same native" do
+      doc = context.parse("<root><item id='1'/></root>")
+      first = doc.xpath("//item").first
+      second = doc.xpath("//item").first
+      expect(first).to equal(second)
+
+      again = doc.root.children.last
+      expect(again).to equal(first)
+    end
+
+    it "re-keys when refresh_native! swaps the native" do
+      doc = context.create_document
+      element = doc.create_element("x")
+      doc.add_child(element)
+
+      refreshed = doc.root
+      expect(refreshed.name).to eq("x")
+      expect(context.wrapper_for(refreshed.native)).to equal(refreshed)
+    end
+  end
 end

data/spec/moxml/error_spec.rb

@@ -150,31 +150,6 @@ RSpec.describe "Moxml errors" do
     end
   end
 
-  describe Moxml::SerializationError do
-    it "includes node, adapter, and format information" do
-      error = described_class.new(
-        "Failed to serialize",
-        adapter: "LibXML",
-        format: "xml",
-      )
-      expect(error.adapter).to eq("LibXML")
-      expect(error.format).to eq("xml")
-    end
-
-    it "provides helpful error message" do
-      error = described_class.new(
-        "Failed to serialize",
-        adapter: "Ox",
-        format: "xml",
-      )
-      message = error.to_s
-      expect(message).to include("Failed to serialize")
-      expect(message).to include("Adapter: Ox")
-      expect(message).to include("Format: xml")
-      expect(message).to include("Hint:")
-    end
-  end
-
   describe Moxml::DocumentStructureError do
     it "includes attempted operation and state" do
       error = described_class.new(
@@ -200,31 +175,6 @@ RSpec.describe "Moxml errors" do
     end
   end
 
-  describe Moxml::AttributeError do
-    it "includes attribute name, element, and value" do
-      error = described_class.new(
-        "Invalid attribute",
-        name: "id",
-        value: 123,
-      )
-      expect(error.attribute_name).to eq("id")
-      expect(error.value).to eq(123)
-    end
-
-    it "provides helpful error message" do
-      error = described_class.new(
-        "Invalid attribute name",
-        name: "123invalid",
-        value: "test",
-      )
-      message = error.to_s
-      expect(message).to include("Invalid attribute name")
-      expect(message).to include("Attribute: 123invalid")
-      expect(message).to include("Value: \"test\"")
-      expect(message).to include("Hint:")
-    end
-  end
-
   describe Moxml::NotImplementedError do
     it "includes feature and adapter information" do
       error = described_class.new(

data/spec/moxml/xpath/axes_spec.rb

@@ -205,6 +205,46 @@ RSpec.describe "XPath Axes" do
       end
     end
 
+    describe "ancestor and sibling axes" do
+      let(:family) do
+        context.parse("<root><parent id='p1'><b id='1'/><b id='2'/><c/><d/></parent></root>")
+      end
+
+      def select(expression, node = family)
+        ast = Moxml::XPath::Parser.parse(expression)
+        proc = Moxml::XPath::Compiler.compile_with_cache(ast)
+        proc.call(node).map(&:name)
+      end
+
+      it "selects ancestors with ancestor::" do
+        expect(select("//c/ancestor::*")).to eq(%w[parent root])
+      end
+
+      it "includes the context node with ancestor-or-self::" do
+        expect(select("//c/ancestor-or-self::*")).to eq(%w[c parent root])
+      end
+
+      it "selects following siblings" do
+        expect(select("//c/following-sibling::*")).to eq(%w[d])
+        expect(select("//b[@id='1']/following-sibling::b")).to eq(%w[b])
+        expect(select("//b[@id='1']/following-sibling::*").size).to eq(3)
+      end
+
+      it "selects preceding siblings" do
+        expect(select("//c/preceding-sibling::*")).to eq(%w[b b])
+      end
+
+      it "resolves the bare parent step and steps after it" do
+        expect(select("//c/..")).to eq(%w[parent])
+        expect(select("//c/../*").size).to eq(4)
+      end
+
+      it "raises a clear error for unimplemented axes" do
+        expect { select("//c/following::*") }
+          .to raise_error(Moxml::XPath::Error, /not supported/)
+      end
+    end
+
     describe "descendant-or-self shorthand from an element" do
       it "selects descendants with .//step" do
         ast = Moxml::XPath::Parser.parse(".//grandchild")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-25 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -151,7 +151,6 @@ files:
 - lib/moxml/adapter/leptris.rb
 - lib/moxml/adapter/libxml.rb
 - lib/moxml/adapter/libxml/entity_ref_registry.rb
-- lib/moxml/adapter/libxml/entity_restorer.rb
 - lib/moxml/adapter/nokogiri.rb
 - lib/moxml/adapter/oga.rb
 - lib/moxml/adapter/ox.rb
@@ -187,10 +186,10 @@ files:
 - lib/moxml/declaration.rb
 - lib/moxml/doctype.rb
 - lib/moxml/document.rb
-- lib/moxml/document_builder.rb
 - lib/moxml/element.rb
 - lib/moxml/entity.rb
 - lib/moxml/entity/reference.rb
+- lib/moxml/entity/restorer.rb
 - lib/moxml/entity_reference.rb
 - lib/moxml/entity_registry.rb
 - lib/moxml/entity_registry_opal_data.rb
@@ -390,7 +389,7 @@ files:
 - spec/integration/shared_examples/high_level/.gitkeep
 - spec/integration/shared_examples/high_level/builder_behavior.rb
 - spec/integration/shared_examples/high_level/context_behavior.rb
-- spec/integration/shared_examples/high_level/document_builder_behavior.rb
+- spec/integration/shared_examples/high_level/parse_behavior.rb
 - spec/integration/shared_examples/integration_workflows.rb
 - spec/integration/shared_examples/line_ending_behavior.rb
 - spec/integration/shared_examples/node_wrappers/.gitkeep
@@ -444,7 +443,6 @@ files:
 - spec/moxml/declaration_preservation_spec.rb
 - spec/moxml/declaration_spec.rb
 - spec/moxml/doctype_spec.rb
-- spec/moxml/document_builder_spec.rb
 - spec/moxml/document_spec.rb
 - spec/moxml/element_spec.rb
 - spec/moxml/entity_preservation_spec.rb

data/lib/moxml/adapter/libxml/entity_restorer.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-module Moxml
-  module Adapter
-    class Libxml < Base
-      # Restores configured character entities into explicit Moxml
-      # EntityReference nodes after LibXML has parsed the native tree.
-      class EntityRestorer
-        def initialize(doc, adapter: Libxml)
-          @doc = doc
-          @ctx = doc.context
-          @registry = @ctx.entity_registry
-          @config = @ctx.config
-          @adapter = adapter
-        end
-
-        def run
-          return unless @registry && @doc.root
-
-          walk(@doc.root)
-        end
-
-        private
-
-        def walk(element)
-          # Snapshot because we may add/remove siblings during the walk.
-          element.children.to_a.each do |child|
-            if child.is_a?(::Moxml::Text)
-              restore_text_node(child)
-            elsif child.is_a?(::Moxml::Element)
-              walk(child)
-            end
-          end
-        end
-
-        # Matches DocumentBuilder's previous behavior, including the libxml
-        # limitation that adjacent native text nodes get merged.
-        def restore_text_node(text_node)
-          content = text_node.content
-          return unless content
-
-          chunks = chunk_text(content)
-          return if chunks.size == 1 && chunks.first.first == :text
-
-          parent = text_node.parent
-          return unless parent
-
-          text_node.remove
-          chunks.each { |type, payload| append_chunk(parent, type, payload) }
-        end
-
-        def chunk_text(content)
-          chunks = []
-          buffer = +""
-          restorable = @registry.restorable_codepoints
-
-          content.each_char do |char|
-            cp = char.ord
-            if restorable.include?(cp) &&
-                (name = @registry.primary_name_for_codepoint(cp)) &&
-                @registry.should_restore?(cp, config: @config)
-              unless buffer.empty?
-                chunks << [:text, buffer.dup]
-                buffer.clear
-              end
-              chunks << [:eref, name]
-            else
-              buffer << char
-            end
-          end
-
-          chunks << [:text, buffer.dup] unless buffer.empty?
-          chunks
-        end
-
-        def append_chunk(parent, type, payload)
-          case type
-          when :text
-            parent.add_child(::Moxml::Text.new(
-                               @adapter.create_native_text(payload), @ctx
-                             ))
-          when :eref
-            parent.add_child(
-              ::Moxml::EntityReference.new(
-                @adapter.create_native_entity_reference(payload),
-                @ctx,
-              ),
-            )
-          end
-        end
-      end
-    end
-  end
-end

data/lib/moxml/document_builder.rb

@@ -1,167 +0,0 @@
-# frozen_string_literal: true
-
-module Moxml
-  class DocumentBuilder
-    attr_reader :context
-
-    def initialize(context)
-      @context = context
-      @node_stack = []
-    end
-
-    def build(native_doc)
-      @current_doc = context.create_document(native_doc)
-
-      # Transfer has_declaration flag if present in attachments
-      if adapter.attachments.key?(native_doc, :has_declaration)
-        has_declaration = adapter.attachments.get(native_doc, :has_declaration)
-        @current_doc.has_xml_declaration = has_declaration
-      end
-
-      # Transfer DOCTYPE from parsed document if it exists in attachments
-      if adapter.attachments.key?(native_doc, :doctype)
-        doctype = adapter.attachments.get(native_doc, :doctype)
-        if doctype
-          adapter.attachments.set(@current_doc.native, :doctype, doctype)
-        end
-      end
-
-      visit_node(native_doc)
-      @current_doc
-    end
-
-    private
-
-    def visit_node(node)
-      case node_type(node)
-      when :document then visit_document(node)
-      when :element then visit_element(node)
-      when :text then visit_text(node)
-      when :cdata then visit_cdata(node)
-      when :comment then visit_comment(node)
-      when :processing_instruction then visit_processing_instruction(node)
-      when :doctype then visit_doctype(node)
-      when :entity_reference then visit_entity_reference(node)
-      end
-    end
-
-    def visit_document(doc)
-      @node_stack.push(@current_doc)
-      visit_children(doc)
-      @node_stack.clear
-    end
-
-    def visit_element(node)
-      childless_node = adapter.duplicate_node(node)
-      adapter.replace_children(childless_node, [])
-      # Prepare node for new document (LibXML needs this)
-      childless_node = adapter.prepare_for_new_document(
-        childless_node,
-        @current_doc.native,
-      )
-      element = Element.new(childless_node, context)
-      @node_stack.last.add_child(element)
-
-      @node_stack.push(element) # add a parent for its children
-      visit_children(node)
-      @node_stack.pop # remove the parent
-    end
-
-    def visit_text(node)
-      # Prepare node for new document before wrapping
-      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
-      content = adapter.text_content(node)
-
-      # Check if we should restore entity references for this text
-      if context.config.restore_entities && text_has_restorable_entities?(content)
-        restore_entities_in_text(content)
-      else
-        @node_stack.last&.add_child(Text.new(prepared, context))
-      end
-    end
-
-    def text_has_restorable_entities?(content)
-      return false unless content
-
-      registry = context.entity_registry
-      codepoints = registry.restorable_codepoints
-      content.each_char do |char|
-        return true if codepoints.include?(char.ord)
-      end
-      false
-    end
-
-    def restore_entities_in_text(content)
-      parent = @node_stack.last
-      return unless parent
-
-      registry = context.entity_registry
-      config = context.config
-      buffer = +""
-
-      content.to_s.each_char do |char|
-        codepoint = char.ord
-        name = registry.primary_name_for_codepoint(codepoint)
-
-        if name && registry.should_restore?(codepoint, config: config)
-          # Flush buffered text before the entity
-          unless buffer.empty?
-            parent.add_child(Text.new(adapter.create_text(buffer), context))
-            buffer.clear
-          end
-          parent.add_child(
-            EntityReference.new(adapter.create_entity_reference(name), context),
-          )
-        else
-          buffer << char
-        end
-      end
-
-      # Flush remaining buffer
-      unless buffer.empty?
-        parent.add_child(Text.new(adapter.create_text(buffer), context))
-      end
-    end
-
-    def visit_cdata(node)
-      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
-      @node_stack.last&.add_child(Cdata.new(prepared, context))
-    end
-
-    def visit_comment(node)
-      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
-      @node_stack.last&.add_child(Comment.new(prepared, context))
-    end
-
-    def visit_processing_instruction(node)
-      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
-      @node_stack.last&.add_child(ProcessingInstruction.new(prepared, context))
-    end
-
-    def visit_doctype(node)
-      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
-      @node_stack.last&.add_child(Doctype.new(prepared, context))
-    end
-
-    def visit_entity_reference(node)
-      prepared = adapter.prepare_for_new_document(node, @current_doc.native)
-      @node_stack.last&.add_child(EntityReference.new(prepared, context))
-    end
-
-    def visit_children(node)
-      children(node).each { |child| visit_node(child) }
-    end
-
-    def node_type(node)
-      context.config.adapter.node_type(node)
-    end
-
-    def children(node)
-      context.config.adapter.children(node)
-    end
-
-    def adapter
-      context.config.adapter
-    end
-  end
-end

data/spec/moxml/document_builder_spec.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-require "spec_helper"
-
-# DocumentBuilder is an internal class for parsing
-# These tests verify it correctly builds Moxml document from native documents
-RSpec.describe Moxml::DocumentBuilder do
-  let(:context) { Moxml.new }
-
-  describe "#build" do
-    it "builds a Moxml document from native document" do
-      native_doc = context.parse("<root><child>content</child></root>").native
-      builder = described_class.new(context)
-      doc = builder.build(native_doc)
-
-      expect(doc).to be_a(Moxml::Document)
-      expect(doc.root.name).to eq("root")
-    end
-  end
-
-  describe "element handling" do
-    it "handles nested elements" do
-      native_doc = context.parse("<parent><child1/><child2/></parent>").native
-      builder = described_class.new(context)
-      doc = builder.build(native_doc)
-
-      expect(doc.root.children.length).to eq(2)
-    end
-  end
-end