markbridge 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cee12c41cea526db53cf389e2cc2bc49310568c0ebe9979d03daa7a4c2d23ac
-  data.tar.gz: a6d541954eea2357b6bb31bcfb685a634383de405dd1f505b257c78007e087d4
+  metadata.gz: dbebafc60a3665c98544f3cfd9496c3c5cdc2c0940339c998791b2df1f04aa44
+  data.tar.gz: 2be35c042f803e37302fa149af772897326241488a9429a525ddc714af0623d1
 SHA512:
-  metadata.gz: b7ddd72dd5d0aa197a7b2477f1bfddd72e9cf7a01f26b4def8da341c8edd739503c04a23a501175adbcc23e23064578a2a4bcb17f3518b543f2716059636e3e7
-  data.tar.gz: 409dcbed4de6b6551c420ca51a00ed998abf11aeac8bd3bce9522b49a5ca07d3e524d68737b9461ddb6e3949485c1c84123c30c8e6e44cb57d7a99d873c7c3af
+  metadata.gz: 6b3e3dc46705d4f7cf52aabaac8b272cbc9241e57473caf11a6c53b1d1355ec2e7874ae485732ba526f67445144f12daccc521dae40a6405994e409a34e00ede
+  data.tar.gz: 89385e8ec7942af10b79b267e6400bfb209af7871775e0891f86153e792e3ef61b15b08eb025f9a6f6d5673c3aaf9bcbb6ec26200ac3a62440b426121fcba1fa

data/lib/markbridge/ast/quote.rb

@@ -4,42 +4,72 @@ module Markbridge
   module AST
     # Represents a quote/blockquote element.
     #
+    # The attribution fields follow Discourse's quote format
+    # (`[quote="username, post:2, topic:456"]`): +post_number+ is the
+    # position of the quoted post *within its topic* (not a database
+    # id), +topic_id+ is the topic's id. Sources that attribute quotes
+    # by database id instead (phpBB, XenForo) use +post_id+ and
+    # +user_id+ — those never feed a Discourse +post:+ reference and
+    # are carried for consumers to remap.
+    #
     # @example Basic quote
     #   quote = AST::Quote.new
     #   quote << AST::Text.new("quoted text")
     #
     # @example Quote with author attribution
-    #   quote = AST::Quote.new(author: "John")
+    #   quote = AST::Quote.new(author: "alice")
     #   quote << AST::Text.new("quoted text")
     #
     # @example Quote with full Discourse context
-    #   quote = AST::Quote.new(author: "John", post: "123", topic: "456", username: "john123")
+    #   quote = AST::Quote.new(author: "alice", post_number: 123, topic_id: 456, username: "alice_b")
     #   quote << AST::Text.new("quoted text")
     class Quote < Element
-      # @return [String, nil] the author/username of the quote
+      # @return [String, nil] the author attribution (display name)
       attr_reader :author
 
-      # @return [String, nil] the post ID for Discourse quotes
-      attr_reader :post
+      # @return [Integer, nil] the quoted post's number within its topic
+      #   (Discourse semantics — not a post id)
+      attr_reader :post_number
+
+      # @return [Integer, nil] the quoted post's database id, for sources
+      #   that attribute quotes by id (phpBB's +post_id+, XenForo's
+      #   +post:+). Distinct from {#post_number}; parsers map whichever
+      #   their dialect provides.
+      attr_reader :post_id
 
-      # @return [String, nil] the topic ID for Discourse quotes
-      attr_reader :topic
+      # @return [Integer, nil] the topic id the quoted post belongs to
+      attr_reader :topic_id
 
-      # @return [String, nil] the username for Discourse quotes
+      # @return [String, nil] the quoted user's username
       attr_reader :username
 
+      # @return [Integer, nil] the quoted user's id, for sources that
+      #   attribute quotes by id (usernames may be unknown or stale)
+      attr_reader :user_id
+
       # Create a new Quote element.
       #
-      # @param author [String, nil] the author attribution
-      # @param post [String, nil] the post ID (Discourse-specific)
-      # @param topic [String, nil] the topic ID (Discourse-specific)
-      # @param username [String, nil] the username (Discourse-specific)
-      def initialize(author: nil, post: nil, topic: nil, username: nil)
+      # @param author [String, nil] the author attribution (display name)
+      # @param post_number [Integer, nil] the quoted post's number within its topic
+      # @param post_id [Integer, nil] the quoted post's database id
+      # @param topic_id [Integer, nil] the topic id
+      # @param username [String, nil] the quoted user's username
+      # @param user_id [Integer, nil] the quoted user's id
+      def initialize(
+        author: nil,
+        post_number: nil,
+        post_id: nil,
+        topic_id: nil,
+        username: nil,
+        user_id: nil
+      )
         super()
         @author = author
-        @post = post
-        @topic = topic
+        @post_number = post_number
+        @post_id = post_id
+        @topic_id = topic_id
         @username = username
+        @user_id = user_id
       end
     end
   end

data/lib/markbridge/ast/text.rb

@@ -19,13 +19,15 @@ module Markbridge
 
       # Create a new text node with the given content.
       #
-      # The text is copied into a fresh mutable buffer so that subsequent
-      # in-place mutations (e.g. via {#merge}) do not leak back to the caller's
-      # original string.
+      # Frozen input is shared as-is (copy-on-write: {#merge} dups before
+      # its first append) — the parser hot path always passes frozen token
+      # text, so no copy is made per text node. Mutable input is copied so
+      # that in-place mutations cannot leak in either direction between
+      # the caller's string and this node.
       #
       # @param text [String] the text content
       def initialize(text)
-        @text = text.dup
+        @text = text.frozen? ? text : text.dup
       end
 
       # Merge another text node's content into this one.
@@ -34,6 +36,7 @@ module Markbridge
       # @param other [Text] the text node to merge from
       # @return [Text] self for method chaining
       def merge(other)
+        @text = @text.dup if @text.frozen?
         @text << other.text
         self
       end

data/lib/markbridge/ast/url.rb

@@ -22,6 +22,21 @@ module Markbridge
         super()
         @href = href
       end
+
+      # Whether this link is "bare" — it has no link text of its own:
+      # either no children, or a single Text child whose content is
+      # exactly the href (how parsers model a URL that stands for
+      # itself). Consumers that record or rewrite links need this
+      # judgment too (a bare URL must stay bare to keep autolinking
+      # and oneboxing working), so it lives on the node rather than
+      # in the renderer.
+      #
+      # @return [Boolean]
+      def bare?
+        return true if children.empty?
+
+        children.size == 1 && children.first.instance_of?(Text) && children.first.text == href
+      end
     end
   end
 end

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

@@ -62,7 +62,11 @@ module Markbridge
         # @param tag_name [String]
         # @return [BaseHandler, nil]
         def [](tag_name)
-          @handlers[tag_name.to_s.downcase]
+          # Keys are always downcased strings and the scanner emits
+          # downcased tags, so the fetch hits directly on the hot path;
+          # the block normalizes only unusual lookups (mixed case,
+          # symbols) instead of allocating a downcased copy per token.
+          @handlers.fetch(tag_name) { @handlers[tag_name.to_s.downcase] }
         end
 
         # Get handler for an element instance
@@ -176,6 +180,28 @@ module Markbridge
           registry
         end
 
+        # Shared, deep-frozen default registry for the no-customization
+        # fast path. Built once per process; {Parser} falls back to it
+        # when no +handlers:+ are given, skipping the full registry
+        # construction on every parse. Handlers and closing strategies
+        # are stateless after construction, so sharing is safe across
+        # parsers and threads.
+        #
+        # @return [HandlerRegistry] the same frozen instance on every call
+        def self.shared_default
+          @shared_default ||= default.freeze
+        end
+
+        # Freeze the registry together with its internal collections so
+        # that registration on a shared instance fails loudly instead of
+        # silently mutating state visible to every parser.
+        def freeze
+          @handlers.freeze
+          @element_handlers.freeze
+          @auto_closeable_elements.freeze
+          super
+        end
+
         # Build a registry from the default configuration with optional customization
         # @yield [HandlerRegistry] the registry to customize
         # @return [HandlerRegistry]

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

@@ -10,7 +10,14 @@ module Markbridge
         # - [quote=author]text[/quote]
         # - [quote="author"]text[/quote]
         # - [quote author=username]text[/quote]
-        # - [quote="username, post:123, topic:456"]text[/quote] (Discourse format)
+        # - [quote="username, post:2, topic:456"]text[/quote] (Discourse format)
+        #
+        # Attribution semantics are Discourse's: `post:` is the post's
+        # number within its topic and `topic:` is the topic id. Beware
+        # when feeding other dialects through this handler — XenForo
+        # attributions ("name, post: 12345, member: 678") also match the
+        # `post:` pattern, but there the value is a database post id, not
+        # a post number.
         class QuoteHandler < BaseHandler
           def initialize
             @element_class = AST::Quote
@@ -27,13 +34,13 @@ module Markbridge
           private
 
           def extract_quote_attrs(token)
-            author, post, topic, username = extract_from_option(token)
+            author, post_number, topic_id, username = extract_from_option(token)
             author ||= token.attrs[:author]
 
             {
               author:,
-              post: token.attrs[:post] || post,
-              topic: token.attrs[:topic] || topic,
+              post_number: integer_or_nil(token.attrs[:post]) || post_number,
+              topic_id: integer_or_nil(token.attrs[:topic]) || topic_id,
               username: token.attrs[:username] || username,
             }
           end
@@ -42,15 +49,31 @@ module Markbridge
             option = token.attrs[:option]
             return nil, nil, nil, nil unless option
 
-            post = option[/,\s*post:(\d+)/, 1]
-            return option, nil, nil, nil unless post
+            post_number = option[/,\s*post:(\d+)/, 1]
+            return option, nil, nil, nil unless post_number
 
-            # Discourse format: "username, post:123, topic:456" (topic optional,
+            # Discourse format: "username, post:2, topic:456" (topic optional,
             # order irrelevant between post: and topic:).
             username = option.split(",").first.strip
-            topic = option[/,\s*topic:(\d+)/, 1]
+            topic_id = option[/,\s*topic:(\d+)/, 1]
 
-            [username, post, topic, username]
+            # The regex captures are guaranteed digit runs, so strict
+            # Integer() applies. Base 10 is explicit: without it a
+            # leading zero switches Integer() to octal and "099" raises.
+            [username, Integer(post_number, 10), topic_id && Integer(topic_id, 10), username]
+          end
+
+          # Coerce an attribute value to Integer; nil and non-numeric
+          # values (which would make a useless attribution anyway)
+          # become nil. Base 10 is explicit so leading zeros ("099")
+          # don't trip Integer()'s octal mode and prefix forms ("0x1A")
+          # don't smuggle in surprise values. The result is an unbounded
+          # Ruby Integer — a runaway digit run like
+          # "post:77777777777777777789999" parses to a bignum, so
+          # consumers binding these into fixed-width storage (int64
+          # columns) need their own bounds check.
+          def integer_or_nil(value)
+            Integer(value, 10, exception: false)
           end
         end
       end

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

@@ -11,6 +11,13 @@ module Markbridge
           def initialize(element_class, collector: RawContentCollector.new)
             @element_class = element_class
             @collector = collector
+            # Computed once here: handlers are long-lived, elements are
+            # per-tag, and the reflection is too costly to repeat per element.
+            @accepts_language =
+              element_class
+                .instance_method(:initialize)
+                .parameters
+                .any? { |_kind, name| name == :language }
           end
 
           def on_open(token:, context:, registry:, tokens:)
@@ -43,10 +50,7 @@ module Markbridge
           end
 
           def accepts_language?
-            @element_class
-              .instance_method(:initialize)
-              .parameters
-              .any? { |_kind, name| name == :language }
+            @accepts_language
           end
         end
       end

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

@@ -26,7 +26,7 @@ module Markbridge
             if block_given?
               HandlerRegistry.build_from_default(&block)
             else
-              handlers || HandlerRegistry.default
+              handlers || HandlerRegistry.shared_default
             end
           @unknown_tags = Hash.new(0)
         end
@@ -53,11 +53,14 @@ module Markbridge
 
         private
 
+        LINE_ENDING_RE = /\r\n?|[\u2028\u2029]+/
+        private_constant :LINE_ENDING_RE
+
         # Normalize line endings (CR, CRLF, and Unicode separators)
         # @param input [String]
-        # @return [String]
+        # @return [String] the input itself when already normalized (LF-only)
         def normalize_line_endings(input)
-          input.gsub(/\r\n?|[\u2028\u2029]+/, "\n")
+          input.match?(LINE_ENDING_RE) ? input.gsub(LINE_ENDING_RE, "\n") : input
         end
 
         # Parse tokens using scanner

data/lib/markbridge/parsers/bbcode/scanner.rb

@@ -3,26 +3,39 @@
 module Markbridge
   module Parsers
     module BBCode
-      # High-performance character-by-character BBCode scanner
+      # High-performance BBCode scanner
       # Tokenizes BBCode in O(n) time with minimal allocations and bounded backtracking
+      #
+      # The scanner works entirely in *byte* offsets (byteindex/byteslice/
+      # getbyte). CRuby has no character-index cache, so character-index
+      # operations like `str[pos]` walk the string from the start on any
+      # input containing a multibyte character — O(pos) per call and
+      # superlinear per document. Byte offsets keep multibyte input at
+      # near-ASCII cost. Invariant: `@current_pos` always sits on a
+      # character boundary — jumps land on matches of ASCII-only patterns
+      # and advances step over ASCII bytes or whole matches. Token
+      # positions are therefore byte offsets into the input.
       class Scanner
         def initialize(input)
           @input = input
-          @length = input.length
+          @length = input.bytesize
           @current_pos = 0
         end
 
         def next_token
           return nil if end_of_input?
           start_pos = @current_pos
-          bracket_index = @input.index("[", @current_pos)
+          # `byteindex` returns 0 for a match at the start — nil-check, never
+          # truthiness-check. Can't be 0 here though: callers guarantee
+          # @current_pos <= bracket_index.
+          bracket_index = @input.byteindex("[", @current_pos)
 
           if bracket_index.nil?
-            text = @input[@current_pos..]
+            text = @input.byteslice(@current_pos, @length - @current_pos)
             @current_pos = @length
             TextToken.new(text:, pos: start_pos)
           elsif bracket_index > @current_pos
-            text = @input[@current_pos...bracket_index]
+            text = @input.byteslice(@current_pos, bracket_index - @current_pos)
             @current_pos = bracket_index
             TextToken.new(text:, pos: start_pos)
           elsif (tag_token = parse_tag_at_cursor)
@@ -35,31 +48,65 @@ module Markbridge
 
         private
 
-        TAG_INITIAL_CHAR = /[a-z*]/i
-        TAG_NAME_CHAR = /[a-z0-9]/i
-        UID_HEX_CHAR = /[0-9a-f]/i
-        ATTR_NAME_CHAR = /\w/
-        WHITESPACE_CHAR = /\s/
+        # Byte constants for tag scanning. A byte >= 0x80 (multibyte
+        # lead/continuation) never satisfies any of the ASCII predicates
+        # below, so no encoding-awareness is needed at probe sites.
+        TAB = 9 # \t
+        CR = 13 # \r  (\s == [ \t\n\v\f\r] == 0x20, 0x09..0x0D)
+        SPACE = 32
+        DOUBLE_QUOTE = 34 # "
+        SINGLE_QUOTE = 39 # '
+        STAR = 42 # *
+        SLASH = 47 # /
+        DIGIT_0 = 48
+        DIGIT_9 = 57
+        COLON = 58 # :
+        EQUALS = 61 # =
+        UPPER_A = 65
+        UPPER_F = 70
+        UPPER_Z = 90
+        BRACKET_CLOSE = 93 # ]
+        UNDERSCORE = 95 # _
+        LOWER_A = 97
+        LOWER_F = 102
+        LOWER_Z = 122
+
+        # Characters an unquoted attribute value stops at. ASCII-only, so a
+        # byteindex match always lands on a character boundary.
         UNQUOTED_VALUE_STOP = /[\[\]\s]/
 
-        private_constant :TAG_INITIAL_CHAR,
-                         :TAG_NAME_CHAR,
-                         :UID_HEX_CHAR,
-                         :ATTR_NAME_CHAR,
-                         :WHITESPACE_CHAR,
+        private_constant :TAB,
+                         :CR,
+                         :SPACE,
+                         :DOUBLE_QUOTE,
+                         :SINGLE_QUOTE,
+                         :STAR,
+                         :SLASH,
+                         :DIGIT_0,
+                         :DIGIT_9,
+                         :COLON,
+                         :EQUALS,
+                         :UPPER_A,
+                         :UPPER_F,
+                         :UPPER_Z,
+                         :BRACKET_CLOSE,
+                         :UNDERSCORE,
+                         :LOWER_A,
+                         :LOWER_F,
+                         :LOWER_Z,
                          :UNQUOTED_VALUE_STOP
 
         # @return [Token, nil] tag token or nil if not a valid tag (caller rolls back)
-        # Precondition: caller has verified current_char == "[".
+        # Precondition: caller has verified the byte at the cursor is "[".
         def parse_tag_at_cursor
           tag_start_pos = @current_pos
           @current_pos += 1 # skip '['
-          closing = consume("/")
+          closing = consume(SLASH)
           tag_name = scan_tag_name
           attrs = (closing || tag_name.nil?) ? {} : scan_attributes
-          return rollback(tag_start_pos) unless tag_name && consume("]")
+          return rollback(tag_start_pos) unless tag_name && consume(BRACKET_CLOSE)
 
-          source = @input[tag_start_pos...@current_pos]
+          source = @input.byteslice(tag_start_pos, @current_pos - tag_start_pos)
           build_token(closing:, tag: tag_name.downcase, attrs:, pos: tag_start_pos, source:)
         end
 
@@ -76,27 +123,26 @@ module Markbridge
           nil
         end
 
-        # Scan a tag name: [a-z*][a-z0-9]*(:hex*)?
+        # Scan a tag name: [a-z*][a-z0-9]*(:hex*)?  (case-insensitive)
         #
-        # Char-by-char rather than a single regex over `@input[pos..]`
+        # Byte-predicate loop rather than a regex over `@input[pos..]`
         # because the regex form allocates a substring for every tag,
-        # which is a dominant cost on tag-heavy input. The char-based
-        # loop is ~3x faster under YJIT.
+        # which is a dominant cost on tag-heavy input.
         # @return [String, nil]
         def scan_tag_name
           start = @current_pos
 
-          return nil unless current_char&.match?(TAG_INITIAL_CHAR)
+          return nil unless tag_initial_byte?(current_byte)
           @current_pos += 1
 
-          @current_pos += 1 while current_char&.match?(TAG_NAME_CHAR)
+          @current_pos += 1 while tag_name_byte?(current_byte)
 
-          if current_char == ":"
+          if current_byte == COLON
             @current_pos += 1
-            @current_pos += 1 while current_char&.match?(UID_HEX_CHAR)
+            @current_pos += 1 while uid_hex_byte?(current_byte)
           end
 
-          @input[start...@current_pos]
+          @input.byteslice(start, @current_pos - start)
         end
 
         # Scan tag attributes
@@ -107,7 +153,7 @@ module Markbridge
           attrs = {}
           skip_whitespace
 
-          if current_char == "="
+          if current_byte == EQUALS
             @current_pos += 1
             skip_whitespace
             if (val = scan_attribute_value)
@@ -116,9 +162,9 @@ module Markbridge
             skip_whitespace
           end
 
-          while (name = scan_while(ATTR_NAME_CHAR))
+          while (name = scan_attr_name)
             skip_whitespace
-            break unless consume("=")
+            break unless consume(EQUALS)
 
             skip_whitespace
             value = scan_attribute_value
@@ -129,16 +175,16 @@ module Markbridge
           attrs
         end
 
-        def consume(char)
-          return false if current_char != char
+        def consume(byte)
+          return false if current_byte != byte
 
           @current_pos += 1
           true
         end
 
         def scan_attribute_value
-          char = current_char
-          if char == '"' || char == "'"
+          byte = current_byte
+          if byte == DOUBLE_QUOTE || byte == SINGLE_QUOTE
             scan_quoted_string
           else
             scan_unquoted_value
@@ -161,52 +207,86 @@ module Markbridge
         #
         # @return [String, nil] the unescaped attribute value, or nil if unterminated
         def scan_quoted_string
-          quote_char = current_char
+          quote = current_byte == DOUBLE_QUOTE ? "\"" : "'"
           start = (@current_pos += 1) # skip opening quote
-          closing_index = @input.index(quote_char, start)
+          closing_index = @input.byteindex(quote, start)
           return nil unless closing_index
 
           @current_pos = closing_index + 1
-          @input[start...closing_index]
+          @input.byteslice(start, closing_index - start)
         end
 
         def scan_unquoted_value
-          scan_until(UNQUOTED_VALUE_STOP)
+          consume_range(@input.byteindex(UNQUOTED_VALUE_STOP, @current_pos) || @length)
         end
 
-        # Consumes characters matching +pattern+; returns substring or nil if empty
-        def scan_while(pattern)
+        # Consumes attribute-name characters (\w == [A-Za-z0-9_]); returns
+        # substring or nil if empty
+        def scan_attr_name
           stop_index = @current_pos
-          stop_index += 1 while stop_index < @length && @input[stop_index].match?(pattern)
+          stop_index += 1 while stop_index < @length && attr_name_byte?(@input.getbyte(stop_index))
           consume_range(stop_index)
         end
 
-        # Consumes characters until +pattern+ matches (or end of input); returns substring or nil if empty
-        def scan_until(pattern)
-          consume_range(@input.index(pattern, @current_pos) || @length)
-        end
-
         # Slice [@current_pos, stop_index), advance the cursor, or return nil for empty.
         def consume_range(stop_index)
           return nil if stop_index == @current_pos
 
-          value = @input[@current_pos...stop_index]
+          value = @input.byteslice(@current_pos, stop_index - @current_pos)
           @current_pos = stop_index
           value
         end
 
-        def current_char
-          @input[@current_pos]
+        # @return [Integer, nil] byte at the cursor, nil at end of input
+        def current_byte
+          @input.getbyte(@current_pos)
         end
 
         def skip_whitespace
           @current_pos += 1 while @current_pos < @length &&
-            @input[@current_pos].match?(WHITESPACE_CHAR)
+            whitespace_byte?(@input.getbyte(@current_pos))
+        end
+
+        # [a-z*]/i — first character of a tag name; nil (end of input) is
+        # not a tag byte
+        def tag_initial_byte?(byte)
+          byte &&
+            (
+              (byte >= LOWER_A && byte <= LOWER_Z) || (byte >= UPPER_A && byte <= UPPER_Z) ||
+                byte == STAR
+            )
+        end
+
+        # [a-z0-9]/i — rest of a tag name
+        def tag_name_byte?(byte)
+          return false if byte.nil?
+
+          (byte >= LOWER_A && byte <= LOWER_Z) || (byte >= UPPER_A && byte <= UPPER_Z) ||
+            (byte >= DIGIT_0 && byte <= DIGIT_9)
+        end
+
+        # [0-9a-f]/i — uid suffix after ':'
+        def uid_hex_byte?(byte)
+          return false if byte.nil?
+
+          (byte >= DIGIT_0 && byte <= DIGIT_9) || (byte >= LOWER_A && byte <= LOWER_F) ||
+            (byte >= UPPER_A && byte <= UPPER_F)
+        end
+
+        # \w — attribute name character
+        def attr_name_byte?(byte)
+          (byte >= LOWER_A && byte <= LOWER_Z) || (byte >= UPPER_A && byte <= UPPER_Z) ||
+            (byte >= DIGIT_0 && byte <= DIGIT_9) || byte == UNDERSCORE
+        end
+
+        # \s — exactly [ \t\n\v\f\r]
+        def whitespace_byte?(byte)
+          byte == SPACE || (byte >= TAB && byte <= CR)
         end
 
         def end_of_input?
-          # All callers maintain @current_pos <= @length (scan_while
-          # bounds on @length; scan_until uses `index || @length`;
+          # All callers maintain @current_pos <= @length (scan_attr_name
+          # bounds on @length; scan_unquoted_value uses `byteindex || @length`;
           # consume is a no-op at EOF); `==` and `>=` are observably
           # identical here.
           @current_pos == @length

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

@@ -112,7 +112,10 @@ module Markbridge
         # @param tag_name [String]
         # @return [BaseHandler, nil]
         def [](tag_name)
-          @handlers[tag_name.to_s.downcase]
+          # Keys are always downcased strings and Nokogiri's HTML parser
+          # yields downcased element names, so the fetch hits directly on
+          # the hot path; the block normalizes only unusual lookups.
+          @handlers.fetch(tag_name) { @handlers[tag_name.to_s.downcase] }
         end
 
         # Create the default handler registry with common HTML tags
@@ -149,6 +152,29 @@ module Markbridge
           yield(registry) if block_given?
           registry
         end
+
+        # Shared, deep-frozen default registry for the no-customization
+        # fast path. Built once per process; {Parser} falls back to it
+        # when no +handlers:+ are given, skipping the full registry
+        # construction on every parse. Handlers are stateless after
+        # construction, so sharing is safe across parsers and threads.
+        # Callers who want to mutate the tag sets must build their own
+        # {.default}.
+        #
+        # @return [HandlerRegistry] the same frozen instance on every call
+        def self.shared_default
+          @shared_default ||= default.freeze
+        end
+
+        # Freeze the registry together with its internal collections so
+        # that mutation of a shared instance fails loudly instead of
+        # silently changing state visible to every parser.
+        def freeze
+          @handlers.freeze
+          @block_level_tags.freeze
+          @whitespace_preserving_tags.freeze
+          super
+        end
       end
     end
   end