markbridge 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e077560817f865c035c136edffd868cbabb934b6a8986614c5e1c48139b05b9b
-  data.tar.gz: 6511b321b0245010d0df81cea6e5b19950de430753a34aea54f4c99c2fa10fc9
+  metadata.gz: 6d958f4d4c04108de2f92388f6a62ac37ab126700f535af2c6cf38f832928e20
+  data.tar.gz: 86510bc530a71fefb9f30e350a7800d159dd9e5fa77231f2f6259253373c11b4
 SHA512:
-  metadata.gz: 7e807c4b7fc8eae29bbcfea9fa6c855f2b627caf2403965e5e0e4d1792a39612e74db2a37e85be72e60f2b3a9e200a70cedf695ed57256e27c03b2569bc9ba26
-  data.tar.gz: 77f38f9577c366005a6b06c25a6287b3631d8d2f4dbcfe54043a0c882587600f95c94f10e4110356573f72a1041e6e7ab0b05fc40bbf9d353258ee7a5dc1fc24
+  metadata.gz: 828a0d60a75ac730dd882e7825e2ea2e0fec53ca6b2efea6329cac03030157fba4ea086118476445ea9505835ab28031221ed786be526bdfb1b2340e2c570c56
+  data.tar.gz: 3df501c15e4050edcbd2225d356440e4672d30a5feb8d85a3b225af0daa4cd66f09f743044ac41b7e75b01a8378951aceac7784078833facb4d42cefcfc3aa24

data/lib/markbridge/ast/code.rb

@@ -15,12 +15,19 @@ module Markbridge
       # @return [String, nil] the programming language for syntax highlighting
       attr_reader :language
 
+      # @return [Boolean, nil] +true+ forces a fenced block; anything else
+      #   leaves the block-or-inline decision to the renderer
+      attr_reader :block
+
       # Create a new code element.
       #
       # @param language [String, nil] optional language identifier for syntax highlighting
-      def initialize(language: nil)
+      # @param block [Boolean, nil] +true+ when the source construct is a code
+      #   block by definition (e.g. +<pre>+), even with single-line content
+      def initialize(language: nil, block: nil)
         super()
         @language = language
+        @block = block
       end
     end
   end

data/lib/markbridge/ast/node.rb

@@ -14,6 +14,47 @@ module Markbridge
     #
     # @abstract Subclass and add specific behavior
     class Node
+      # Registry of every class that inherits from {Node}, direct or not.
+      # This is boot-time state: the built-in classes land here while the
+      # gem's requires run, and a consumer subclass is appended when its
+      # class body runs. Anything built from this list at freeze time
+      # (see +TagLibrary#freeze+ and +RuleSet#freeze+) covers only the
+      # classes defined up to that point; later classes go through the
+      # lazy ancestry lookups instead.
+      DESCENDANTS = []
+
+      # No +super+ on purpose: +Class#inherited+ is a no-op, so calling
+      # it adds nothing observable (verified by mutation testing).
+      # @param subclass [Class]
+      def self.inherited(subclass)
+        DESCENDANTS << subclass
+      end
+
+      # @return [Array<Class>] every known descendant class, in definition
+      #   order (see {DESCENDANTS} — boot-time state)
+      def self.descendants
+        DESCENDANTS
+      end
+
+      # The class chain from this class up to {Node}, most specific class
+      # first. Cached on the class: the chain is pure class structure and
+      # can never change once the class is defined, so one array per class
+      # serves the whole process. The normalizer and the tag library use
+      # it for ancestry matching.
+      #
+      # @return [Array<Class>] frozen, e.g. +[Bold, Element, Node]+
+      def self.ast_chain
+        @ast_chain ||=
+          begin
+            chain = [self]
+            sup = superclass
+            while sup <= Node
+              chain << sup
+              sup = sup.superclass
+            end
+            chain.freeze
+          end
+      end
     end
   end
 end

data/lib/markbridge/normalizer/rule_set.rb

@@ -4,18 +4,35 @@ module Markbridge
   class Normalizer
     # Maps a node and its ancestor stack to a strategy.
     #
-    # Matching is exact-class (equivalent to +instance_of?+): rules are
-    # keyed by +Class+ and looked up via +node.class+, so an anonymous
-    # +Class.new(AST::Element)+ or any future subclass never accidentally
-    # matches a rule written for the base class. Registering a rule for a
-    # +(parent, child)+ pair that already has one replaces it, so later
-    # layers (Discourse, a consumer's +#rule+) override earlier ones.
+    # Rules are keyed by +Class+ on both sides, and matching follows the
+    # class ancestry: a rule registered for a base class also applies to
+    # its subclasses, for the parent and for the child. Only classes
+    # inside the +AST::Node+ hierarchy take part; the walk never reaches
+    # +Object+, so a rule keyed on a class outside the AST never matches.
+    #
+    # Precedence, in this order:
+    # 1. Stack position — the outermost ancestor in the stack with any
+    #    matching rule wins.
+    # 2. Child class specificity — at that ancestor, a rule keyed on the
+    #    node's own class beats a rule keyed on a superclass.
+    # 3. Parent class specificity — then a rule keyed on the ancestor's
+    #    own class beats a rule keyed on a superclass.
+    #
+    # A rule registered for the exact +(parent, child)+ pair therefore
+    # always overrides an inherited one. Registering a rule for a pair
+    # that already has one replaces it, so later layers (Discourse, a
+    # consumer's +#rule+) override earlier ones.
     class RuleSet
       NO_MATCH = [nil, nil].freeze
 
+      # Shared "no rule targets this class" marker, so the cache entry for
+      # a rule-less class costs no allocation.
+      EMPTY_CANDIDATES = [].freeze
+
       def initialize
         @by_parent = {} # parent_class => { child_class => strategy }
         @child_classes = Set.new
+        # @candidates_cache stays unset (nil) until #freeze fills it.
       end
 
       # Register (or replace) a rule.
@@ -33,20 +50,35 @@ module Markbridge
 
       # Resolve the strategy for +child+ given its ancestor stack (root
       # first). Returns +[strategy, boundary]+ where +boundary+ is the
-      # *outermost* ancestor whose class has a rule for +child+'s class, or
+      # *outermost* ancestor with a rule that matches +child+'s class, or
       # {NO_MATCH} (+[nil, nil]+) when nothing matches.
       #
+      # +walk_cache+ caches the child-rule candidates per class. The caller owns
+      # it and should reuse one Hash for a whole tree walk, so each
+      # distinct class is analyzed at most once per walk. Keeping the
+      # cache outside the RuleSet leaves a frozen shared instance free of
+      # per-call state. The cache read is a single Hash lookup because this
+      # method runs for every node in the tree.
+      #
       # @param child [AST::Node]
       # @param ancestors [Array<AST::Element>] root-first ancestor stack
+      # @param walk_cache [Hash{Class => Array<Class>}] per-walk cache owned by
+      #   the caller
       # @return [Array(Object, AST::Element), Array(nil, nil)]
-      def resolve(child, ancestors)
-        child_class = child.class
+      def resolve(child, ancestors, walk_cache)
+        klass = child.class
+        # A frozen rule set carries a prebuilt candidates cache (see
+        # #freeze); the walk cache is only needed for classes defined after the
+        # freeze and for mutable rule sets.
+        frozen_cache = @candidates_cache
+        candidates =
+          (frozen_cache && frozen_cache[klass]) || (walk_cache[klass] ||= child_candidates(klass))
         # Skip the ancestor scan for a class no rule targets (most nodes, for
         # example plain text). The scan below returns the same result for such
         # a class, so this only saves work.
-        return NO_MATCH unless @child_classes.include?(child_class)
+        return NO_MATCH if candidates.empty?
 
-        scan_ancestors(child_class, ancestors)
+        scan_ancestors(candidates, ancestors)
       end
 
       # Freeze so a shared instance raises if something tries to change it.
@@ -54,7 +86,19 @@ module Markbridge
       # there before it touches +@child_classes+, so a frozen instance raises
       # on the +@by_parent+ write first. +@child_classes+ is never reached, so
       # it does not need freezing.
+      #
+      # Freezing also precomputes the child-rule candidates for every AST
+      # class known at this point (+AST::Node.descendants+ is boot-time
+      # state), so {#resolve} on a frozen rule set answers with one Hash
+      # lookup instead of going through the per-walk cache. The rules can
+      # not change anymore, so the cache can never go stale; classes
+      # defined after the freeze fall back to the walk cache. The +||=+ keeps a
+      # second freeze from writing to the then-frozen instance. Like
+      # +@child_classes+, the cache Hash stays unfrozen — nothing writes
+      # to it after this point.
       def freeze
+        @candidates_cache ||=
+          AST::Node.descendants.to_h { |klass| [klass, child_candidates(klass)] }
         @by_parent.each_value(&:freeze)
         @by_parent.freeze
         super
@@ -62,20 +106,50 @@ module Markbridge
 
       private
 
-      # The ancestor scan behind {#resolve}: the outermost matching ancestor
-      # wins. It is split from the skip check in {#resolve} so the scan can be
-      # tested on its own.
-      def scan_ancestors(child_class, ancestors)
+      # The ancestor scan behind {#resolve}: the outermost ancestor with any
+      # matching rule wins (precedence 1). {#best_rule} applies the class
+      # specificity order within one ancestor.
+      def scan_ancestors(candidates, ancestors)
         ancestors.each do |ancestor|
-          strategies = @by_parent[ancestor.class]
-          next unless strategies
-
-          strategy = strategies[child_class]
+          strategy = best_rule(candidates, ancestor.class)
           return strategy, ancestor if strategy
         end
         NO_MATCH
       end
 
+      # The most specific rule at one ancestor: try each child candidate
+      # (the node's own class first — precedence 2), and for each walk the
+      # ancestor's class chain inside the AST (its own class first —
+      # precedence 3). An ancestor whose class is outside the AST has no
+      # chain and can never match. (+Module#<=+ is nil for an unrelated
+      # class, so the ternary — not an inverted guard — is the correct
+      # check here.)
+      def best_rule(candidates, ancestor_class)
+        chain = ancestor_class <= AST::Node ? ancestor_class.ast_chain : EMPTY_CANDIDATES
+        candidates.each do |child_class|
+          chain.each do |parent_class|
+            strategies = @by_parent[parent_class]
+            strategy = strategies[child_class] if strategies
+            return strategy if strategy
+          end
+        end
+        nil
+      end
+
+      # The classes in +klass+'s AST chain that at least one rule targets
+      # as a child, most specific class first (empty for most classes). A
+      # fresh walk cache sees every class once per document, so this allocates
+      # nothing unless there is a match. A class outside the AST has no
+      # chain and no candidates (+Module#<=+ is nil for an unrelated
+      # class, so the ternary — not an inverted guard — is the correct
+      # check here).
+      def child_candidates(klass)
+        chain = klass <= AST::Node ? klass.ast_chain : EMPTY_CANDIDATES
+        candidates = nil
+        chain.each { |current| (candidates ||= []) << current if @child_classes.include?(current) }
+        candidates || EMPTY_CANDIDATES
+      end
+
       def validate_strategy!(strategy)
         return if strategy.respond_to?(:call)
         return if STRATEGIES.include?(strategy)

data/lib/markbridge/normalizer/walker.rb

@@ -50,6 +50,11 @@ module Markbridge
       def initialize(rule_set, report)
         @rules = rule_set
         @report = report
+        # Per-run cache for RuleSet#resolve's ancestry analysis. A Walker
+        # lives for one normalize call, so each distinct node class is
+        # analyzed at most once per run while the RuleSet itself stays
+        # free of per-call state.
+        @walk_cache = {}
       end
 
       # Normalize +document+'s subtree in place.
@@ -94,7 +99,7 @@ module Markbridge
         bubble = nil
 
         children.each_with_index do |child, index|
-          strategy, boundary = @rules.resolve(child, stack)
+          strategy, boundary = @rules.resolve(child, stack, @walk_cache)
           strategy = strategy.call(boundary, child) if strategy.respond_to?(:call)
 
           if strategy.nil? || strategy == :keep
@@ -129,7 +134,7 @@ module Markbridge
       # +out+ — the shared entry point used by {#emit}'s +:unwrap+ recursion,
       # where +out+ already exists.
       def resolve_into(child, stack, out, bubble)
-        strategy, boundary = @rules.resolve(child, stack)
+        strategy, boundary = @rules.resolve(child, stack, @walk_cache)
         strategy = strategy.call(boundary, child) if strategy.respond_to?(:call)
 
         if strategy.nil? || strategy == :keep

data/lib/markbridge/normalizer.rb

@@ -48,8 +48,9 @@ module Markbridge
 
     # AST nodes the Discourse renderer prints as block-level Markdown (their
     # output has blank lines around it). One inside an inline container breaks
-    # that container, so it is moved out. Spoiler and single-line Code stay
-    # inline and are not listed (Code is handled by {KEEP_INLINE_CODE}).
+    # that container, so it is moved out. Spoiler and single-line Code without
+    # a forced +block+ flag stay inline and are not listed (Code is handled by
+    # {KEEP_INLINE_CODE}).
     BLOCK_NODES = [
       AST::Quote,
       AST::Heading,
@@ -68,11 +69,14 @@ module Markbridge
 
     # A code span may stay inside an inline container while it is on one line.
     # A fenced or multi-line block is moved out. This matches
-    # +RenderingInterface#block_context?+: Code prints as a fenced block when a
-    # Text child has a newline (the language alone does not make it a block).
+    # +RenderingInterface#block_context?+: Code prints as a fenced block when
+    # its +block+ flag is set or a Text child has a newline (the language alone
+    # does not make it a block).
     KEEP_INLINE_CODE =
       lambda do |_boundary, node|
-        block = node.children.any? { |c| c.instance_of?(AST::Text) && c.text.include?("\n") }
+        block =
+          node.block ||
+            node.children.any? { |c| c.instance_of?(AST::Text) && c.text.include?("\n") }
         block ? :hoist_after : :keep
       end
 
@@ -150,7 +154,10 @@ module Markbridge
     # @return [Array<Hash>] +{parent:, child:, strategy:}+ per occurrence
     def violations(ast)
       found = []
-      collect_violations(ast, EMPTY_STACK, found)
+      # Per-call cache for RuleSet#resolve's ancestry analysis; keeps the
+      # Normalizer instance itself free of state, so a frozen shared
+      # instance stays safe across threads.
+      collect_violations(ast, EMPTY_STACK, found, {})
       found
     end
 
@@ -161,15 +168,15 @@ module Markbridge
 
     private
 
-    def collect_violations(element, ancestors, found)
+    def collect_violations(element, ancestors, found, walk_cache)
       stack = ancestors + [element]
       element.children.each do |child|
-        strategy, boundary = @rules.resolve(child, stack)
+        strategy, boundary = @rules.resolve(child, stack, walk_cache)
         strategy = strategy.call(boundary, child) if strategy.respond_to?(:call)
         unless strategy.nil? || strategy == :keep
           found << { parent: demodulize(boundary.class), child: demodulize(child.class), strategy: }
         end
-        collect_violations(child, stack, found) if child.is_a?(AST::Element)
+        collect_violations(child, stack, found, walk_cache) if child.is_a?(AST::Element)
       end
     end
 

data/lib/markbridge/parsers/bbcode/handlers/code_handler.rb

@@ -11,9 +11,26 @@ module Markbridge
         #   # end
         #   # [/code]
         class CodeHandler < RawHandler
+          # Tags that mean a code block by definition; [tt] is inline
+          # teletype and leaves the decision to the renderer.
+          BLOCK_TAGS = %w[code pre].freeze
+          private_constant :BLOCK_TAGS
+
           def initialize
             super(AST::Code)
           end
+
+          private
+
+          def create_element(token:, content:)
+            element =
+              AST::Code.new(
+                language: token.attrs[:lang] || token.attrs[:option],
+                block: (true if BLOCK_TAGS.include?(token.tag)),
+              )
+            element << AST::Text.new(content) unless content.empty?
+            element
+          end
         end
       end
     end

data/lib/markbridge/parsers/html/handler_registry.rb

@@ -132,6 +132,7 @@ module Markbridge
             registry.register("a", Handlers::UrlHandler.new)
             registry.register("img", Handlers::ImageHandler.new)
             registry.register("blockquote", Handlers::QuoteHandler.new)
+            registry.register(%w[h1 h2 h3 h4 h5 h6], Handlers::HeadingHandler.new)
             registry.register("br", Handlers::SelfClosingHandler.new(AST::LineBreak))
             registry.register("hr", Handlers::SelfClosingHandler.new(AST::HorizontalRule))
             registry.register(%w[ul ol], Handlers::ListHandler.new)

data/lib/markbridge/parsers/html/handlers/heading_handler.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handles <h1> through <h6> by creating a Heading element with the
+        # matching level and processing children into it.
+        class HeadingHandler < BaseHandler
+          # @param element [Nokogiri::XML::Element] the heading element
+          # @param parent [AST::Element] the parent AST node
+          # @return [AST::Heading] the created heading, so children get processed into it
+          def process(element:, parent:)
+            level = element.name.delete_prefix("h").to_i.clamp(1, 6)
+            heading = AST::Heading.new(level:)
+            parent << heading
+
+            heading
+          end
+
+          # @return [Class] AST::Heading
+          def element_class
+            AST::Heading
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/html/handlers/raw_handler.rb

@@ -6,6 +6,12 @@ module Markbridge
       module Handlers
         # Handler for raw/preformatted tags that preserve content as-is
         class RawHandler < BaseHandler
+          # A language must be one clean token — the renderer splices it
+          # into the code fence line, so a class attribute with spaces or
+          # other markup characters must not end up there.
+          LANGUAGE_PATTERN = /\A[a-z0-9][a-z0-9_+-]*\z/
+          private_constant :LANGUAGE_PATTERN
+
           def initialize(element_class)
             @element_class = element_class
           end
@@ -14,10 +20,8 @@ module Markbridge
             # Get the inner text content
             content = element.inner_text
 
-            # Extract language from class or lang attribute
-            language = element["class"] || element["lang"]
-
-            ast_element = @element_class.new(language:)
+            ast_element =
+              @element_class.new(language: language_for(element), block: block_for(element))
             ast_element << AST::Text.new(content) unless content.empty?
             parent << ast_element
 
@@ -26,6 +30,53 @@ module Markbridge
           end
 
           attr_reader :element_class
+
+          private
+
+          # <pre> is a block by definition, so its content keeps the fenced
+          # form even on one line; <code> and <tt> leave the decision to the
+          # renderer's newline check.
+          #
+          # @param element [Nokogiri::XML::Element]
+          # @return [Boolean, nil]
+          def block_for(element)
+            true if element.name == "pre"
+          end
+
+          # The language of a code block, from the strongest signal to the
+          # weakest: a `language-*` class on the element itself or on its
+          # direct <code> child (the CommonMark convention for fenced code,
+          # `<pre><code class="language-ruby">`), then the `lang` attribute,
+          # then a lone class used as-is. A lone class ranks below `lang`
+          # because a class can be pure styling (`hljs`, `prettyprint`).
+          def language_for(element)
+            code_child_classes = element.at_xpath("./code")&.[]("class")
+
+            prefixed_language(element["class"]) || prefixed_language(code_child_classes) ||
+              attribute_language(element["lang"]) || single_class_language(element["class"]) ||
+              single_class_language(code_child_classes)
+          end
+
+          def prefixed_language(classes)
+            classes
+              &.split
+              &.filter_map do |name|
+                name.delete_prefix("language-").downcase if name.start_with?("language-")
+              end
+              &.find { |language| LANGUAGE_PATTERN.match?(language) }
+          end
+
+          def attribute_language(value)
+            language = value&.strip&.downcase
+            language if language&.match?(LANGUAGE_PATTERN)
+          end
+
+          def single_class_language(classes)
+            names = classes&.split
+            return unless names&.length == 1
+
+            attribute_language(names.first)
+          end
         end
       end
     end

data/lib/markbridge/parsers/html.rb

@@ -17,6 +17,7 @@ require_relative "html/handlers/image_handler"
 require_relative "html/handlers/list_handler"
 require_relative "html/handlers/list_item_handler"
 require_relative "html/handlers/quote_handler"
+require_relative "html/handlers/heading_handler"
 require_relative "html/handlers/paragraph_handler"
 require_relative "html/handlers/table_handler"
 require_relative "html/handlers/table_row_handler"

data/lib/markbridge/parsers/media_wiki/parser.rb

@@ -347,7 +347,7 @@ module Markbridge
           consumed = lines[start_index..].take_while { |line| line.start_with?(" ") }
           content = consumed.map { |line| line[1..] }.join("\n")
 
-          code = AST::Code.new
+          code = AST::Code.new(block: true)
           code << AST::Text.new(content)
           @document << code
 
@@ -372,7 +372,7 @@ module Markbridge
           combined = consumed.join("\n")
           content = combined.sub(PRE_TAG_OPEN, "").sub(PRE_TAG_CLOSE_TRAILING, "")
 
-          code = AST::Code.new
+          code = AST::Code.new(block: true)
           code << AST::Text.new(content)
           @document << code
 

data/lib/markbridge/parsers/text_formatter/handlers/code_handler.rb

@@ -13,7 +13,9 @@ module Markbridge
           def process(element:, parent:, processor: nil)
             attrs = extract_attributes(element)
             lang = attrs[:lang] || attrs[:language]
-            node = AST::Code.new(language: lang)
+            # s9e CODE is always a block, so the flag keeps the fenced form
+            # even for single-line content.
+            node = AST::Code.new(language: lang, block: true)
             parent << node
 
             # Return node to signal: process children into this node

data/lib/markbridge/renderers/discourse/html_block_safety.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Renderers
+    module Discourse
+      # Decides whether a rendered fragment is safe to splice into a
+      # CommonMark HTML block (spec §4.6). Inside such a block the
+      # content passes through as raw HTML; Markdown is only parsed
+      # again across blank lines. Safe output is therefore: a raw HTML
+      # or plain-text fragment without Markdown sigils, or a
+      # +\n\n…\n\n+ wrap — a deliberate Markdown island.
+      #
+      # Used by the html_mode contract check that ships in
+      # +markbridge/rspec+ and by this repo's own contract spec.
+      module HtmlBlockSafety
+        # Markdown sigils that would surface as literal text inside an
+        # HTML block: emphasis (`*`, `_`, `~`) and link middles (`](`).
+        MARKDOWN_SIGILS = /[*_~]|\]\(/
+        private_constant :MARKDOWN_SIGILS
+
+        # @param output [String] a tag's html_mode render result
+        # @return [Boolean]
+        def self.safe?(output)
+          return true if output.start_with?("\n\n") && output.end_with?("\n\n")
+
+          !output.match?(MARKDOWN_SIGILS)
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/renderers/discourse/renderer.rb

@@ -12,8 +12,9 @@ module Markbridge
           @escaper = escaper || MarkdownEscaper.new
           @html_escaper = html_escaper || HtmlEscaper
           @postprocessor = postprocessor || Postprocessor::DEFAULT
-          # @interface_cache is lazily initialized in #render's top-level
-          # call and reset to nil after the call completes.
+          # @interface_cache, @resolved_tags, and @resolved_default_tags
+          # are lazily initialized during a top-level #render /
+          # #render_default call and reset to nil after the call completes.
         end
 
         # Render a node to Markdown
@@ -28,7 +29,10 @@ module Markbridge
           root_call = @interface_cache.nil?
           @interface_cache = {} if root_call
 
-          tag = @tag_library[node.class]
+          # Exact-class hit first (a single Hash lookup, the common case),
+          # then the memoized ancestry fallback so a subclass without its
+          # own tag renders through its nearest ancestor's tag.
+          tag = @tag_library[node.class] || resolved_tag(node.class)
           if tag
             result = tag.render(node, interface_for(context))
             unless result.is_a?(String)
@@ -43,7 +47,11 @@ module Markbridge
 
           render_without_tag(node, context)
         ensure
-          @interface_cache = nil if root_call
+          if root_call
+            @interface_cache = nil
+            @resolved_tags = nil
+            @resolved_default_tags = nil
+          end
         end
 
         # Render a node with the stock tag for its class, ignoring any
@@ -66,12 +74,16 @@ module Markbridge
           root_call = @interface_cache.nil?
           @interface_cache = {} if root_call
 
-          tag = default_tag_library[node.class]
+          tag = default_tag_library[node.class] || resolved_default_tag(node.class)
           return tag.render(node, interface_for(context)) if tag
 
           render_without_tag(node, context)
         ensure
-          @interface_cache = nil if root_call
+          if root_call
+            @interface_cache = nil
+            @resolved_tags = nil
+            @resolved_default_tags = nil
+          end
         end
 
         # Render all children of a node
@@ -113,6 +125,24 @@ module Markbridge
           @interface_cache[context.object_id] ||= RenderingInterface.new(self, context)
         end
 
+        # Ancestry fallback for tag dispatch (see TagLibrary#resolve),
+        # memoized per top-level render call — the tag library can change
+        # between calls, so the cache must not outlive one call (it is
+        # reset in #render's ensure). +fetch+ stores nil results too, so a
+        # class that resolves to no tag is walked once per call, not once
+        # per node.
+        def resolved_tag(node_class)
+          cache = @resolved_tags ||= {}
+          cache.fetch(node_class) { cache[node_class] = @tag_library.resolve(node_class) }
+        end
+
+        # Same as {#resolved_tag}, against the default library backing
+        # #render_default.
+        def resolved_default_tag(node_class)
+          cache = @resolved_default_tags ||= {}
+          cache.fetch(node_class) { cache[node_class] = default_tag_library.resolve(node_class) }
+        end
+
         # Pristine default library backing #render_default. Built lazily —
         # most renders never need it.
         def default_tag_library

data/lib/markbridge/renderers/discourse/rendering_interface.rb

@@ -65,6 +65,10 @@ module Markbridge
         def block_context?(node)
           # Check if it's a block-level element type (but not code, which can be inline)
           return true if node.instance_of?(AST::List) || node.instance_of?(AST::HorizontalRule)
+          # A Code node whose source construct is a block by definition keeps
+          # its block form even with single-line content (is_a?, so Code
+          # subclasses inherit the behavior).
+          return true if node.is_a?(AST::Code) && node.block
           return false unless node.is_a?(AST::Element)
 
           # Check if content has newlines

data/lib/markbridge/renderers/discourse/tag.rb

@@ -36,6 +36,16 @@ module Markbridge
             raise NotImplementedError, "#{self.class} must implement #render or provide a block"
           end
         end
+
+        # A tag that renders only the element's children, with the element
+        # pushed on the parent chain. Tag dispatch matches by ancestry, so
+        # a subclass normally inherits its base class tag; register
+        # PASSTHROUGH for the subclass to opt out — the exact-class hit
+        # wins and the base tag is not used.
+        PASSTHROUGH =
+          new do |element, interface|
+            interface.render_children(element, context: interface.with_parent(element))
+          end.freeze
       end
     end
   end

data/lib/markbridge/renderers/discourse/tag_library.rb

@@ -15,9 +15,17 @@ module Markbridge
         # internal +@tags+ Hash is independent of the source. Without
         # this, both copies would share the same underlying Hash and
         # mutations to one would silently affect the other.
+        #
+        # A frozen source also carries flattened ancestry entries (see
+        # {#freeze}); the copy is mutable again, so those entries are
+        # dropped and the copy goes back to the lazy {#resolve} lookup.
+        # Keeping them would bake in inheritance decisions from before
+        # any changes made to the copy.
         def initialize_copy(other)
           super
           @tags = @tags.dup
+          @flattened_classes&.each { |klass| @tags.delete(klass) }
+          @flattened_classes = nil
         end
 
         # Register a tag for an element class
@@ -28,9 +36,11 @@ module Markbridge
           self
         end
 
-        # Remove a tag binding so the renderer falls through to
-        # +render_children+ for that element class. See
-        # +Renderer#render+ for the auto-passthrough path.
+        # Remove the binding for this exact element class. Lookup then
+        # falls back to the nearest ancestor class with a tag; when no
+        # ancestor has one — true for every built-in class, since
+        # nothing binds +AST::Element+ or +AST::Node+ — the renderer
+        # falls through to +render_children+. See +Renderer#render+.
         #
         # @param element_class [Class]
         # @return [self]
@@ -41,7 +51,7 @@ module Markbridge
 
         # Merge a Hash of class → Tag mappings on top of this library
         # in-place. A +nil+ value unregisters the corresponding class
-        # (so the default auto-passthrough kicks in).
+        # (see {#unregister} for what lookup does then).
         #
         # Named with a trailing +!+ because it mutates +self+ —
         # mirroring Ruby's Hash#merge / Hash#merge! convention. Use
@@ -67,6 +77,26 @@ module Markbridge
           @tags[element_class]
         end
 
+        # Find the tag for +element_class+ through its ancestry: walk the
+        # superclass chain, starting at +element_class.superclass+, and
+        # return the first registered tag. The walk stays inside the
+        # +AST::Node+ hierarchy, so a tag registered for a class outside
+        # the AST is never found. The exact-class lookup is {#[]};
+        # callers check that first.
+        #
+        # @param element_class [Class]
+        # @return [Tag, nil]
+        def resolve(element_class)
+          klass = element_class.superclass
+          while klass && klass <= AST::Node
+            tag = self[klass]
+            return tag if tag
+
+            klass = klass.superclass
+          end
+          # The while loop's own value is nil, so a miss returns nil.
+        end
+
         # Iterate over registered (element_class, tag) pairs.
         # Useful for debugging custom libraries — e.g. confirming an override
         # has stuck. Iteration order matches registration order.
@@ -122,10 +152,35 @@ module Markbridge
         # Freeze the library together with its internal Hash so that
         # registration on a shared instance fails loudly instead of
         # silently mutating state visible to every renderer.
+        #
+        # Freezing also flattens ancestry resolution: every known AST
+        # class without an explicit binding whose ancestry resolves to a
+        # tag gets that tag copied into the internal Hash, so lookup on a
+        # frozen library is a single exact Hash hit for those classes
+        # too. +AST::Node.descendants+ is boot-time state, so only
+        # classes defined before the freeze are covered; later classes
+        # keep working through the renderer's lazy {#resolve} fallback.
         def freeze
+          flatten_ancestry!
           @tags.freeze
           super
         end
+
+        private
+
+        # See {#freeze}. Records what it added in +@flattened_classes+ so
+        # {#initialize_copy} can drop those entries from a copy again.
+        def flatten_ancestry!
+          AST::Node.descendants.each do |klass|
+            next if @tags.key?(klass)
+
+            tag = resolve(klass)
+            next unless tag
+
+            (@flattened_classes ||= []) << klass
+            @tags[klass] = tag
+          end
+        end
       end
     end
   end

data/lib/markbridge/renderers/discourse/tags/code_tag.rb

@@ -9,6 +9,10 @@ module Markbridge
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
+            # An empty element renders to nothing — a bare `` pair or an
+            # empty fence would only add noise to the output.
+            return "" if content.empty?
+
             if interface.block_context?(element)
               if interface.html_mode?
                 render_html_block(content, element.language)

data/lib/markbridge/renderers/discourse/tags/details_tag.rb

@@ -25,12 +25,16 @@ module Markbridge
 
           def render(element, interface)
             child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
+            content = interface.render_children(element, context: child_context).strip
+
+            # A details block with nothing to show renders to nothing —
+            # an empty [details] shell would only add noise to the output.
+            return "" if content.empty?
 
             return render_html(element.title, content) if interface.html_mode?
 
             opener = element.title ? %([details="#{element.title}"]) : "[details]"
-            "\n\n#{opener}\n#{content.strip}\n[/details]\n\n"
+            "\n\n#{opener}\n#{content}\n[/details]\n\n"
           end
 
           private

data/lib/markbridge/renderers/discourse/tags/spoiler_tag.rb

@@ -11,6 +11,10 @@ module Markbridge
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
+            # A spoiler with nothing to hide renders to nothing — an empty
+            # [spoiler] shell would only add noise to the output.
+            return "" if content.empty?
+
             return render_html(element.title, content) if interface.html_mode?
 
             if element.title

data/lib/markbridge/renderers/discourse.rb

@@ -7,6 +7,7 @@ require_relative "discourse/rendering_interface"
 require_relative "discourse/markdown_escaper"
 require_relative "discourse/identity_escaper"
 require_relative "discourse/html_escaper"
+require_relative "discourse/html_block_safety"
 require_relative "discourse/postprocessor"
 
 # Builders

data/lib/markbridge/rspec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../markbridge"
+
+# Shared RSpec examples for consumers who write their own renderer
+# tags. Require this file from your spec setup (RSpec itself must
+# already be loaded):
+#
+#     require "markbridge/rspec"
+#
+# and put a custom tag under the html_mode contract:
+#
+#     RSpec.describe MyQuoteTag do
+#       it_behaves_like "an html_mode safe tag" do
+#         let(:tag) { described_class.new }
+#         let(:element) do
+#           element = MyQuote.new
+#           element << Markbridge::AST::Text.new("body *with* sigils")
+#           element
+#         end
+#       end
+#     end
+#
+# The example renders +element+ with +tag+ in html_mode and fails when
+# the output would break inside a CommonMark HTML block — the same
+# check Markbridge runs against its own tags. Give +element+ children
+# whose text contains Markdown sigils, so a tag that passes them
+# through unprotected is caught. When the tag needs a customized
+# renderer to resolve its children (for example a custom tag library),
+# override +markbridge_renderer+ with your configured renderer.
+RSpec.shared_examples "an html_mode safe tag" do
+  let(:markbridge_renderer) { Markbridge::Renderers::Discourse::Renderer.new }
+
+  let(:markbridge_html_mode_interface) do
+    context = Markbridge::Renderers::Discourse::RenderContext.new([], html_mode: true)
+    Markbridge::Renderers::Discourse::RenderingInterface.new(markbridge_renderer, context)
+  end
+
+  it "renders html_mode output that is safe inside an HTML block" do
+    output = tag.render(element, markbridge_html_mode_interface)
+
+    expect(Markbridge::Renderers::Discourse::HtmlBlockSafety.safe?(output)).to be(true),
+    "Expected #{tag.class} to render raw HTML or a \\n\\n-wrapped " \
+      "Markdown island in html_mode, got: #{output.inspect}"
+  end
+end

data/lib/markbridge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markbridge
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/markbridge.rb

@@ -276,8 +276,10 @@ module Markbridge
     #   library to start from. Defaults to a fresh {TagLibrary.default}.
     #   When supplied, it is +dup+'d before any +tags:+ / +unregister:+
     #   mutation, so the caller's library is left untouched.
-    # @param unregister [Array<Class>, nil] AST classes to drop from
-    #   the library so they fall through to +render_children+.
+    # @param unregister [Array<Class>, nil] AST classes whose binding to
+    #   drop from the library. A built-in class then renders as just its
+    #   children; a subclass of a bound class falls back to the nearest
+    #   ancestor's tag (see {Renderers::Discourse::TagLibrary#unregister}).
     # @param escaper [#escape, nil] when given, used as-is; +escape:+,
     #   +escape_hard_line_breaks:+, and +allow:+ are then ignored.
     # @param escape [Boolean] when +false+, the renderer is built with

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markbridge
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Discourse Team
@@ -103,6 +103,7 @@ files:
 - lib/markbridge/parsers/html.rb
 - lib/markbridge/parsers/html/handler_registry.rb
 - lib/markbridge/parsers/html/handlers/base_handler.rb
+- lib/markbridge/parsers/html/handlers/heading_handler.rb
 - lib/markbridge/parsers/html/handlers/image_handler.rb
 - lib/markbridge/parsers/html/handlers/list_handler.rb
 - lib/markbridge/parsers/html/handlers/list_item_handler.rb
@@ -137,6 +138,7 @@ files:
 - lib/markbridge/parsers/text_formatter/parser.rb
 - lib/markbridge/renderers/discourse.rb
 - lib/markbridge/renderers/discourse/builders/list_item_builder.rb
+- lib/markbridge/renderers/discourse/html_block_safety.rb
 - lib/markbridge/renderers/discourse/html_escaper.rb
 - lib/markbridge/renderers/discourse/identity_escaper.rb
 - lib/markbridge/renderers/discourse/markdown_escaper.rb
@@ -176,6 +178,7 @@ files:
 - lib/markbridge/renderers/discourse/tags/underline_tag.rb
 - lib/markbridge/renderers/discourse/tags/upload_tag.rb
 - lib/markbridge/renderers/discourse/tags/url_tag.rb
+- lib/markbridge/rspec.rb
 - lib/markbridge/textformatter.rb
 - lib/markbridge/version.rb
 homepage: https://github.com/discourse/markbridge