metanorma-document 0.2.12 → 0.2.13

data/lib/metanorma/html/base_renderer.rb

@@ -6,16 +6,15 @@ require "cgi"
 
 module Metanorma
   module Html
-    module Renderers
-      autoload :InlineRenderer, "metanorma/html/renderers/inline_renderer"
-      autoload :BlockRenderer, "metanorma/html/renderers/block_renderer"
-      autoload :SectionRenderer, "metanorma/html/renderers/section_renderer"
-      autoload :PubidRenderer, "metanorma/html/renderers/pubid_renderer"
-    end
-
+    # Renders BasicDocument components to HTML.
+    # Subclassed by StandardRenderer and flavor-specific renderers.
+    # Owns the full HTML document generation pipeline: body content, header,
+    # footer, ToC sidebar, CSS (via Theme), and JavaScript.
     class BaseRenderer
       LOGO_DIR = File.expand_path("../../../data/logos", __dir__)
 
+      # HTML-specific class names for inline spans, keyed by the XML span role.
+      # The XML class_attr is INPUT only — we never emit it in HTML.
       SPAN_ROLE_CLASSES = {
         "boldtitle" => "title-text",
         "nonboldtitle" => "subtitle-text",
@@ -45,6 +44,8 @@ module Metanorma
 
       METANORMA_LOGO = "metanorma-logo.svg"
 
+      # Type-to-method registry for OCP dispatch.
+      # Each subclass gets its own hash; lookup traverses ancestors.
       class << self
         def render_registry
           @render_registry ||= {}
@@ -63,12 +64,8 @@ module Metanorma
         end
       end
 
-      attr_reader :inline_renderer, :block_renderer, :section_renderer,
-                  :pubid_renderer, :index_term_collector, :footnote_collector
-      private :inline_renderer, :block_renderer, :section_renderer,
-              :pubid_renderer
-
       def initialize
+        @output = +""
         @toc_entries = []
         @figure_entries = []
         @table_entries = []
@@ -76,107 +73,86 @@ module Metanorma
         @footnote_collector = Component::FootnoteCollector.new
         @current_section_id = nil
         @current_section_number = nil
-
-        @inline_renderer = Renderers::InlineRenderer.new(self)
-        @block_renderer = Renderers::BlockRenderer.new(self)
-        @section_renderer = Renderers::SectionRenderer.new(self)
-        @pubid_renderer = Renderers::PubidRenderer.new(self)
       end
 
+      # --- Public API ---
+
+      # Facade object for Drops to call renderer methods without exposing
+      # the full private interface. Delegates via method_missing with an
+      # explicit allowlist — adding new delegations only requires updating
+      # DELEGATED_METHODS, not writing a new one-liner.
       class RendererContext
+        DELEGATED_METHODS = %i[
+          safe_attr escape_html extract_block_label extract_plain_text
+          capture_output render_paragraph render_mixed_inline
+          render_inline_element render_unordered_list render_ordered_list
+          render_definition_list render_sourcecode render_table
+          render_figure render_quote render_formula render_note
+          render_image render_stem_content register_figure_entry
+          render_liquid render_block_children
+        ].freeze
+
         def initialize(renderer)
           @renderer = renderer
         end
 
-        def safe_attr(...)        = @renderer.safe_attr(...)
-        def escape_html(...)      = @renderer.escape_html(...)
-        def extract_block_label(...)= @renderer.extract_block_label(...)
-        def extract_plain_text(...)= @renderer.extract_plain_text(...)
-        def render_paragraph(...) = @renderer.render_paragraph(...)
-        def render_mixed_inline(...)= @renderer.render_mixed_inline(...)
-        def render_inline_element(...)= @renderer.render_inline_element(...)
-        def render_unordered_list(...)= @renderer.render_unordered_list(...)
-        def render_ordered_list(...)= @renderer.render_ordered_list(...)
-        def render_definition_list(...)= @renderer.render_definition_list(...)
-        def render_sourcecode(...)  = @renderer.render_sourcecode(...)
-        def render_table(...)       = @renderer.render_table(...)
-        def render_figure(...)      = @renderer.render_figure(...)
-        def render_quote(...)       = @renderer.render_quote(...)
-        def render_formula(...)     = @renderer.render_formula(...)
-        def render_note(...)        = @renderer.render_note(...)
-        def render_image(...)       = @renderer.render_image(...)
-        def render_stem_content(...)= @renderer.render_stem_content(...)
-        def register_figure_entry(...)= @renderer.register_figure_entry(...)
-        def render_liquid(...) = @renderer.render_liquid(...)
-        def render_note_children(...) = @renderer.render_note_children(...)
-        def render_simple_children(...) = @renderer.render_simple_children(...)
-        def render_full_block_children(...) = @renderer.render_full_block_children(...)
+        def respond_to_missing?(method_name, include_private = false)
+          DELEGATED_METHODS.include?(method_name) || super
+        end
+
+        private
+
+        def method_missing(method_name, ...)
+          if DELEGATED_METHODS.include?(method_name)
+            @renderer.public_send(method_name, ...)
+          else
+            super
+          end
+        end
       end
 
       def renderer_context
         @renderer_context ||= RendererContext.new(self)
       end
 
+      def to_html
+        @output
+      end
+
       def toc_entries
         @toc_entries
       end
 
-      attr_writer :document, :theme
-
-      def generate_full_document(document, **)
+      # Generate a complete HTML document from a presentation XML document.
+      def generate_full_document(document)
         @document = document
         validate_presentation_xml!
 
-        body = render(@document) || ""
+        # First pass: render body content (collects ToC entries as side effect)
+        render(@document)
+        body = @output
 
         assemble_document(body)
       end
 
-      # --- Flavor configuration hooks ---
-
-      FLAVOR_MAP = {
-        "IsoDocument" => :iso,
-        "IecDocument" => :iec,
-        "IeeeDocument" => :ieee,
-        "IetfDocument" => :ietf,
-        "ItuDocument" => :itu,
-        "IhoDocument" => :iho,
-        "BipmDocument" => :bipm,
-        "OgcDocument" => :ogc,
-        "OimlDocument" => :oiml,
-        "CcDocument" => :cc,
-        "IccDocument" => :icc,
-        "RiboseDocument" => :ribose,
-        "PdfaDocument" => :pdfa,
-      }.freeze
+      # --- Flavor configuration hooks (override in subclasses) ---
 
       def theme
-        @theme ||= resolve_theme
-      end
-
-      def resolve_theme
-        flavor = flavor_name
-        flavor ? Theme.load(flavor) : Theme.new
-      end
-
-      def flavor_name
-        return nil unless defined?(@document) && @document
-
-        @document.class.name&.split("::")&.detect do |ns|
-          FLAVOR_MAP.key?(ns)
-        end&.then { |ns| FLAVOR_MAP[ns] }
+        @theme ||= Theme.new
       end
 
       def flavor_publishers(_doc_id)
-        theme.publishers
+        []
       end
 
       def flavor_publisher_name
-        theme.publisher_name
+        pubs = flavor_publishers(extract_primary_doc_id)
+        pubs.empty? ? nil : pubs.join("/")
       end
 
+      # Map of publisher name => logo filename. Override in flavor renderers.
       def publisher_logo_map
-        theme.logos_light
+        {}
       end
 
       def flavor_font_url
@@ -189,7 +165,7 @@ module Metanorma
       TEMPLATE_CACHE_MUTEX = Mutex.new
 
       def render_liquid(template_name, assigns)
-        template_path = theme.resolve_template(template_name)
+        template_path = File.join(TEMPLATES_ROOT, template_name)
         template = TEMPLATE_CACHE_MUTEX.synchronize do
           TEMPLATE_CACHE[template_path] ||= Liquid::Template.parse(File.read(template_path))
         end
@@ -235,7 +211,7 @@ module Metanorma
       end
 
       def header_title_text
-        raw = html_title.to_s.split(" — ").first.to_s
+        raw = html_title.to_s.split(" — ").first.to_s.gsub(/<[^>]+>/, "")
         raw.length > 60 ? "#{raw[0, 57]}..." : raw
       end
 
@@ -244,7 +220,7 @@ module Metanorma
         logo_map = publisher_logo_map
         return "" if publishers.empty? && logo_map.empty?
 
-        dark_logo_map = theme.logos_dark
+        # Use flavor-declared publishers; fall back to logo map keys
         display_pubs = publishers.empty? ? logo_map.keys : publishers
 
         display_pubs.filter_map do |pub|
@@ -254,28 +230,18 @@ module Metanorma
           svg = load_logo_svg(filename, height: 26)
           next unless svg
 
-          light_span = "<span class=\"brand-logo brand-logo-light\" aria-label=\"#{pub} logo\">#{svg}</span>"
-
-          dark_span = ""
-          dark_filename = dark_logo_map[pub]
-          if dark_filename
-            dark_svg = load_logo_svg(dark_filename, height: 26)
-            if dark_svg
-              dark_span = "<span class=\"brand-logo brand-logo-dark\" aria-label=\"#{pub} logo\">#{dark_svg}</span>"
-            end
-          end
-
-          "#{light_span}\n#{dark_span}"
+          "<span class=\"brand-logo\" aria-label=\"#{pub} logo\">#{svg}</span>"
         end.join("\n")
       end
 
       def load_logo_svg(filename, height: 32)
-        path = theme.resolve_asset(filename) || File.join(LOGO_DIR, filename)
+        path = File.join(LOGO_DIR, filename)
         return nil unless File.exist?(path)
 
         svg = File.read(path)
         svg = svg.sub(/\A<\?xml[^?]*\?>\s*/, "")
         svg = svg.sub(/\A\s*<!--.*?-->\s*/m, "")
+        svg = svg.sub(/<path[^>]*style="fill:#e3000f[^"]*"[^>]*\/>/, "")
         svg = svg.sub(/<svg\s/, '<svg class="header-logo" ')
         svg = if svg.match?(/<svg[^>]*\sheight="[^"]*"/)
                 svg.sub(/(<svg[^>]*?)(\sheight="[^"]*")/,
@@ -331,10 +297,7 @@ module Metanorma
       def build_styles
         pipeline = AssetPipeline.new
         css = pipeline.compile_css(flavor_css: flavor_css_module)
-        parts = [theme.to_css_root, css, theme.to_css_extras]
-        custom_css_path = theme.theme_css_path
-        parts << File.read(custom_css_path) if custom_css_path
-        parts.join("\n")
+        "#{theme.to_css_root}\n#{css}\n#{theme.to_css_extras}"
       end
 
       # --- Validation ---
@@ -353,11 +316,12 @@ module Metanorma
         return false unless node
         return false if node.is_a?(String)
 
+        if node.is_a?(Metanorma::Document::Root) && node.type == "presentation"
+          return true
+        end
+
         if node.is_a?(Lutaml::Model::Serializable)
           node_attrs = node.class.attributes
-          if node_attrs.key?(:type) && node.type == "presentation"
-            return true
-          end
           if node_attrs.key?(:fmt_title) && node.fmt_title
             return true
           end
@@ -399,21 +363,16 @@ module Metanorma
       end
 
       def html_title
-        extract_display_title(@document.bibdata) || "Document"
-      end
-
-      def extract_display_title(bibdata)
-        return nil unless bibdata
-
-        title = bibdata.title_for("en") if bibdata.is_a?(Metanorma::Document::Components::BibData::BibData)
-        return title.to_s if title && !title.to_s.empty?
-
-        titles = safe_attr(bibdata, :title)
-        return nil unless titles && !titles.is_a?(String) && !titles.empty?
+        bibdata = @document.bibdata
+        return "Document" unless bibdata
 
-        en = titles.find { |t| safe_attr(t, :language) == "en" }
-        found = en || titles.first
-        extract_text_value(found).to_s
+        titles = bibdata.titles
+        if titles
+          title = bibdata.title_for("en")
+          title.to_s
+        else
+          "Document"
+        end
       end
 
       def extract_primary_doc_id
@@ -434,7 +393,7 @@ module Metanorma
         text.strip.empty? ? nil : text.strip
       end
 
-      # --- Registration helpers ---
+      # --- CSS loader ---
 
       def register_toc_entry(id:, level:, text:)
         @toc_entries << { id: id, level: level, text: text }
@@ -444,14 +403,12 @@ module Metanorma
         @figure_entries << { id: id, text: text }
       end
 
-      def figure_entries
-        @figure_entries
-      end
-
       def register_table_entry(id:, text:)
         @table_entries << { id: id, text: text }
       end
 
+      attr_reader :index_term_collector, :footnote_collector
+
       def extract_plain_text(node)
         return node.to_s if node.is_a?(String)
         return extract_text_value(node).to_s unless node.is_a?(Lutaml::Model::Serializable)
@@ -474,39 +431,38 @@ module Metanorma
             if el.text?
               parts << el.text_content.to_s
             elsif el.name == "tab"
-              parts << " "
+              parts << "\u00A0\u00A0"
             elsif el.name == "br"
               parts << " "
             elsif el.element?
               attr_name = element_to_attr[el.name]
-              if attr_name
-                coll = node.public_send(attr_name)
-                obj = if coll.is_a?(Array)
-                        idx = indices[attr_name]
-                        indices[attr_name] += 1
-                        coll[idx]
-                      else
-                        coll
-                      end
-                text = extract_plain_text(obj)
-                parts << (text.empty? ? " " : text)
-              elsif el.name == "span"
-                parts << " "
-              end
+              next unless attr_name
+
+              coll = node.public_send(attr_name)
+              obj = if coll.is_a?(Array)
+                      idx = indices[attr_name]
+                      indices[attr_name] += 1
+                      coll[idx]
+                    else
+                      coll
+                    end
+              parts << extract_plain_text(obj) if obj
             end
           end
         end
 
+        # Fallback: try .text
         if parts.join.strip.empty?
           t = safe_attr(node, :text)
           parts << (t.is_a?(Array) ? t.join : t.to_s) if t
         end
 
-        parts.join.strip.gsub(" ", " ")
+        parts.join.strip.gsub("\u00A0", " ")
       end
 
-      # --- Dispatch ---
-
+      # Dispatch to the appropriate render method via type registry.
+      # Lookups traverse the ancestor chain so subclasses inherit
+      # parent registrations and can override them independently.
       def render(node, **)
         return escape_html(node) if node.is_a?(String)
 
@@ -514,18 +470,20 @@ module Metanorma
         method ? public_send(method, node, **) : ""
       end
 
+      # Dispatch to the appropriate inline render method via type registry.
       def render_inline_element(element, **)
-        @inline_renderer.render_inline_element(element)
-      end
-
-      def is_title_element?(node, section)
-        title = safe_attr(section, :title)
-        return false unless title
-
-        node.equal?(title)
+        return "" if element.nil?
+        return escape_html(element) if element.is_a?(String)
+
+        method = lookup_dispatch(element.class, :inline_registry)
+        if method
+          public_send(method, element)
+        elsif element.is_a?(Lutaml::Model::Serializable) && element.mixed?
+          render_mixed_inline(element)
+        end
       end
 
-      # --- Type registrations ---
+      # --- Type registrations (class-level, evaluated at class load time) ---
 
       register_render Metanorma::Document::Components::Paragraphs::ParagraphBlock,
                       :render_paragraph
@@ -624,6 +582,7 @@ module Metanorma
                              :render_index
       register_inline_render Metanorma::Document::Components::Blocks::NoteBlock,
                              :render_note_inline
+      # All Fmt* elements delegate to render_mixed_inline
       register_inline_render Metanorma::Document::Components::Inline::FmtNameElement,
                              :render_mixed_inline
       register_inline_render Metanorma::Document::Components::Inline::FmtTitleElement,
@@ -688,163 +647,941 @@ module Metanorma
         nil
       end
 
-      # --- Delegation to sub-renderers ---
+      # --- Block-level rendering ---
+
+      def render_paragraph(p, **_opts)
+        attrs = element_attrs(id: safe_attr(p, :id),
+                              style: alignment_style(safe_attr(
+                                                       p, :alignment
+                                                     )))
+        tag("p", attrs) { render_mixed_inline(p) }
+      end
+
+      def render_table(table, **_opts)
+        attrs = element_attrs(id: safe_attr(table, :id), class: "table-block")
+        table_id = safe_attr(table, :id)
+        name_el = safe_attr(table, :fmt_name) || safe_attr(table, :name)
+        if table_id && name_el
+          register_table_entry(id: table_id, text: extract_plain_text(name_el))
+        end
+        col_count = table_column_count(table)
+        @output << "<div class=\"table-scroll-wrapper\">"
+        tag("table", attrs) do
+          name_el = safe_attr(table, :fmt_name) || safe_attr(table, :name)
+          if name_el
+            @output << "<caption>"
+            render_inline_element(name_el)
+            @output << "</caption>"
+          end
+          @output << "<colgroup>" if table.colgroup
+          render_table_colgroup(table.colgroup) if table.colgroup
+          @output << "</colgroup>" if table.colgroup
+          render_table_section(table.thead, "thead") if table.thead
+          render_table_section(table.tbody, "tbody") if table.tbody
+          if table.tfoot || (table.note && !table.note.empty?)
+            @output << "<tfoot>"
+            render_table_section_rows(table.tfoot) if table.tfoot
+            if table.note && !table.note.empty?
+              @output << "<tr><td colspan=\"#{col_count}\" class=\"table-notes\">"
+              table.note.each { |n| render_note(n) }
+              @output << "</td></tr>"
+            end
+            @output << "</tfoot>"
+          end
+        end
+        @output << "</div>"
+      end
+
+      def table_column_count(table)
+        if table.colgroup&.col && !table.colgroup.col.empty?
+          return table.colgroup.col.size
+        end
+
+        # Walk all rows to find max column count, accounting for colspan
+        max_cols = 0
+        %i[thead tbody tfoot].each do |section|
+          sec = table.public_send(section)
+          next unless sec&.tr
+
+          sec.tr.each do |tr|
+            cols = 0
+            Array(tr.th).each do |th|
+              cols += th.colspan && th.colspan > 1 ? th.colspan : 1
+            end
+            Array(tr.td).each do |td|
+              cols += td.colspan && td.colspan > 1 ? td.colspan : 1
+            end
+            max_cols = cols if cols > max_cols
+          end
+        end
+        max_cols.positive? ? max_cols : 1
+      end
+
+      def render_table_colgroup(colgroup)
+        colgroup.col&.each do |col|
+          attrs = element_attrs(style: col.width ? "width: #{col.width}" : nil)
+          @output << "<col#{attrs}>"
+        end
+      end
+
+      def render_table_section(section, tag_name)
+        @output << "<#{tag_name}>"
+        render_table_section_rows(section)
+        @output << "</#{tag_name}>"
+      end
+
+      def render_table_section_rows(section)
+        section.tr&.each do |tr|
+          @output << "<tr>"
+          walked = walk_ordered(tr) do |type, obj|
+            next unless type == :element
+
+            render_table_cell(obj)
+          end
+          unless walked
+            Array(tr.th).each { |th| render_table_cell(th, "th") }
+            Array(tr.td).each { |td| render_table_cell(td, "td") }
+          end
+          @output << "</tr>"
+        end
+      end
+
+      def render_unordered_list(ul, **_opts)
+        attrs = element_attrs(id: safe_attr(ul, :id))
+        tag("ul", attrs) do
+          ul.listitem&.each { |li| render_list_item(li) }
+        end
+      end
+
+      def render_table_cell(cell, force_tag = nil)
+        tag_name = force_tag || (cell.is_a?(Metanorma::Document::Components::Tables::HeaderTableCell) ? "th" : "td")
+        attrs = element_attrs(
+          colspan: safe_attr(cell, :colspan),
+          rowspan: safe_attr(cell, :rowspan),
+          align: safe_attr(cell, :alignment),
+          valign: safe_attr(cell, :vertical_alignment),
+        )
+        @output << "<#{tag_name}#{attrs}>"
+        render_cell_content(cell)
+        @output << "</#{tag_name}>"
+      end
+
+      def render_ordered_list(ol, **_opts)
+        attrs = element_attrs(id: safe_attr(ol, :id),
+                              start: safe_attr(ol, :start), type: safe_attr(ol, :type_attr))
+        tag("ol", attrs) do
+          ol.listitem&.each { |li| render_list_item(li) }
+        end
+      end
+
+      def render_list_item(li)
+        li_id = safe_attr(li, :id)
+        attrs = li_id ? %( id="#{escape_html(li_id)}") : ""
+        @output << "<li#{attrs}>"
+        render_mixed_content_in_order(li)
+        @output << "</li>"
+      end
+
+      # Render all children of a mixed-content node in document order,
+      # dispatching block elements to their render methods.
+      def render_mixed_content_in_order(node)
+        node.each_mixed_content do |child|
+          case child
+          when String
+            @output << escape_html(child)
+          else
+            if block_element?(child)
+              render(child)
+            else
+              render_inline_element(child)
+            end
+          end
+        end
+      end
+
+      # Collect all renderable children from a node in document order,
+      # sorted by displayorder when available. Uses walk_ordered to traverse
+      # element_order, and also gathers typed attributes that may not appear
+      # in element_order (e.g. terms, definitions on section models).
+      def collect_ordered_children(section)
+        children = []
+
+        walk_ordered(section) do |type, obj|
+          next if %i[text tab].include?(type)
+
+          children << obj
+        end
+
+        # Gather typed attributes that may not appear in element_order
+        supplementary_attrs = %i[terms definitions]
+        supplementary_attrs.each do |attr|
+          val = safe_attr(section, attr)
+          next if val.nil?
+
+          Array(val).each do |v|
+            children << v unless children.include?(v)
+          end
+        end
+
+        children.compact!
+        sort_by_displayorder(children)
+      end
+
+      # Render children of a section in displayorder, skipping title elements.
+      def render_ordered_content(section, level = 1)
+        children = collect_ordered_children(section)
+        children.each do |node|
+          next if node.is_a?(String)
+          next if is_title_element?(node, section)
+
+          render(node, level: level + 1)
+        end
+      end
+
+      def sort_by_displayorder(children)
+        children.sort_by do |node|
+          order = if node.is_a?(Lutaml::Model::Serializable) &&
+              node.class.attributes.key?(:displayorder)
+                    node.displayorder
+                  end
+          order &&= order.to_i
+          order || Float::INFINITY
+        end
+      end
+
+      def render_definition_list(dl, **_opts)
+        attrs = element_attrs(id: safe_attr(dl, :id))
+        tag("dl", attrs) do
+          dl.dt&.each_with_index do |dt, i|
+            @output << "<dt>"
+            render_mixed_inline(dt)
+            @output << "</dt>"
+            dd = dl.dd&.[](i)
+            if dd
+              @output << "<dd>"
+              render_mixed_inline(dd)
+              @output << "</dd>"
+            end
+          end
+        end
+      end
+
+      def render_figure(figure, **_opts)
+        drop = Drops::FigureDrop.from_model(figure, renderer: renderer_context)
+        @output << render_liquid("_figure.html.liquid", { "block" => drop })
+      end
+
+      def render_image(image)
+        src_val = safe_attr(image, :src) || safe_attr(image, :source)
+        attrs = element_attrs(
+          id: safe_attr(image, :id),
+          src: src_val,
+          alt: safe_attr(image, :alt),
+          height: safe_attr(image, :height),
+          width: safe_attr(image, :width),
+        )
+        @output << "<img#{attrs} />"
+      end
+
+      def render_video(video)
+        attrs = element_attrs(
+          id: safe_attr(video, :id),
+          src: safe_attr(video, :src),
+        )
+        @output << "<video#{attrs} controls></video>"
+      end
+
+      def render_audio(audio)
+        attrs = element_attrs(
+          id: safe_attr(audio, :id),
+          src: safe_attr(audio, :src),
+        )
+        @output << "<audio#{attrs} controls></audio>"
+      end
+
+      def render_note(note, **_opts)
+        drop = Drops::NoteDrop.from_model(note, renderer: renderer_context)
+        @output << render_liquid("_note.html.liquid", { "block" => drop })
+      end
+
+      def render_example(example, **_opts)
+        drop = Drops::ExampleDrop.from_model(example,
+                                             renderer: renderer_context)
+        @output << render_liquid("_example.html.liquid", { "block" => drop })
+      end
+
+      def render_sourcecode(sc, **_opts)
+        drop = Drops::SourcecodeDrop.from_model(sc, renderer: renderer_context)
+        @output << render_liquid("_sourcecode.html.liquid", { "block" => drop })
+      end
+
+      def render_formula(formula, **_opts)
+        drop = Drops::FormulaDrop.from_model(formula,
+                                             renderer: renderer_context)
+        @output << render_liquid("_formula.html.liquid", { "block" => drop })
+      end
+
+      def render_quote(quote, **_opts)
+        attrs = element_attrs(id: safe_attr(quote, :id), class: "quote")
+        tag("blockquote", attrs) do
+          quote.paragraphs&.each { |para| render_paragraph(para) }
+          quote.ul&.each { |ul| render_unordered_list(ul) }
+          quote.ol&.each { |ol| render_ordered_list(ol) }
+          if quote.attribution
+            @output << "<footer>"
+            render_mixed_inline(quote.attribution)
+            @output << "</footer>"
+          end
+        end
+      end
+
+      def render_admonition(admonition, **_opts)
+        drop = Drops::AdmonitionDrop.from_model(admonition,
+                                                renderer: renderer_context)
+        @output << render_liquid("_admonition.html.liquid", { "block" => drop })
+      end
+
+      def render_bookmark(bookmark, **_opts)
+        @output << %(<a id="#{escape_html(safe_attr(bookmark, :id).to_s)}"></a>)
+      end
+
+      # Renders the typed child collections of a block element (paragraphs,
+      # lists, nested blocks) in a standard order.  Used by Drops and section
+      # rendering to avoid duplicating the enumeration in each consumer.
+      #
+      # +children+ is a Hash mapping attr names to render-method symbols:
+      #   { paragraphs: :render_paragraph, ul: :render_unordered_list, ... }
+      #
+      # Each key is sent to +model+ via safe_attr; non-nil results are
+      # dispatched to the corresponding render method.
+      def render_block_children(model, children:)
+        children.each do |attr, render_method|
+          values = safe_attr(model, attr)
+          next if values.nil?
+
+          Array(values).each { |v| public_send(render_method, v) }
+        end
+      end
+
+      # Standard child set for container blocks (example, note, etc.)
+      BLOCK_CHILDREN = {
+        paragraphs: :render_paragraph,
+        ul: :render_unordered_list,
+        ol: :render_ordered_list,
+        dl: :render_definition_list,
+        sourcecode: :render_sourcecode,
+        table: :render_table,
+        figure: :render_figure,
+        quote: :render_quote,
+        formula: :render_formula,
+      }.freeze
+
+      # Minimal child set for simple blocks (admonition, note with content only)
+      SIMPLE_CHILDREN = {
+        paragraphs: :render_paragraph,
+      }.freeze
+
+      # Note-style child set (paragraphs + lists + dl, no nested blocks)
+      NOTE_CHILDREN = {
+        paragraphs: :render_paragraph,
+        ul: :render_unordered_list,
+        ol: :render_ordered_list,
+        dl: :render_definition_list,
+        quote: :render_quote,
+      }.freeze
+
+      # --- Section rendering ---
+
+      def render_basic_section(section, level: 1, **_opts)
+        attrs = element_attrs(id: safe_attr(section, :id))
+        tag("div", attrs) do
+          render_section_title(section, level)
+          section.blocks&.each { |block| render(block) }
+          section.notes&.each { |note| render_note(note) }
+        end
+      end
+
+      def render_hierarchical_section(section, level: 1, **_opts)
+        attrs = element_attrs(id: safe_attr(section, :id))
+        tag("div", attrs) do
+          render_section_title(section, level)
+          render_section_content(section, level)
+          section.subsections&.each { |sub| render(sub, level: level + 1) }
+        end
+      end
+
+      def render_content_section(section, level: 1, **_opts)
+        render_hierarchical_section(section, level: level, **_opts)
+      end
+
+      def render_section_title(section, level)
+        titles = section.title
+        return unless titles && !titles.empty?
+
+        h = "h#{[[level, 6].min, 1].max}"
+        title_text = extract_title_text(titles)
+        @output << "<#{h}>#{escape_html(title_text)}</#{h}>"
+      end
+
+      def render_section_content(section, _level)
+        section.blocks&.each { |block| render(block) }
+        section.notes&.each { |note| render_note(note) }
+      end
+
+      # --- Inline content rendering ---
+
+      # Walk element_order in document order, resolving each element to its
+      # Ruby object via the XML mapping, and yielding (element_order_entry, resolved_object)
+      # to the given block. Handles tab elements as nbsp. Skips elements not in the mapping.
+      #
+      # This is the single ordered-walk primitive used by all mixed content renderers:
+      # - render_mixed_inline (inline-only)
+      # - render_cell_content (mixed block/inline)
+      # - render_semx_content (filtered display attrs only)
+      def walk_ordered(node, allow_filter: nil)
+        return false unless node.is_a?(Lutaml::Model::Serializable)
+        return false unless node.element_order.is_a?(Array) && !node.element_order.empty?
+
+        xml_mapping = node.class.mappings_for(:xml, node.lutaml_register)
+        return false unless xml_mapping
+
+        element_to_attr = {}
+        xml_mapping.mapping_elements_hash.each_value do |rule_or_array|
+          Array(rule_or_array).each do |rule|
+            element_to_attr[rule.name] = rule.to
+            element_to_attr[rule.name.to_s] = rule.to if rule.name.is_a?(Symbol)
+          end
+        end
+
+        skip_indices = build_semx_skip_set(node)
 
-      # Inline rendering delegation
-      def walk_ordered(node, allow_filter: nil, &)
-        @inline_renderer.walk_ordered(node, allow_filter: allow_filter, &)
+        indices = Hash.new(0)
+
+        node.element_order.each_with_index do |el, i|
+          next if skip_indices.include?(i)
+
+          if el.text?
+            text = el.text_content
+            yield :text, text if text && block_given?
+          elsif el.element?
+            # Handle <tab/> elements
+            if el.name == "tab"
+              yield :tab, nil if block_given?
+              next
+            end
+
+            attr_name = element_to_attr[el.name]
+            next unless attr_name
+
+            # Apply optional filter (used by semx to skip semantic attrs)
+            next if allow_filter && !allow_filter.include?(attr_name)
+
+            coll = node.public_send(attr_name)
+            obj = if coll.is_a?(Array)
+                    idx = indices[attr_name]
+                    indices[attr_name] += 1
+                    coll[idx]
+                  else
+                    coll
+                  end
+            yield :element, obj if obj && block_given?
+          end
+        end
+        true
+      end
+
+      # In presentation XML, semantic elements are followed by <semx> wrappers
+      # or <fmt-*> display elements. Skip source elements to avoid duplicates.
+      def build_semx_skip_set(node)
+        skip_after = {
+          "link" => "semx",
+          "xref" => "semx",
+          "eref" => "semx",
+          "stem" => nil,
+          "concept" => "fmt-concept",
+          "refterm" => nil,
+          "renderterm" => nil,
+          "origin" => "semx",
+        }
+        skip = {}
+        node.element_order.each_with_index do |el, i|
+          next unless el.element?
+
+          next_tag = skip_after[el.name]
+          next unless next_tag
+
+          next_el = node.element_order[i + 1]
+          if next_tag.nil?
+            skip[i] = true
+          elsif next_el&.element? && next_el.name == next_tag
+            skip[i] = true
+          end
+        end
+        skip
+      end
+
+      # Table cells can contain both block-level content (p, ul, ol, dl)
+      # and inline content (text, em, strong, etc.) in document order.
+      def render_cell_content(cell)
+        walked = walk_ordered(cell) do |type, obj|
+          case type
+          when :text
+            @output << escape_html(obj)
+          when :tab
+            @output << "\u00a0\u00a0"
+          when :element
+            if block_element?(obj)
+              render(obj)
+            else
+              render_inline_element(obj)
+            end
+          end
+        end
+        unless walked
+          render_mixed_content_in_order(cell)
+        end
       end
 
       def render_mixed_inline(node)
-        @inline_renderer.render_mixed_inline(node)
+        # Models using map_all_content: raw XML in content
+        if raw_content_node?(node)
+          raw = node.content
+          if raw.is_a?(String) && !raw.strip.empty?
+            @output << render_raw_content(raw)
+            return
+          end
+        end
+
+        if node.is_a?(Lutaml::Model::Serializable) && node.element_order && !node.element_order.empty?
+          render_ordered_inline(node)
+        elsif node.is_a?(Lutaml::Model::Serializable)
+          node.each_mixed_content do |child|
+            case child
+            when String
+              @output << escape_html(child)
+            else
+              render_inline_element(child)
+            end
+          end
+        else
+          render_inline_collections(node)
+        end
       end
 
-      def render_cell_content(cell) = @inline_renderer.render_cell_content(cell)
-      def render_em(el) = @inline_renderer.render_em(el)
-      def render_strong(el) = @inline_renderer.render_strong(el)
-      def render_tt(el) = @inline_renderer.render_tt(el)
-      def render_sub(el) = @inline_renderer.render_sub(el)
-      def render_sup(el) = @inline_renderer.render_sup(el)
-      def render_small_caps(el) = @inline_renderer.render_small_caps(el)
-      def render_underline(el) = @inline_renderer.render_underline(el)
-      def render_strike(el) = @inline_renderer.render_strike(el)
-      def render_br(*) = @inline_renderer.render_br
-      def render_tab(*) = @inline_renderer.render_tab
-      def render_span(el) = @inline_renderer.render_span(el)
-      def render_fn_inline(el) = @inline_renderer.render_fn_inline(el)
-      def render_stem(el) = @inline_renderer.render_stem(el)
-      def render_semx_inline(el) = @inline_renderer.render_semx_inline(el)
-      def render_fmt_xref(el) = @inline_renderer.render_fmt_xref(el)
-      def render_comma(*) = @inline_renderer.render_comma
-      def render_math(el) = @inline_renderer.render_math(el)
-      def render_asciimath(el) = @inline_renderer.render_asciimath(el)
-      def render_index(el) = @inline_renderer.render_index(el)
-      def render_note_inline(el) = @inline_renderer.render_note_inline(el)
+      def raw_content_node?(node)
+        node.is_a?(Lutaml::Model::Serializable) &&
+          node.content.is_a?(String)
+      rescue NoMethodError
+        false
+      end
 
-      def render_semx_content(el,
-**)
-        @inline_renderer.render_semx_content(el, **)
+      # Iterate element_order directly, preserving whitespace text nodes
+      # that each_mixed_content drops (it skips text where text.strip.empty?)
+      def render_ordered_inline(node)
+        walked = walk_ordered(node) do |type, obj|
+          case type
+          when :text
+            @output << escape_html(obj)
+          when :tab
+            @output << "\u00a0\u00a0"
+          when :element
+            render_inline_element(obj)
+          end
+        end
+        unless walked
+          node.each_mixed_content do |child|
+            case child
+            when String
+              @output << escape_html(child)
+            else
+              render_inline_element(child)
+            end
+          end
+        end
       end
 
-      def render_stem_content(stem) = @inline_renderer.render_stem_content(stem)
-      def render_link(link) = @inline_renderer.render_link(link)
-      def render_xref(xref) = @inline_renderer.render_xref(xref)
-      def render_eref(eref) = @inline_renderer.render_eref(eref)
-      def render_fn(fn) = @inline_renderer.render_fn(fn)
-      def render_concept(concept) = @inline_renderer.render_concept(concept)
-      def render_fmt_stem(fmt_stem) = @inline_renderer.render_fmt_stem(fmt_stem)
-      def render_mixed_content_in_order(node) = @inline_renderer.render_mixed_content_in_order(node)
+      # Inline adapter methods for registry dispatch
+
+      def render_em(el)
+        render_inline_tag("em", el)
+      end
 
-      # Block rendering delegation
-      def render_paragraph(p,
-**)
-        @block_renderer.render_paragraph(p, **)
+      def render_strong(el)
+        render_inline_tag("strong", el)
       end
 
-      def render_table(table,
-**)
-        @block_renderer.render_table(table, **)
+      def render_tt(el)
+        render_inline_tag("tt", el)
       end
 
-      def render_unordered_list(ul,
-**)
-        @block_renderer.render_unordered_list(ul, **)
+      def render_sub(el)
+        render_inline_tag("sub", el)
       end
 
-      def render_ordered_list(ol,
-**)
-        @block_renderer.render_ordered_list(ol, **)
+      def render_sup(el)
+        render_inline_tag("sup", el)
       end
 
-      def render_definition_list(dl,
-**)
-        @block_renderer.render_definition_list(dl, **)
+      def render_small_caps(el)
+        render_inline_tag("span", el, class: "small-caps")
       end
 
-      def render_figure(figure,
-**)
-        @block_renderer.render_figure(figure, **)
+      def render_underline(el)
+        render_inline_tag("u", el)
       end
 
-      def render_image(image) = @block_renderer.render_image(image)
-      def render_video(video) = @block_renderer.render_video(video)
-      def render_audio(audio) = @block_renderer.render_audio(audio)
-      def render_note(note, **) = @block_renderer.render_note(note, **)
+      def render_strike(el)
+        render_inline_tag("s", el)
+      end
 
-      def render_example(example,
-**)
-        @block_renderer.render_example(example, **)
+      def render_br(*)
+        @output << "<br />"
       end
 
-      def render_sourcecode(sc,
-**)
-        @block_renderer.render_sourcecode(sc, **)
+      def render_tab(*)
+        @output << "\u00a0\u00a0"
       end
 
-      def render_formula(formula,
-**)
-        @block_renderer.render_formula(formula, **)
+      def render_span(el)
+        xml_class = safe_attr(el, :class_attr).to_s
+        html_class = html_class_for_span(xml_class) unless xml_class.empty?
+        attrs = element_attrs(style: safe_attr(el, :style), class: html_class)
+        tag("span", attrs) { render_mixed_inline(el) }
       end
 
-      def render_quote(quote,
-**)
-        @block_renderer.render_quote(quote, **)
+      def render_fn_inline(el)
+        render_fn(el)
       end
 
-      def render_admonition(admonition,
-**)
-        @block_renderer.render_admonition(admonition, **)
+      def render_stem(el)
+        @output << render_stem_content(el)
       end
 
-      def render_bookmark(bookmark,
-**)
-        @block_renderer.render_bookmark(bookmark, **)
+      def render_semx_inline(el)
+        render_semx_content(el)
       end
 
-      def render_block_children(model,
-children:)
-        @block_renderer.render_block_children(model, children: children)
+      def render_fmt_xref(el)
+        target = safe_attr(el, :target) || safe_attr(el, :to_attr)
+        if target
+          attrs = element_attrs(href: "##{escape_html(target)}", class: "xref")
+          tag("a", attrs) { render_mixed_inline(el) }
+        else
+          render_mixed_inline(el)
+        end
       end
 
-      def render_note_children(model) = @block_renderer.render_note_children(model)
-      def render_simple_children(model) = @block_renderer.render_simple_children(model)
-      def render_full_block_children(model) = @block_renderer.render_full_block_children(model)
+      def render_comma(*)
+        @output << ", "
+      end
 
-      # Section rendering delegation
-      def render_basic_section(section,
-**)
-        @section_renderer.render_basic_section(section, **)
+      def render_math(el)
+        @output << el.content.to_s
       end
 
-      def render_hierarchical_section(section,
-**)
-        @section_renderer.render_hierarchical_section(section, **)
+      def render_asciimath(el)
+        @output << %(<span class="stem">#{escape_html(Array(el.text).join)}</span>)
       end
 
-      def render_content_section(section,
-**)
-        @section_renderer.render_content_section(section, **)
+      def render_index(el)
+        collect_index_term(el)
+        ""
       end
 
-      def render_ordered_content(section,
-level = 1)
-        @section_renderer.render_ordered_content(section, level)
+      def render_note_inline(el)
+        render_note(el)
       end
 
-      def collect_ordered_children(section) = @section_renderer.collect_ordered_children(section)
-      def sort_by_displayorder(children) = @section_renderer.sort_by_displayorder(children)
+      def render_inline_collections(node)
+        texts = node.text
+        if texts.is_a?(Array)
+          texts.each do |t|
+            if t.is_a?(String)
+              @output << escape_html(t)
+            else
+              render_inline_element(t)
+            end
+          end
+        elsif texts.is_a?(String)
+          @output << escape_html(texts)
+        end
 
-      def render_preface(preface,
-**)
-        @section_renderer.render_preface(preface, **)
+        inline_attrs = %i[em strong smallcap sub sup tt underline strike
+                          xref eref link span stem concept fn br tab keyword
+                          fmt_annotation_start fmt_annotation_end
+                          fmt_stem fmt_fn_label fmt_concept
+                          bookmark image semx fmt_xref_label]
+        inline_attrs.each do |attr|
+          values = safe_attr(node, attr)
+          next if values.nil?
+
+          Array(values).each { |v| render_inline_element(v) }
+        end
       end
 
-      # Pubid rendering delegation
-      def parse_pubid(docidentifier_string) = @pubid_renderer.parse_pubid(docidentifier_string)
-      def pubid_to_html(identifier) = @pubid_renderer.pubid_to_html(identifier)
+      # Render SemxElement display content only, skipping semantic linkage.
+      # semx wraps both semantic data (origin, xref, source, etc.) and
+      # display content (fmt-xref, span, strong, etc.). Only render display.
+      def render_semx_content(element, **_opts)
+        display_attrs = %i[text fmt_xref fmt_link fmt_concept span strong em sup p semx
+                           asciimath math sub_child tt_child br_child tab_child
+                           stem_child figure_child formula_child sourcecode_child]
+        label_stripped = false
+
+        walked = walk_ordered(element,
+                              allow_filter: display_attrs) do |type, obj|
+          case type
+          when :text
+            text = obj
+            if !label_stripped
+              text = deduplicate_semx_text(text, @output)
+              label_stripped = true
+            end
+            @output << escape_html(text)
+          when :element
+            if obj.is_a?(Metanorma::Document::Components::Paragraphs::ParagraphBlock)
+              render_paragraph(obj)
+            else
+              render_inline_element(obj)
+            end
+          end
+        end
+
+        unless walked
+          display_attrs.each do |attr|
+            val = safe_attr(element, attr)
+            next if val.nil?
+
+            if val.is_a?(Array)
+              val.each do |v|
+                if v.is_a?(Metanorma::Document::Components::Paragraphs::ParagraphBlock)
+                  render_paragraph(v)
+                else
+                  render_inline_element(v)
+                end
+              end
+            elsif val.is_a?(String)
+              @output << escape_html(val)
+            else
+              render_inline_element(val)
+            end
+          end
+        end
+      end
+
+      def deduplicate_semx_text(semx_text, output)
+        first_word = semx_text[/\A\s*(\S+)/, 1]
+        return semx_text unless first_word
+
+        tail = output[-200..]
+        return semx_text unless tail&.rstrip&.end_with?(first_word)
+
+        semx_text.sub(/\A\s*#{Regexp.escape(first_word)}\s*/, "")
+      end
+
+      def render_inline_tag(tag_name, element, **extra_attrs)
+        tag(tag_name, element_attrs(**extra_attrs)) do
+          render_mixed_inline(element)
+        end
+      end
+
+      # Process raw XML content from map_all_content models.
+      # Strips source elements (xref, eref, stem) that have a following <semx>
+      # wrapper, keeping only the semx display content.
+      def render_raw_content(raw_xml)
+        doc = Nokogiri::XML.fragment(raw_xml)
+        # Convert fmt-link elements to HTML <a> tags before stripping wrappers
+        doc.css("fmt-link").each do |el|
+          target = el["target"] || el["href"]
+          if target
+            display_text = target.delete_prefix("mailto:")
+            a = doc.document.create_element("a", display_text, "href" => target)
+            el.replace(a)
+          else
+            el.replace(el.children)
+          end
+        end
+        # Remove source elements that precede a <semx> sibling,
+        # deduplicating any label text that appears in both the source
+        # paragraph and the semx display content.
+        doc.traverse do |node|
+          next unless node.element?
+          next unless %w[xref eref stem link].include?(node.name)
+
+          next_sib = node.next_sibling
+          while next_sib.is_a?(Nokogiri::XML::Text) && next_sib.text.strip.empty?
+            next_sib = next_sib.next_sibling
+          end
+          next unless next_sib&.element? && next_sib.name == "semx"
+
+          deduplicate_semx_label(node, next_sib)
+          node.remove
+        end
+        # Strip presentation wrappers, keeping inner content
+        %w[semx fmt-xref].each do |tag|
+          doc.css(tag).each { |el| el.replace(el.children) }
+        end
+        # Remap XML class names to HTML-specific class names
+        doc.css("[class]").each do |el|
+          el["class"] = el["class"].split(/\s+/).map do |c|
+            html_class_for_span(c)
+          end.join(" ")
+        end
+        doc.inner_html
+      end
+
+      def deduplicate_semx_label(source_node, semx_node)
+        first_text = semx_node.children.find do |c|
+          c.text? && !c.text.strip.empty?
+        end
+        return unless first_text
+
+        semx_prefix = first_text.text[/\A(\s*\S+)/, 1]
+        return unless semx_prefix && !semx_prefix.strip.empty?
+
+        prev = source_node.previous_sibling
+        return unless prev.is_a?(Nokogiri::XML::Text)
+
+        label = semx_prefix.strip
+        prev_text = prev.text.rstrip
+        return unless prev_text.end_with?(label)
+
+        prev.content = prev_text.sub(/#{Regexp.escape(label)}\s*\z/, "")
+        first_text.content = first_text.text.sub(
+          /\A\s*#{Regexp.escape(label)}\s*/, ""
+        )
+      end
+
+      def render_link(link)
+        target = safe_attr(link, :target) || safe_attr(link, :href)
+        attrs = element_attrs(href: target, id: safe_attr(link, :id))
+        tag("a", attrs) do
+          content = safe_attr(link, :content)
+          if content && !Array(content).join.strip.empty?
+            render_mixed_inline(link)
+          else
+            display_text = target.to_s.delete_prefix("mailto:")
+            @output << escape_html(display_text)
+          end
+        end
+      end
+
+      def render_xref(xref)
+        target = safe_attr(xref, :target) || safe_attr(xref, :to_attr)
+        attrs = element_attrs(href: "##{escape_html(target)}",
+                              id: safe_attr(xref,
+                                            :id))
+        tag("a", attrs) { render_mixed_inline(xref) }
+      end
+
+      def render_eref(eref)
+        citeas = safe_attr(eref, :citeas)
+        if citeas
+          @output << escape_html(citeas)
+        else
+          render_mixed_inline(eref)
+        end
+      end
+
+      def render_fn(fn)
+        fn_id = safe_attr(fn, :id)
+        number = @footnote_collector.register(fn)
+
+        attrs = element_attrs(id: fn_id, class: "fn-marker")
+        tag("span", attrs) do
+          label = safe_attr(fn, :fn_label) || safe_attr(fn, :reference)
+          if label
+            @output << "<sup><a href=\"##{escape_html("footnote-#{number}")}\" " \
+                       "class=\"fn-link\" id=\"#{escape_html("fnref-#{number}")}\">" \
+                       "#{escape_html(label.to_s)}</a></sup>"
+          end
+        end
+      end
+
+      def render_concept(concept)
+        render_mixed_inline(concept)
+      end
+
+      # --- Stem/math rendering ---
+
+      def render_fmt_stem(fmt_stem)
+        semx_items = Array(fmt_stem.semx)
+        return if semx_items.empty?
+
+        semx = semx_items.first
+        math_items = Array(semx.math)
+        ascii_items = Array(semx.asciimath)
+
+        # Collect source formats for interactive copy dropdown
+        source_formats = {}
+        if ascii_items.any?
+          ascii_text = ascii_items.map { |a| a.text.to_s.strip }.join
+          source_formats["asciimath"] = ascii_text unless ascii_text.empty?
+        end
+
+        data_attrs = ""
+        unless source_formats.empty?
+          data_attrs = " data-stem-formats='#{escape_html(source_formats.to_json)}'"
+        end
+
+        if math_items.any?
+          content = math_items.map { |m| m.content.to_s }.join
+          unless content.empty?
+            @output << "<span class=\"math-container\"#{data_attrs}>"
+            @output << "<math xmlns=\"http://www.w3.org/1998/Math/MathML\">#{content}</math>"
+            @output << "</span>"
+          end
+        elsif ascii_items.any?
+          # No MathML — render asciimath as fallback
+          text = ascii_items.map { |a| a.text.to_s.strip }.join
+          @output << "<span class=\"stem\"#{data_attrs}>#{escape_html(text)}</span>"
+        end
+      end
+
+      def render_stem_content(stem)
+        return "" if stem.nil?
+
+        # StemInlineElement — source element, skip (rendered via FmtStemElement)
+        if stem.is_a?(Metanorma::Document::Components::Inline::StemInlineElement)
+          return ""
+        end
+
+        # FmtStemElement — already handled by render_fmt_stem
+        if stem.is_a?(Metanorma::Document::Components::Inline::FmtStemElement)
+          return ""
+        end
+
+        # TextElements::StemElement — block math (no fmt- counterpart for display formulas)
+        if stem.is_a?(Metanorma::Document::Components::TextElements::StemElement)
+          if stem.math
+            math_val = stem.math
+            return math_val.to_xml if math_val.is_a?(Nokogiri::XML::Node)
+            return math_val.to_xml if defined?(Moxml::Document) && math_val.is_a?(Moxml::Document)
+
+            math_items = Array(math_val)
+            math_items.join
+          elsif stem.asciimath
+            text = extract_text_value(stem.asciimath)
+            return %(<span class="stem">#{escape_html(text)}</span>)
+          end
+          if stem.latexmath
+            text = extract_text_value(stem.latexmath)
+            return %(<span class="stem">#{escape_html(text)}</span>)
+          end
+        end
+
+        text = extract_text_value(stem)
+        text.empty? ? "" : %(<span class="stem">#{escape_html(text)}</span>)
+      end
 
       # --- Helper methods ---
 
+      def tag(name, attrs_str)
+        @output << "<#{name}#{attrs_str}>"
+        yield
+        @output << "</#{name}>"
+      end
+
       def element_attrs(**attrs)
         parts = []
         attrs.each do |k, v|
@@ -907,6 +1644,7 @@ level = 1)
       end
 
       def extract_block_label(block, default)
+        # Presentation XML puts label in <name> child element
         names = safe_attr(block, :name)
         if names && !names.empty?
           name = names.is_a?(Array) ? names.first : names
@@ -914,6 +1652,7 @@ level = 1)
           return text unless text.to_s.strip.empty?
         end
 
+        # Fallback: autonum XML attribute
         autonum = safe_attr(block, :autonum)
         if autonum && !autonum.to_s.empty?
           number = autonum.to_s
@@ -930,10 +1669,9 @@ level = 1)
       end
 
       def extract_title_text(titles)
-        return "" if titles.nil?
-        return extract_text_value(titles).to_s unless titles.is_a?(Array)
-        return "" if titles.empty?
+        return "" if titles.nil? || titles.empty?
 
+        titles = Array(titles)
         title = titles.first
         extract_text_value(title).to_s
       end
@@ -971,20 +1709,29 @@ level = 1)
       end
 
       def render_footnotes_section
-        return nil if @footnote_collector.empty?
+        return if @footnote_collector.empty?
 
         drops = @footnote_collector.to_a.map do |entry|
           content_html = ""
           if entry.content && !entry.content.empty?
-            content_html = Array(entry.content).filter_map do |p|
-              render_paragraph(p)
-            end.join
+            content_html = capture_output do
+              Array(entry.content).each { |p| render_paragraph(p) }
+            end
           end
           Drops::FootnoteDrop.new(entry, content_html)
         end
 
-        render_liquid("_footnotes.html.liquid",
-                      { "footnotes" => drops })
+        @output << render_liquid("_footnotes.html.liquid",
+                                 { "footnotes" => drops })
+      end
+
+      def capture_output
+        old_output = @output
+        @output = +""
+        yield
+        result = @output
+        @output = old_output
+        result
       end
     end
   end