canon 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53a9382cf5977e8e1b65a847cd11f9f2c61a162c3913a64588e4d48c71cfbf94
-  data.tar.gz: 851f0227e56cffdd225fce23ec32b78b3b44f43e08137a39572a2db237d94aaf
+  metadata.gz: 04012234db38cae77206ba33f856aca1262a0ad0111e7d233d5b814e90c22187
+  data.tar.gz: 3700758afcb5619f59ba7e2f896963bc63695d534f60af7d922dfce8c26076ec
 SHA512:
-  metadata.gz: 67710ade1d18f99c23e4477540303f45867d145c7f92df59f2f1277cf442c576eca2a3d8562cb92972f56d80dbe111e6104d28353cb7c5091d690490605772ff
-  data.tar.gz: e8d2783baa8fba878cb3cbb7a602dff3563f23dfb15df95ca5c24c075475d53c8319f2579bf3ce3c533e1989b1c75b91b72913c57c30279278a59de68202aef0
+  metadata.gz: c6452b462325e65c3f38f31438656b1cf60790646413314d8e835f6a27f78026bc10de2474065627b26a602962c424fd6858e1bc97ed3bca43e8a009b1779291
+  data.tar.gz: 749b78e282b4b2c7d440f9dff4a2361ee8d7742afcdab54b490bf836ae9417afc5f677e2039143020a6e50eceaf12d42950372c7a5f62dfcd335223243962fef

data/lib/canon/html/data_model.rb

@@ -76,171 +76,74 @@ module Canon
         Canon::Xml::DataModel.serialize(node)
       end
 
-      # Build XPath data model from Nokogiri document or fragment
+      # Build XPath data model from a Nokogiri HTML document or
+      # fragment — a TreeBuilder walk like the XML extractors, with the
+      # HTML whitespace policy and xmlns-free attributes.
       def self.build_from_nokogiri(nokogiri_doc)
+        builder = Canon::Xml::TreeBuilder::DEFAULT
         root = Canon::Xml::Nodes::RootNode.new
+        skip_types = defined?(Nokogiri) ? [Nokogiri::XML::DTD] : []
 
         if nokogiri_doc.is_a?(Nokogiri::XML::Document) && nokogiri_doc.root
-          # For Documents (HTML4, HTML5): process the root element
-          root.add_child(build_element_node(nokogiri_doc.root))
-
-          # Process PIs and comments outside doc element
-          nokogiri_doc.children.each do |child|
-            next if child == nokogiri_doc.root
-            next if child.is_a?(Nokogiri::XML::DTD)
-
-            node = build_node_from_nokogiri(child)
-            root.add_child(node) if node
+          root.add_child(walk(builder, nokogiri_doc.root))
+          builder.add_document_children(root, nokogiri_doc.children,
+                                        nokogiri_doc.root, skip_types) do |child|
+            walk(builder, child)
           end
         else
-          # For DocumentFragments: process all children directly
-          # Fragments don't have a single .root, they contain multiple top-level nodes
-          nokogiri_doc.children.each do |child|
-            next if child.is_a?(Nokogiri::XML::DTD)
-
-            node = build_node_from_nokogiri(child)
-            root.add_child(node) if node
+          builder.add_document_children(root, nokogiri_doc.children,
+                                        nil, skip_types) do |child|
+            walk(builder, child)
           end
         end
 
         root
       end
 
-      # Build node from Nokogiri node
-      def self.build_node_from_nokogiri(nokogiri_node)
-        case nokogiri_node
+      def self.walk(builder, node, inherited_namespaces: nil)
+        case node
         when Nokogiri::XML::Element
-          build_element_node(nokogiri_node)
-        when Nokogiri::XML::Text
-          build_text_node(nokogiri_node)
-        when Nokogiri::XML::Comment
-          build_comment_node(nokogiri_node)
-        when Nokogiri::XML::ProcessingInstruction
-          build_pi_node(nokogiri_node)
-        end
-      end
-
-      # Build element node from Nokogiri element
-      def self.build_element_node(nokogiri_element)
-        element = Canon::Xml::Nodes::ElementNode.new(
-          name: nokogiri_element.name,
-          namespace_uri: nokogiri_element.namespace&.href,
-          prefix: nokogiri_element.namespace&.prefix,
-        )
-
-        # Build namespace nodes (includes inherited namespaces)
-        build_namespace_nodes(nokogiri_element, element)
-
-        # Build attribute nodes
-        build_attribute_nodes(nokogiri_element, element)
-
-        # Build child nodes
-        nokogiri_element.children.each do |child|
-          node = build_node_from_nokogiri(child)
-          element.add_child(node) if node
-        end
-
-        element
-      end
-
-      # Build namespace nodes for an element
-      def self.build_namespace_nodes(nokogiri_element, element)
-        # Collect all in-scope namespaces
-        namespaces = collect_in_scope_namespaces(nokogiri_element)
-
-        namespaces.each do |prefix, uri|
-          ns_node = Canon::Xml::Nodes::NamespaceNode.new(
-            prefix: prefix,
-            uri: uri,
+          scope = builder.merge_namespace_scope(
+            inherited_namespaces,
+            node.namespace_definitions.map { |ns| [ns.prefix, ns.href] },
           )
-          element.add_namespace(ns_node)
-        end
-      end
-
-      # Collect all in-scope namespaces for an element
-      def self.collect_in_scope_namespaces(nokogiri_element)
-        namespaces = {}
-
-        # Walk up the tree to collect all namespace declarations
-        current = nokogiri_element
-        while current && !current.is_a?(Nokogiri::XML::Document)
-          if current.is_a?(Nokogiri::XML::Element)
-            current.namespace_definitions.each do |ns|
-              prefix = ns.prefix || ""
-              # Only add if not already defined (child overrides parent)
-              unless namespaces.key?(prefix)
-                namespaces[prefix] = ns.href
-              end
-            end
-          end
-          current = current.parent
-        end
-
-        # Always include xml namespace
-        namespaces["xml"] ||= "http://www.w3.org/XML/1998/namespace"
-
-        namespaces
-      end
-
-      # Build attribute nodes for an element
-      def self.build_attribute_nodes(nokogiri_element, element)
-        nokogiri_element.attributes.each do |name, attr|
-          next if name.start_with?("xmlns")
-
-          attr_node = Canon::Xml::Nodes::AttributeNode.new(
-            name: attr.name,
-            value: attr.value,
-            namespace_uri: attr.namespace&.href,
-            prefix: attr.namespace&.prefix,
+          element = builder.element(
+            name: node.name,
+            prefix: node.namespace&.prefix,
+            namespace_uri: node.namespace&.href,
+            # HTML attributes are namespace-free; xmlns declarations are
+            # not reported as attributes.
+            attributes: node.attribute_nodes.filter_map do |attr|
+              next if attr.name.start_with?("xmlns")
+
+              [attr.name, attr.value, nil, nil]
+            end,
+            namespace_scope: scope,
           )
-          element.add_attribute(attr_node)
-        end
-      end
-
-      # Build text node from Nokogiri text node
-      # HTML-specific: handles whitespace-sensitive elements (pre, code, textarea, script, style)
-      # and preserves whitespace between inline element siblings.
-      def self.build_text_node(nokogiri_text)
-        # Skip text nodes that are only whitespace between elements
-        # EXCEPT in whitespace-sensitive elements (pre, code, textarea, script, style)
-        # and when whitespace is between inline element siblings (semantically significant)
-        content = nokogiri_text.content
-
-        # NBSP (U+00A0) is never insignificant whitespace
-        if content.strip.empty? && nokogiri_text.parent.is_a?(Nokogiri::XML::Element) && !content.include?("\u00A0")
-          # Check if parent is whitespace-sensitive
-          parent_name = nokogiri_text.parent.name.downcase
-          whitespace_sensitive_tags = %w[pre code textarea script style]
-
-          # Check if whitespace is between inline siblings
-          unless whitespace_sensitive_tags.include?(parent_name) ||
-              Canon::Comparison::WhitespaceSensitivity.inline_whitespace_significant?(nokogiri_text)
-            return nil
+          node.children.each do |child|
+            built = walk(builder, child, inherited_namespaces: scope)
+            element.add_child(built) if built
           end
+          element
+        when Nokogiri::XML::Text
+          builder.text(
+            node.content,
+            keep: Canon::Xml::WhitespacePolicy.keep_html_text?(
+              node.content,
+              parent_name: node.parent.is_a?(Nokogiri::XML::Element) ? node.parent.name : nil,
+              inline_significant:
+                Canon::Comparison::WhitespaceSensitivity.inline_whitespace_significant?(node),
+            ),
+          )
+        when Nokogiri::XML::Comment
+          builder.comment(node.content)
+        when Nokogiri::XML::ProcessingInstruction
+          builder.processing_instruction(node.name, node.content)
         end
-
-        # Nokogiri already handles CDATA conversion and entity resolution
-        Canon::Xml::Nodes::TextNode.new(value: content)
-      end
-
-      # Build comment node from Nokogiri comment
-      def self.build_comment_node(nokogiri_comment)
-        Canon::Xml::Nodes::CommentNode.new(value: nokogiri_comment.content)
-      end
-
-      # Build PI node from Nokogiri PI
-      def self.build_pi_node(nokogiri_pi)
-        Canon::Xml::Nodes::ProcessingInstructionNode.new(
-          target: nokogiri_pi.name,
-          data: nokogiri_pi.content,
-        )
       end
 
       class << self
-        private :build_from_nokogiri, :build_node_from_nokogiri,
-                :build_element_node, :build_namespace_nodes,
-                :collect_in_scope_namespaces, :build_attribute_nodes,
-                :build_text_node, :build_comment_node, :build_pi_node
+        private :build_from_nokogiri, :walk
       end
     end
   end

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.3.4"
+  VERSION = "0.3.6"
 end

data/lib/canon/xml/data_model.rb

@@ -126,149 +126,83 @@ module Canon
         end
       end
 
-      # --- Shared construction kernels (identical semantics per engine) ---
-
-      # Attach document-level children (prolog/epilog PIs, comments,
-      # document-level text) to the canon root, in document order,
-      # skipping the document element and the doctype. `converter`
-      # converts one engine child to a canon node (or nil).
-      def self.add_document_children(root, children, document_element,
-                                      skip_types, converter)
-        children.each do |child|
-          next if child.equal?(document_element)
-          next if skip_types.any? { |type| child.is_a?(type) }
-
-          node = converter.call(child)
-          root.add_child(node) if node
-        end
-      end
+      # --- Engine extractors ---
+      #
+      # Traversal and engine mapping only. Each walk maps its engine's
+      # shapes onto TreeBuilder's interface; all construction semantics
+      # (namespace scopes, attribute normalization, whitespace policy,
+      # node kinds, document ordering) live in TreeBuilder and
+      # WhitespacePolicy — one dialect, three feeds.
 
-      # In-scope namespace bindings: the element's own declarations
-      # shadow inherited ones; xml is prebound at the base. Declaration
-      # pairs are [prefix-or-nil, uri]; nil and "" both mean the default
-      # namespace.
-      def self.merge_namespace_scope(inherited, declaration_pairs)
-        scope = inherited ? inherited.dup : { "xml" => "http://www.w3.org/XML/1998/namespace" }
-        declaration_pairs.each do |prefix, uri|
-          scope[prefix || ""] = uri
-        end
-        scope
-      end
+      # -- Nokogiri walk: top-down, scope flows down the recursion --
 
       def self.build_from_nokogiri(nokogiri_doc, preserve_whitespace: false)
         root = Nodes::RootNode.new
-
-        converter = ->(child) { build_node_from_nokogiri(child, preserve_whitespace: preserve_whitespace) }
         skip_types = defined?(Nokogiri) ? [Nokogiri::XML::DTD] : []
 
         if nokogiri_doc.is_a?(Nokogiri::XML::Document) && nokogiri_doc.root
-          root.add_child(build_element_node(nokogiri_doc.root,
-                                            preserve_whitespace: preserve_whitespace))
-          add_document_children(root, nokogiri_doc.children, nokogiri_doc.root,
-                                skip_types, converter)
+          root.add_child(walk_nokogiri(nokogiri_doc.root,
+                                       preserve_whitespace: preserve_whitespace))
+          TreeBuilder::DEFAULT.add_document_children(root, nokogiri_doc.children,
+                                                     nokogiri_doc.root, skip_types) do |child|
+            walk_nokogiri(child, preserve_whitespace: preserve_whitespace)
+          end
         else
-          add_document_children(root, nokogiri_doc.children, nil,
-                                skip_types, converter)
+          TreeBuilder::DEFAULT.add_document_children(root, nokogiri_doc.children,
+                                                     nil, skip_types) do |child|
+            walk_nokogiri(child, preserve_whitespace: preserve_whitespace)
+          end
         end
 
         root
       end
 
-      def self.build_node_from_nokogiri(nokogiri_node,
-preserve_whitespace: false, inherited_namespaces: nil)
-        case nokogiri_node
+      def self.walk_nokogiri(node, preserve_whitespace:,
+inherited_namespaces: nil)
+        case node
         when Nokogiri::XML::Element
-          build_element_node(nokogiri_node,
-                             preserve_whitespace: preserve_whitespace,
-                             inherited_namespaces: inherited_namespaces)
+          scope = TreeBuilder::DEFAULT.merge_namespace_scope(
+            inherited_namespaces,
+            node.namespace_definitions.map { |ns| [ns.prefix, ns.href] },
+          )
+          element = TreeBuilder::DEFAULT.element(
+            name: node.name,
+            prefix: node.namespace&.prefix,
+            namespace_uri: node.namespace&.href,
+            attributes: node.attribute_nodes.map do |attr|
+              [attr.name, attr.value, attr.namespace&.href, attr.namespace&.prefix]
+            end,
+            namespace_scope: scope,
+          )
+          node.children.each do |child|
+            built = walk_nokogiri(child,
+                                  preserve_whitespace: preserve_whitespace,
+                                  inherited_namespaces: scope)
+            element.add_child(built) if built
+          end
+          element
         when Nokogiri::XML::Text, Nokogiri::XML::CDATA
-          build_text_node(nokogiri_node,
-                          preserve_whitespace: preserve_whitespace)
+          TreeBuilder::DEFAULT.text(node.content,
+                                    keep: WhitespacePolicy.keep_dom_text?(
+                                      node.content,
+                                      preserve_whitespace: preserve_whitespace,
+                                      element_parent: node.parent.is_a?(Nokogiri::XML::Element),
+                                    ),
+                                    original: node.to_xml)
         when Nokogiri::XML::Comment
-          build_comment_node(nokogiri_node)
+          TreeBuilder::DEFAULT.comment(node.content)
         when Nokogiri::XML::ProcessingInstruction
-          build_pi_node(nokogiri_node)
-        end
-      end
-
-      def self.build_element_node(nokogiri_element, preserve_whitespace: false,
-inherited_namespaces: nil)
-        element = Nodes::ElementNode.new(
-          name: nokogiri_element.name,
-          namespace_uri: nokogiri_element.namespace&.href,
-          prefix: nokogiri_element.namespace&.prefix,
-        )
-
-        scope = nokogiri_namespace_scope(nokogiri_element, inherited_namespaces)
-        scope.each do |prefix, uri|
-          element.add_namespace(Nodes::NamespaceNode.new(
-                                  prefix: prefix,
-                                  uri: uri,
-                                ))
-        end
-
-        build_attribute_nodes(nokogiri_element, element)
-
-        nokogiri_element.children.each do |child|
-          node = build_node_from_nokogiri(child,
-                                          preserve_whitespace: preserve_whitespace,
-                                          inherited_namespaces: scope)
-          element.add_child(node) if node
-        end
-
-        element
-      end
-
-      # In-scope bindings via the shared kernel; the scope is passed down
-      # the recursion — one definition fetch per element instead of an
-      # ancestor walk per element (O(n) total, not O(n * depth)).
-      def self.nokogiri_namespace_scope(nokogiri_element, inherited)
-        merge_namespace_scope(inherited,
-                              nokogiri_element.namespace_definitions.map do |ns|
-                                [ns.prefix, ns.href]
-                              end)
-      end
-
-      def self.build_attribute_nodes(nokogiri_element, element)
-        # attribute_nodes, not the attributes hash: the hash is keyed by
-        # local name and collapses e.g. attr / a:attr / b:attr into one
-        # entry, losing namespaced attributes (W3C C14N ex 3.3).
-        nokogiri_element.attribute_nodes.each do |attr|
-          attr_node = Nodes::AttributeNode.new(
-            name: attr.name,
-            value: attr.value,
-            namespace_uri: attr.namespace&.href,
-            prefix: attr.namespace&.prefix,
-          )
-          element.add_attribute(attr_node)
-        end
-      end
-
-      def self.build_text_node(nokogiri_text, preserve_whitespace: false)
-        content = nokogiri_text.content
-
-        unless WhitespacePolicy.keep_dom_text?(content,
-                                               preserve_whitespace: preserve_whitespace,
-                                               element_parent: nokogiri_text.parent.is_a?(Nokogiri::XML::Element))
-          return nil
+          TreeBuilder::DEFAULT.processing_instruction(node.name, node.content)
         end
-
-        original = nokogiri_text.to_xml
-        Nodes::TextNode.new(value: content, original: original)
       end
 
-      def self.build_comment_node(nokogiri_comment)
-        Nodes::CommentNode.new(value: nokogiri_comment.content)
-      end
-
-      def self.build_pi_node(nokogiri_pi)
-        Nodes::ProcessingInstructionNode.new(
-          target: nokogiri_pi.name,
-          data: nokogiri_pi.content,
-        )
-      end
-
-      # --- Moxml path ---
+      # -- moxml record stream: post-order frames adopt children --
+      # One flattened record stream (moxml#132/#138) instead of a
+      # wrapper walk, so document conversion costs no Moxml::Node
+      # allocation per node. Own namespace declarations ride an
+      # identity-keyed stash; assign_moxml_namespace_scopes expands
+      # them to in-scope scopes afterwards (post-order arrival means
+      # scopes cannot flow down during the stream).
 
       def self.from_moxml_xml(xml_string, preserve_whitespace:)
         doc = Canon::XmlParsing.moxml_context.parse(xml_string, readonly: true)
@@ -301,35 +235,26 @@ inherited_namespaces: nil)
 
       def self.build_from_moxml(moxml_doc, preserve_whitespace: false)
         root = Nodes::RootNode.new
-
-        converter = ->(child) { build_moxml_node(child, preserve_whitespace: preserve_whitespace) }
         skip_types = [Moxml::Doctype]
 
         if moxml_doc.is_a?(Moxml::Document) && moxml_doc.root
           element = build_moxml_subtree_from_records(moxml_doc.root,
                                                      preserve_whitespace: preserve_whitespace)
           root.add_child(element) if element
-          add_document_children(root, moxml_doc.children, moxml_doc.root,
-                                skip_types, converter)
+          TreeBuilder::DEFAULT.add_document_children(root, moxml_doc.children,
+                                                     moxml_doc.root, skip_types) do |child|
+            walk_moxml(child, preserve_whitespace: preserve_whitespace)
+          end
         else
-          add_document_children(root, moxml_doc.children, nil,
-                                skip_types, converter)
+          TreeBuilder::DEFAULT.add_document_children(root, moxml_doc.children,
+                                                     nil, skip_types) do |child|
+            walk_moxml(child, preserve_whitespace: preserve_whitespace)
+          end
         end
 
         root
       end
 
-      # Document path: build the root subtree from materialize records —
-      # one flattened record stream (moxml#132/#138) instead of a wrapper
-      # walk, so conversion costs no Moxml::Node allocation per node.
-      #
-      # Records arrive post-order (children before parents): completed
-      # nodes stack up with their depth, and an element record adopts
-      # every completed node deeper than itself. Each element's OWN
-      # namespace declarations ride an identity-keyed stash; afterwards
-      # assign_moxml_namespace_scopes expands them to in-scope scopes
-      # with the same first-wins/xml-prebound semantics as the Nokogiri
-      # collector.
       def self.build_moxml_subtree_from_records(moxml_element,
 preserve_whitespace: false)
         frames = []
@@ -339,8 +264,8 @@ preserve_whitespace: false)
           # The record contract is root-subtree-only since moxml 0.5.11
           # (moxml#140). Older 0.5.x releases — still allowed by canon's
           # gemspec floor — leaked epilog document-level records at depth
-          # 0, which the document-children enumeration below also covers;
-          # one integer compare per record keeps those working.
+          # 0, which the document-children enumeration also covers; one
+          # integer compare per record keeps those working.
           next if record[:depth].zero? && record[:kind] != :element
 
           node = case record[:kind]
@@ -348,14 +273,16 @@ preserve_whitespace: false)
                    build_moxml_element_from_record(record, frames,
                                                    own_namespaces)
                  when :text, :cdata
-                   build_moxml_text_from_record(record, preserve_whitespace)
+                   content = record[:text].to_s
+                   TreeBuilder::DEFAULT.text(content,
+                                             keep: WhitespacePolicy.keep_dom_text?(
+                                               content, preserve_whitespace: preserve_whitespace
+                                             ))
                  when :comment
-                   Nodes::CommentNode.new(value: record[:text])
+                   TreeBuilder::DEFAULT.comment(record[:text])
                  when :processing_instruction
-                   Nodes::ProcessingInstructionNode.new(
-                     target: record[:qname],
-                     data: record[:text] || "",
-                   )
+                   TreeBuilder::DEFAULT.processing_instruction(record[:qname],
+                                                               record[:text] || "")
                  end
 
           frames.push([record[:depth], node]) if node
@@ -364,34 +291,18 @@ preserve_whitespace: false)
         top = frames.last
         return nil unless top
 
-        element = top[1]
-        assign_moxml_namespace_scopes(element,
-                                      { "xml" => "http://www.w3.org/XML/1998/namespace" },
-                                      own_namespaces)
-        element
+        assign_moxml_namespace_scopes(top[1], nil, own_namespaces)
+        top[1]
       end
 
       def self.build_moxml_element_from_record(record, frames, own_namespaces)
-        element = Nodes::ElementNode.new(
+        element = TreeBuilder::DEFAULT.element(
           name: record[:qname],
-          namespace_uri: record[:namespace_uri],
           prefix: record[:prefix],
+          namespace_uri: record[:namespace_uri],
+          attributes: record[:attributes],
         )
 
-        seen = {}
-        record[:attributes].each do |name, value, namespace_uri, prefix|
-          key = [name, namespace_uri]
-          next if seen.key?(key)
-
-          seen[key] = true
-          element.add_attribute(Nodes::AttributeNode.new(
-                                  name: name,
-                                  value: value,
-                                  namespace_uri: namespace_uri,
-                                  prefix: prefix,
-                                ))
-        end
-
         # Adopt completed children: they pop in reverse order; reversing
         # once is O(n) (unshift per child would be O(n^2) on wide trees).
         children = []
@@ -402,133 +313,54 @@ preserve_whitespace: false)
         element
       end
 
-      # Text records inside a document subtree always have an element
-      # parent (only the document element sits at depth 0), so the
-      # whitespace-only skip rule matches the wrapper path exactly.
-      def self.build_moxml_text_from_record(record, preserve_whitespace)
-        content = record[:text].to_s
-        return nil unless WhitespacePolicy.keep_dom_text?(content, preserve_whitespace: preserve_whitespace)
-
-        Nodes::TextNode.new(value: content, original: content)
-      end
-
-      # Expand each element's own declarations to in-scope bindings via
-      # the shared kernel. Scope flows down the canon tree — no engine
-      # calls.
       def self.assign_moxml_namespace_scopes(element, inherited, own_namespaces)
-        scope = merge_namespace_scope(inherited, own_namespaces[element].to_a)
-
-        scope.each do |prefix, uri|
-          element.add_namespace(Nodes::NamespaceNode.new(
-                                  prefix: prefix,
-                                  uri: uri,
-                                ))
-        end
+        scope = TreeBuilder::DEFAULT.merge_namespace_scope(inherited,
+                                                           own_namespaces[element].to_a)
+        TreeBuilder::DEFAULT.attach_namespace_scope(element, scope)
 
         element.children.each do |child|
           assign_moxml_namespace_scopes(child, scope, own_namespaces) if child.is_a?(Nodes::ElementNode)
         end
       end
 
-      def self.build_moxml_node(node, preserve_whitespace: false,
+      # -- moxml wrapper walk: fragments and user-supplied nodes --
+
+      def self.walk_moxml(node, preserve_whitespace: false,
 inherited_namespaces: nil)
         case node
         when Moxml::Element
-          build_moxml_element_node(node,
-                                   preserve_whitespace: preserve_whitespace,
-                                   inherited_namespaces: inherited_namespaces)
+          scope = TreeBuilder::DEFAULT.merge_namespace_scope(
+            inherited_namespaces,
+            node.namespace_definitions.map { |ns| [ns.prefix, ns.uri] },
+          )
+          element = TreeBuilder::DEFAULT.element(
+            name: node.name,
+            prefix: node.namespace&.prefix,
+            namespace_uri: node.namespace&.uri,
+            attributes: node.attributes.map do |attr|
+              [attr.name, attr.value, attr.namespace&.uri, attr.namespace&.prefix]
+            end,
+            namespace_scope: scope,
+          )
+          node.children.each do |child|
+            built = walk_moxml(child,
+                               preserve_whitespace: preserve_whitespace,
+                               inherited_namespaces: scope)
+            element.add_child(built) if built
+          end
+          element
         when Moxml::Text, Moxml::Cdata
-          build_moxml_text_node(node, preserve_whitespace: preserve_whitespace)
+          TreeBuilder::DEFAULT.text(node.content,
+                                    keep: WhitespacePolicy.keep_dom_text?(
+                                      node.content,
+                                      preserve_whitespace: preserve_whitespace,
+                                      element_parent: node.parent.is_a?(Moxml::Element),
+                                    ))
         when Moxml::Comment
-          build_moxml_comment_node(node)
+          TreeBuilder::DEFAULT.comment(node.content)
         when Moxml::ProcessingInstruction
-          build_moxml_pi_node(node)
-        end
-      end
-
-      def self.build_moxml_element_node(moxml_element,
-preserve_whitespace: false,
-inherited_namespaces: nil)
-        ns = moxml_element.namespace
-        element = Nodes::ElementNode.new(
-          name: moxml_element.name,
-          namespace_uri: ns&.uri,
-          prefix: ns&.prefix,
-        )
-
-        scope = moxml_namespace_scope(moxml_element, inherited_namespaces)
-        scope.each do |prefix, uri|
-          element.add_namespace(Nodes::NamespaceNode.new(
-                                  prefix: prefix,
-                                  uri: uri,
-                                ))
+          TreeBuilder::DEFAULT.processing_instruction(node.target, node.content)
         end
-
-        build_moxml_attribute_nodes(moxml_element, element)
-
-        moxml_element.children.each do |child|
-          node = build_moxml_node(child,
-                                  preserve_whitespace: preserve_whitespace,
-                                  inherited_namespaces: scope)
-          element.add_child(node) if node
-        end
-
-        element
-      end
-
-      # In-scope namespace bindings: the element's own declarations
-      # shadow inherited ones, xml is prebound. The scope is passed down
-      # the recursion so each element pays one declaration fetch instead
-      # of an ancestor walk through the adapter layer (the Nokogiri
-      # collector walks ancestors because those calls are cheap there).
-      def self.moxml_namespace_scope(moxml_element, inherited)
-        merge_namespace_scope(inherited,
-                              moxml_element.namespace_definitions.map do |decl|
-                                [decl.prefix, decl.uri]
-                              end)
-      end
-
-      def self.build_moxml_attribute_nodes(moxml_element, element)
-        seen = {}
-        moxml_element.attributes.each do |attr|
-          # Duplicate attribute names are invalid XML; engines expose
-          # them differently (libxml2 lists repeats, libleptris dedups
-          # last-wins). Canon follows the Nokogiri presentation contract:
-          # first occurrence wins, keyed by name + namespace.
-          key = [attr.name, attr.namespace&.uri]
-          next if seen.key?(key)
-
-          seen[key] = true
-          element.add_attribute(Nodes::AttributeNode.new(
-                                  name: attr.name,
-                                  value: attr.value,
-                                  namespace_uri: attr.namespace&.uri,
-                                  prefix: attr.namespace&.prefix,
-                                ))
-        end
-      end
-
-      def self.build_moxml_text_node(moxml_text, preserve_whitespace: false)
-        content = moxml_text.content
-
-        unless WhitespacePolicy.keep_dom_text?(content,
-                                               preserve_whitespace: preserve_whitespace,
-                                               element_parent: moxml_text.parent.is_a?(Moxml::Element))
-          return nil
-        end
-
-        Nodes::TextNode.new(value: content, original: content)
-      end
-
-      def self.build_moxml_comment_node(moxml_comment)
-        Nodes::CommentNode.new(value: moxml_comment.content)
-      end
-
-      def self.build_moxml_pi_node(moxml_pi)
-        Nodes::ProcessingInstructionNode.new(
-          target: moxml_pi.target,
-          data: moxml_pi.content,
-        )
       end
     end
   end

data/lib/canon/xml/sax_builder.rb

@@ -9,6 +9,11 @@ module Canon
     # selects the driver. Much faster than DOM parsing + conversion —
     # no intermediate engine DOM tree, no traversal conversion pass.
     #
+    # Construction goes through TreeBuilder like every other feed:
+    # this class owns only what is SAX-specific — qname parsing, xmlns
+    # separation, character-reference decoding, adjacency combining,
+    # the namespace stack, and document-level reordering.
+    #
     # Usage:
     #   root = SaxBuilder.parse(xml_string, preserve_whitespace: false)
     #   # root is a Canon::Xml::Nodes::RootNode
@@ -123,26 +128,23 @@ strip_doctype: false)
           end
         end
 
-        # Push new namespace scope with declarations
+        # Push new namespace scope with declarations (own shadows
+        # inherited — the same merge the TreeBuilder scope kernel applies)
         new_scope = @namespace_stack.last.merge(ns_hash)
         @namespace_stack.push(new_scope)
 
-        # Find namespace URI from current scope
-        ns_uri = new_scope[prefix.to_s]
-
-        # Create element node
-        element = Nodes::ElementNode.new(
+        element = TreeBuilder::DEFAULT.element(
           name: local_name,
-          namespace_uri: ns_uri,
           prefix: prefix,
+          namespace_uri: new_scope[prefix.to_s],
+          namespace_scope: new_scope,
+          attributes: regular_attrs.map do |attr_name, attr_value|
+            attr_prefix, attr_local = parse_qname(attr_name)
+            attr_ns_uri = attr_prefix ? new_scope[attr_prefix] : nil
+            [attr_local, decode_character_references(attr_value || ""), attr_ns_uri, attr_prefix]
+          end,
         )
 
-        # Add namespace nodes from current scope
-        add_namespace_nodes(element, new_scope)
-
-        # Build and add attribute nodes (excluding xmlns declarations)
-        add_attribute_nodes(element, regular_attrs)
-
         parent.add_child(element)
         @stack.push(element)
       end
@@ -200,13 +202,15 @@ strip_doctype: false)
 
         # Skip whitespace-only text nodes unless preserving, per the SAX
         # policy (CR-bearing content always survives for C14N;
-        # non-ASCII whitespace is meaningful content).
+        # non-ASCII whitespace is meaningful content; document-level
+        # whitespace drops with every policy).
         return unless WhitespacePolicy.keep_sax_text?(decoded_string,
                                                       preserve_whitespace: @preserve_whitespace,
                                                       element_parent: parent.node_type == :element)
 
-        text = Nodes::TextNode.new(value: decoded_string, original: raw_string)
-        parent.add_child(text)
+        parent.add_child(
+          TreeBuilder::DEFAULT.text(decoded_string, keep: true, original: raw_string),
+        )
       end
       private :append_text
 
@@ -214,9 +218,7 @@ strip_doctype: false)
       #
       # @param string [String] Comment content
       def comment(string)
-        parent = @stack.last
-        comment_node = Nodes::CommentNode.new(value: string)
-        parent.add_child(comment_node)
+        @stack.last.add_child(TreeBuilder::DEFAULT.comment(string))
       end
 
       # Called for processing instructions
@@ -224,10 +226,9 @@ strip_doctype: false)
       # @param name [String] PI target
       # @param content [String] PI content
       def processing_instruction(name, content)
-        parent = @stack.last
-        pi = Nodes::ProcessingInstructionNode.new(target: name,
-                                                  data: content || "")
-        parent.add_child(pi)
+        @stack.last.add_child(
+          TreeBuilder::DEFAULT.processing_instruction(name, content || ""),
+        )
       end
 
       # Return the built tree
@@ -313,44 +314,7 @@ strip_doctype: false)
         [ns_decls, regular_attrs]
       end
 
-      # Add namespace nodes to element
-      #
-      # @param element [Nodes::ElementNode] Element to add namespaces to
-      # @param scope [Hash] Current namespace scope
-      def add_namespace_nodes(element, scope)
-        scope.each do |prefix, uri|
-          ns_node = Nodes::NamespaceNode.new(prefix: prefix, uri: uri)
-          element.add_namespace(ns_node)
-        end
-      end
-
-      # Add attribute nodes to element
-      #
-      # @param element [Nodes::ElementNode] Element to add attributes to
-      # @param attrs [Array] Array of [name, value] pairs
-      def add_attribute_nodes(element, attrs)
-        attrs.each do |attr_name, attr_value|
-          attr_prefix, attr_local = parse_qname(attr_name)
-
-          # Find namespace for attribute (if prefixed)
-          attr_ns_uri = attr_prefix ? @namespace_stack.last[attr_prefix] : nil
-
-          # Decode numeric character references (e.g., & → &)
-          # Nokogiri SAX leaves these as-is, but we need them decoded for C14N
-          decoded_value = decode_character_references(attr_value || "")
-
-          attr_node = Nodes::AttributeNode.new(
-            name: attr_local,
-            value: decoded_value,
-            namespace_uri: attr_ns_uri,
-            prefix: attr_prefix,
-          )
-          element.add_attribute(attr_node)
-        end
-      end
-
-      # Decode numeric character references in a string
-      # Handles both &#decimal; and &#xhex; forms
+      # Decode numeric character references (e.g., & → &)
       #
       # @param value [String] String potentially containing character references
       # @return [String] String with character references decoded

data/lib/canon/xml/tree_builder.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    # The one place canon tree nodes are constructed from parsed XML.
+    #
+    # Owns construction semantics: namespace scopes, attribute
+    # normalization, node kinds, and document-level ordering. Keep/strip
+    # decisions come from WhitespacePolicy (one home for all three
+    # policies); engine walks — the Nokogiri and moxml extractors in
+    # Xml::DataModel, the HTML walk in Html::DataModel — only map their
+    # engine's shapes onto this interface.
+    #
+    # Attribute normalization: duplicate (name, namespace) pairs are
+    # invalid XML; engines expose them differently (libxml2 lists
+    # repeats, libleptris deduplicates), so the builder resolves them
+    # once — first occurrence wins.
+    class TreeBuilder
+      # Stateless module: one shared instance serves every feed.
+      DEFAULT = new
+
+      NO_ATTRIBUTES = [].freeze
+      XML_NAMESPACE_PREFIX = "xml"
+      XML_NAMESPACE_URI = "http://www.w3.org/XML/1998/namespace"
+
+      # In-scope namespace bindings: the element's own declarations
+      # shadow inherited ones; xml is prebound at the base. Declaration
+      # pairs are [prefix-or-nil, uri]; nil and "" both mean the default
+      # namespace.
+      def merge_namespace_scope(inherited, declaration_pairs)
+        scope = inherited ? inherited.dup : { XML_NAMESPACE_PREFIX => XML_NAMESPACE_URI }
+        declaration_pairs.each do |prefix, uri|
+          scope[prefix || ""] = uri
+        end
+        scope
+      end
+
+      # Attach an in-scope scope to an element as namespace nodes.
+      def attach_namespace_scope(element, scope)
+        scope.each do |prefix, uri|
+          element.add_namespace(Nodes::NamespaceNode.new(
+                                  prefix: prefix,
+                                  uri: uri,
+                                ))
+        end
+      end
+
+      # Build an element. `attributes` are [name, value, namespace_uri,
+      # prefix] pairs; `namespace_scope` is a merged scope (or nil for
+      # no namespace nodes).
+      def element(name:, prefix: nil, namespace_uri: nil,
+                  attributes: NO_ATTRIBUTES, namespace_scope: nil)
+        element = Nodes::ElementNode.new(
+          name: name,
+          namespace_uri: namespace_uri,
+          prefix: prefix,
+        )
+        attach_namespace_scope(element, namespace_scope) if namespace_scope
+
+        # Duplicate (name, namespace) pairs are invalid XML — first
+        # occurrence wins. Attributes per element are few, so a pairwise
+        # scan beats a per-element seen-hash on allocation (this is the
+        # hot SAX path).
+        attributes.each_with_index do |(attr_name, value, attr_namespace_uri, attr_prefix), index|
+          duplicate = attributes[0...index].any? do |prior_name, _v, prior_ns, _p|
+            prior_name == attr_name && prior_ns == attr_namespace_uri
+          end
+          next if duplicate
+
+          element.add_attribute(Nodes::AttributeNode.new(
+                                  name: attr_name,
+                                  value: value,
+                                  namespace_uri: attr_namespace_uri,
+                                  prefix: attr_prefix,
+                                ))
+        end
+
+        element
+      end
+
+      # Build a text node; `keep` comes from WhitespacePolicy (the
+      # caller knows the policy and parent context).
+      def text(content, keep:, original: content)
+        return nil unless keep
+
+        Nodes::TextNode.new(value: content, original: original)
+      end
+
+      def comment(content)
+        Nodes::CommentNode.new(value: content)
+      end
+
+      def processing_instruction(target, data)
+        Nodes::ProcessingInstructionNode.new(target: target, data: data)
+      end
+
+      # Attach document-level children (prolog/epilog PIs, comments,
+      # document-level text) to the canon root, in document order,
+      # skipping the document element and the given types. Yields each
+      # child to the caller's converter; nil results are dropped.
+      def add_document_children(root, children, document_element,
+                                skip_types = [])
+        children.each do |child|
+          next if child.equal?(document_element)
+          next if skip_types.any? { |type| child.is_a?(type) }
+
+          node = yield child
+          root.add_child(node) if node
+        end
+      end
+    end
+  end
+end

data/lib/canon/xml/whitespace_policy.rb

@@ -4,8 +4,15 @@ module Canon
   module Xml
     # Parse-time whitespace policy: whether a character-data node
     # survives conversion. One home for the keep/strip rules so the
-    # DOM/SAX differences are visible here instead of implied by
+    # DOM/SAX/HTML differences are visible here instead of implied by
     # copy-paste across conversion sites.
+    #
+    # Document-level character data (outside the root element) can only
+    # be whitespace per the XML grammar, and the XPath data model —
+    # which canon's tree and C14N follow — has no root text children at
+    # all. Every policy therefore drops whitespace-only document-level
+    # text; engines that report it (libxml2 does not, libleptris 1.9.38+
+    # does) stay byte-compatible through here.
     module WhitespacePolicy
       module_function
 
@@ -15,9 +22,14 @@ module Canon
       #
       # NOTE: CR-only nodes are dropped on this path; the SAX rule keeps
       # them (character references must survive for C14N).
-      def keep_dom_text?(content, preserve_whitespace:, element_parent: true)
+      def keep_dom_text?(content, preserve_whitespace:,
+element_parent: true)
+        # The XPath data model has no root text children — drop
+        # whitespace-only document-level text even when preserving
+        # (engines that report it stay byte-compatible with libxml2).
+        return false if !element_parent && content.strip.empty?
+
         return true if preserve_whitespace
-        return true unless element_parent
 
         !content.strip.empty?
       end
@@ -25,13 +37,33 @@ module Canon
       # SAX rule: same shape, plus CR-bearing content is always kept
       # (
 must survive parsing for C14N) — only runs of pure ASCII
       # whitespace (space, tab, CR, LF) are dropped when not preserving.
-      def keep_sax_text?(content, preserve_whitespace:, element_parent: true)
+      def keep_sax_text?(content, preserve_whitespace:,
+element_parent: true)
+        return false if !element_parent && content.strip.empty?
+
         return true if preserve_whitespace
-        return true unless element_parent
         return true if content.include?("\r")
 
         !content.gsub(/[ \t\r\n]/, "").empty?
       end
+
+      # HTML conversion rule: whitespace-only text is dropped except in
+      # whitespace-sensitive elements (pre/code/textarea/script/style),
+      # between inline siblings (semantically significant), and when it
+      # carries NBSP (U+00A0 — never insignificant; strip is ASCII-only
+      # so it is checked explicitly).
+      HTML_WHITESPACE_SENSITIVE_TAGS = %w[pre code textarea script style].freeze
+
+      def keep_html_text?(content, parent_name:, inline_significant: false)
+        return true unless content.strip.empty?
+        return true if content.include?(" ")
+
+        parent_name = parent_name.to_s.downcase
+        return true if HTML_WHITESPACE_SENSITIVE_TAGS.include?(parent_name)
+        return true if inline_significant
+
+        false
+      end
     end
   end
 end

data/lib/canon/xml.rb

@@ -27,6 +27,7 @@ module Canon
     autoload :Processor, "canon/xml/processor"
     autoload :Sax, "canon/xml/sax"
     autoload :SaxBuilder, "canon/xml/sax_builder"
+    autoload :TreeBuilder, "canon/xml/tree_builder"
     autoload :WhitespaceNormalizer, "canon/xml/whitespace_normalizer"
     autoload :WhitespacePolicy, "canon/xml/whitespace_policy"
     autoload :XmlBaseHandler, "canon/xml/xml_base_handler"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.6
 platform: ruby
 authors:
 - Ribose Inc.
@@ -400,6 +400,7 @@ files:
 - lib/canon/xml/sax/moxml_driver.rb
 - lib/canon/xml/sax/nokogiri_driver.rb
 - lib/canon/xml/sax_builder.rb
+- lib/canon/xml/tree_builder.rb
 - lib/canon/xml/whitespace_normalizer.rb
 - lib/canon/xml/whitespace_policy.rb
 - lib/canon/xml/xml_base_handler.rb