przn 0.5.0 → 0.6.0

data/lib/przn/parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'set'
 require 'strscan'
 
 module Przn
@@ -18,11 +19,11 @@ module Przn
     }.freeze
 
     NAMED_COLORS = {
-      'red' => 31, 'green' => 32, 'yellow' => 33, 'blue' => 34,
-      'magenta' => 35, 'cyan' => 36, 'white' => 37,
-      'bright_red' => 91, 'bright_green' => 92, 'bright_yellow' => 93,
-      'bright_blue' => 94, 'bright_magenta' => 95, 'bright_cyan' => 96,
-      'bright_white' => 97
+      'black' => 30, 'red' => 31, 'green' => 32, 'yellow' => 33,
+      'blue' => 34, 'magenta' => 35, 'cyan' => 36, 'white' => 37,
+      'bright_black' => 90, 'bright_red' => 91, 'bright_green' => 92,
+      'bright_yellow' => 93, 'bright_blue' => 94, 'bright_magenta' => 95,
+      'bright_cyan' => 96, 'bright_white' => 97
     }.freeze
 
     # HTML-ish attribute, three accepted value forms:
@@ -32,7 +33,7 @@ module Przn
     # `/` is intentionally NOT excluded so paths like `src=path/to/file`
     # work — which means self-closing tags need a space before `/>` when
     # the last attribute is unquoted (`<img src=foo.png />`).
-    ATTR_RE_SRC = '\w+=(?:"[^"]*"|\'[^\']*\'|[^\s=<>"\'`]+)'
+    ATTR_RE_SRC = '[\w-]+=(?:"[^"]*"|\'[^\']*\'|[^\s=<>"\'`]+)'
 
     module_function
 
@@ -64,6 +65,7 @@ module Przn
 
     def parse_slide(raw)
       blocks = []
+      slide_attrs = {}
       lines = raw.lines
       i = 0
 
@@ -71,6 +73,13 @@ module Przn
         line = lines[i]
 
         case line
+        # <!-- ... --> block (single or multi line) — skip entirely.
+        # Sibling of the kramdown `{::comment} ... {:/comment}` form.
+        when /\A\s*<!--/
+          # Same line? Skip just this line.
+          i += 1 unless line.match?(/-->/)
+          i += 1 while i < lines.size && !lines[i].match?(/-->/)
+
         # {::comment} ... {:/comment} block — skip entirely
         when /\A\s*\{::comment\}/
           i += 1
@@ -83,7 +92,9 @@ module Przn
         # Block alignment, XML form: <center>content</center> or <right>content</right>
         when /\A\s*<(center|right)>(.*)<\/\1>\s*\z/
           blocks << {type: :align, align: Regexp.last_match(1).to_sym}
-          blocks << {type: :paragraph, content: Regexp.last_match(2)}
+          content = Regexp.last_match(2).dup
+          blocks << {type: :wait} if strip_leading_wait!(content)
+          blocks << {type: :paragraph, content: content}
 
         # Slide background (Echoes OSC 7772):
         #   <bg color="#..."/>                              — solid (bg-color)
@@ -102,10 +113,17 @@ module Przn
         when %r{\A\s*\{::at((?:\s+#{ATTR_RE_SRC})+)\}(.*)\{:/at\}\s*\z}o
           blocks << {type: :at, attrs: parse_xml_attrs(Regexp.last_match(1)), content: Regexp.last_match(2)}
 
-        # Fenced code block
-        when /\A\s*```(\w*)\s*\z/
+        # Fenced code block. Optional kramdown-style IAL right after the
+        # language lets one block override the theme's per-attribute
+        # code defaults — typically `size` to shrink a long snippet to
+        # one scale, or `family` / `color` / `bg` for a one-off look:
+        #   ```ruby {size=1}
+        #   ```ruby {size: small, family: Menlo}
+        when /\A\s*```(\w*)\s*(?:\{([^}]*)\})?\s*\z/
           lang = Regexp.last_match(1)
           lang = nil if lang.empty?
+          ial_inner = Regexp.last_match(2)
+          attrs = ial_inner ? parse_ial_attrs(ial_inner) : nil
           code_lines = []
           i += 1
           while i < lines.size && !lines[i].match?(/\A\s*```\s*\z/)
@@ -118,8 +136,33 @@ module Przn
             if lines[i].match(/lang="(\w+)"/)
               lang = Regexp.last_match(1)
             end
+            # Closing-line IAL can also carry per-block style overrides,
+            # merged WITHOUT clobbering the opener IAL (opener wins).
+            trailing = parse_ial_attrs(lines[i][/\{([^}]*)\}/, 1] || '')
+            attrs = trailing.merge(attrs || {}) unless trailing.empty?
+          end
+          # ```mermaid is special-cased into its own block type — the
+          # renderer shells out to mmdc to produce a PNG and places it
+          # as an inline image. Per-block IAL (`{height=70%}`, etc.)
+          # rides through on attrs to size the placement.
+          block = if lang == 'mermaid'
+                    {type: :mermaid, content: code_lines.join}
+                  else
+                    {type: :code_block, content: code_lines.join, language: lang}
+                  end
+          block[:attrs] = attrs if attrs && !attrs.empty?
+          # Per-line highlight stepping: `{lines=1-2|3|4}` parses pipe-
+          # separated step groups and emits one synthetic `<wait/>` per
+          # extra group so the step counter advances naturally. The
+          # renderer dims lines outside the active group via the
+          # OSC 7772 cell-alpha pipeline.
+          if attrs && (raw = attrs[:lines]) && (steps = parse_line_steps(raw))
+            block[:line_steps] = steps
+            blocks << block
+            (steps.size - 1).times { blocks << {type: :wait} }
+          else
+            blocks << block
           end
-          blocks << {type: :code_block, content: code_lines.join, language: lang}
 
         # Indented code block (4 spaces)
         when /\A {4}(.*)$/
@@ -138,9 +181,98 @@ module Przn
           end
           blocks << {type: :code_block, content: code_lines.join("\n") + "\n", language: lang}
 
-        # h1 (slide title)
+        # h1 (slide title) — also accepts a trailing IAL with slide-level
+        # metadata: `# Title {layout=name}` / `{:layout=name}` / `{layout: name}`.
+        # The IAL is lifted off and stashed on slide_attrs; the heading
+        # content keeps just the title text.
         when /\A#\s+(.*)/
-          blocks << {type: :heading, level: 1, content: Regexp.last_match(1).strip}
+          heading_body, ial_attrs = extract_h1_ial(Regexp.last_match(1).strip)
+          blocks << {type: :heading, level: 1, content: heading_body}
+          slide_attrs.merge!(ial_attrs)
+
+        # Slot break inside a layout-driven slide. `<slot/>` advances to
+        # the next slot; `<slot name="right"/>` jumps to that named slot.
+        # Outside a layout, the block is a render-time no-op.
+        when %r{\A\s*<slot((?:\s+#{ATTR_RE_SRC})*)\s*/>\s*\z}o
+          attrs = parse_xml_attrs(Regexp.last_match(1))
+          blocks << {type: :slot, name: attrs[:name]}
+
+        # Step boundary for incremental reveals (Keynote-style "builds").
+        # A `<wait/>` on its own line divides the slide's block sequence
+        # into a group; the renderer renders all blocks up to the current
+        # step and *reserves* layout space for the rest. Pressing Space
+        # advances by one step before flipping to the next slide. A
+        # leading `<wait/>` on a list item or paragraph (handled at the
+        # respective push sites) is the same boundary scoped one notch
+        # finer. Mid-text `<wait/>` is still silently dropped in
+        # `parse_inline` — splitting a sentence mid-flow has no defined
+        # rendering semantics yet.
+        when %r{\A\s*<wait\s*/>\s*\z}, %r{\A\s*<wait>\s*</wait>\s*\z}, %r{\A\s*\{::wait/\}\s*\z}
+          blocks << {type: :wait}
+
+        # Action targeting a previously-id'd block. The renderer
+        # accumulates these by step into an "effective state" map
+        # (`{id => override_attrs}`) so when the target block renders
+        # at the current step it picks up the new x / y / etc. instead
+        # of its original attrs. `target=` is required; other attrs
+        # ride through as overrides — typically x / y / z / opacity
+        # but anything the target's renderer reads can be moved.
+        when %r{\A\s*<action((?:\s+#{ATTR_RE_SRC})*)\s*/>\s*\z}o
+          attrs = parse_xml_attrs(Regexp.last_match(1))
+          if attrs[:target]
+            block = {type: :action, attrs: attrs}
+            # `duration="500ms"` / `"0.5s"` / plain `"500"` turns the
+            # snap into a smooth interpolation. Unparseable values
+            # silently fall back to instant — keeps a typo from
+            # crashing the deck. See `parse_duration_ms`.
+            if attrs[:duration] && (ms = parse_duration_ms(attrs[:duration]))
+              block[:duration_ms] = ms
+            end
+            blocks << block
+          end
+
+        # Cross-slide content reference. `<ref id="x"/>` re-renders the
+        # block whose original declaration carries `id="x"` (anywhere
+        # in the deck) at the ref's position. Same-tag attrs on the
+        # `<ref>` (typically x / y) override the source's, so the same
+        # callout can appear in a new spot without copy-pasting its
+        # content. Missing id is silently dropped, matching `<action>`.
+        when %r{\A\s*<ref((?:\s+#{ATTR_RE_SRC})*)\s*/>\s*\z}o
+          attrs = parse_xml_attrs(Regexp.last_match(1))
+          blocks << {type: :ref, attrs: attrs} if attrs[:id]
+
+        # Composite container — wraps an arbitrary sequence of child
+        # blocks under one id. `<ref id="x"/>` resolves a group source
+        # the same way it resolves any other id'd block, replaying the
+        # whole bundle on another slide. The opening and closing tags
+        # must each be alone on their own line (matches the line-level
+        # parsing model the rest of the block-level dispatch uses). A
+        # missing close tag or missing id is silently dropped — the
+        # next h1 / end-of-input ends the implicit scan.
+        when %r{\A\s*<group((?:\s+#{ATTR_RE_SRC})*)\s*>\s*\z}o
+          group_attrs = parse_xml_attrs(Regexp.last_match(1))
+          depth = 1
+          scan = i + 1
+          while scan < lines.size
+            if lines[scan] =~ %r{\A\s*<group((?:\s+#{ATTR_RE_SRC})*)\s*>\s*\z}o
+              depth += 1
+            elsif lines[scan] =~ %r{\A\s*</group>\s*\z}
+              depth -= 1
+              break if depth == 0
+            end
+            scan += 1
+          end
+          if depth == 0 && group_attrs[:id]
+            # Recurse on the inner lines via parse_slide so every existing
+            # block-level construct (paragraph, <at>, <img>, shapes, even
+            # nested <group>) works inside without duplicating the dispatch.
+            # Throw away any incidental h1 IAL the inner content yields —
+            # it belongs to the outer slide, not the group.
+            inner_text = lines[(i + 1)...scan].join
+            children = parse_slide(inner_text).blocks
+            blocks << {type: :group, attrs: group_attrs, children: children}
+            i = scan   # outer `i += 1` lands on the line after </group>
+          end
 
         # h2-h6 (sub-headings within slide)
         when /\A(\#{2,6})\s+(.*)/
@@ -172,7 +304,10 @@ module Przn
           while i < lines.size && (lines[i].match?(/\A[*\-]\s+/) || lines[i].match?(/\A {2,}[*\-]\s+/) || lines[i].match?(/\A {2,}\S/))
             if lines[i].match(/\A(\s*)[*\-]\s+(.*)/)
               depth = Regexp.last_match(1).size / 2
-              items << {text: Regexp.last_match(2), depth: depth}
+              text = Regexp.last_match(2).dup
+              item = {text: text, depth: depth}
+              item[:wait] = true if strip_leading_wait!(text)
+              items << item
             elsif lines[i].match(/\A {2,}(\S.*)/)
               # Continuation line
               items.last[:text] << ' ' << Regexp.last_match(1) if items.last
@@ -190,12 +325,28 @@ module Przn
           while i < lines.size && lines[i].match?(/\A\s*\d+\.\s+/)
             lines[i].match(/\A(\s*)\d+\.\s+(.*)/)
             depth = Regexp.last_match(1).size / 3
-            items << {text: Regexp.last_match(2), depth: depth}
+            text = Regexp.last_match(2).dup
+            item = {text: text, depth: depth}
+            item[:wait] = true if strip_leading_wait!(text)
+            items << item
             i += 1
           end
           i -= 1
           blocks << {type: :ordered_list, items: items}
 
+        # Shape primitives — Keynote-style "Shapes and Lines". Each tag is
+        # self-closing with the shape's geometry attrs (cells, or `N%` of
+        # the terminal w/h) plus optional SVG paint attrs (fill, stroke,
+        # stroke-width, opacity, …). The renderer composes each block into
+        # a tiny self-contained SVG document shipped via the Kitty
+        # Graphics Protocol — Echoes content-sniffs the payload and
+        # rasterizes it through its native CoreGraphics fast path
+        # (sub-millisecond for path-only SVGs, which these always are).
+        when %r{\A\s*<(rect|circle|ellipse|line|polyline|polygon|arrow|path)((?:\s+#{ATTR_RE_SRC})*)\s*/>\s*\z}o
+          kind = Regexp.last_match(1).to_sym
+          attrs = parse_xml_attrs(Regexp.last_match(2)).transform_keys(&:to_s)
+          blocks << {type: :shape, kind: kind, attrs: attrs}
+
         # Image, XML form: <img src="path" alt="..." title="..." {:attrs}/>
         # Equivalent to the markdown `![alt](src "title"){:attrs}` form below
         # — emits the same `:image` block so the renderer handles both
@@ -251,19 +402,83 @@ module Przn
             i -= 1
             blocks << {type: :definition_list, term: term, definition: definition_lines.join("\n")}
           else
-            blocks << {type: :paragraph, content: Regexp.last_match(1).strip}
+            content = Regexp.last_match(1).strip
+            blocks << {type: :wait} if strip_leading_wait!(content)
+            blocks << {type: :paragraph, content: content}
           end
 
         when /\A\s*\z/
           blocks << {type: :blank}
 
         else
-          blocks << {type: :paragraph, content: line.strip}
+          content = line.strip
+          blocks << {type: :wait} if strip_leading_wait!(content)
+          blocks << {type: :paragraph, content: content}
         end
         i += 1
       end
 
-      Slide.new(blocks)
+      hoist_fragment_attrs!(blocks)
+      layout = slide_attrs.delete(:layout)
+      Slide.new(blocks, layout: layout, attrs: slide_attrs)
+    end
+
+    # Pull `fragment="..."` off the attrs of `<at>` / `<img>` / shape
+    # blocks and stash it on the block itself as `:fragment`. Auto-
+    # generate an `id=` when none is present so the renderer's effective-
+    # state machinery can target the block. Counter is per-slide; cross-
+    # slide id collisions are fine because each slide computes its own
+    # effective_state independently.
+    def hoist_fragment_attrs!(blocks)
+      counter = 0
+      blocks.each do |block|
+        next unless %i[at image shape].include?(block[:type])
+        attrs = block[:attrs] or next
+        fragment = attrs.delete(:fragment) || attrs.delete('fragment')
+        next unless fragment
+        block[:fragment] = fragment.to_s
+        unless attrs[:id] || attrs['id']
+          # Match the attr's existing key style — `:at` uses symbols,
+          # `:image` and `:shape` use strings (their parsers run
+          # `transform_keys(&:to_s)`).
+          key = block[:type] == :at ? :id : 'id'
+          attrs[key] = "__frag_#{counter}"
+          counter += 1
+        end
+      end
+    end
+
+    # Pull a trailing IAL block off an h1's content. Accepted spellings:
+    #   `Title {layout=name}`     — plain HTML-attr style
+    #   `Title {:layout=name}`    — kramdown IAL (leading colon marker)
+    #   `Title {layout: name}`    — YAML / JSON flow style (colon separator)
+    # `=` and `:` are interchangeable separators. Values can be unquoted,
+    # single-quoted, or double-quoted; unquoted excludes `,` and `}` so
+    # multi-attr forms like `{layout: two-column, foo: bar}` parse cleanly.
+    # If no key=value pairs are found inside the braces we leave the title
+    # untouched — `# What about {curlies}?` shouldn't be munched.
+    def extract_h1_ial(content)
+      return [content, {}] unless content =~ /\A(.*?)\s*\{([^}]*)\}\s*\z/
+      body  = Regexp.last_match(1)
+      inner = Regexp.last_match(2)
+
+      attrs = parse_ial_attrs(inner)
+      return [content, {}] if attrs.empty?
+      [body, attrs]
+    end
+
+    # Scan the inside of an IAL brace block for key=value / key: value
+    # pairs and return a symbol-keyed hash. Accepts quoted (single /
+    # double) and unquoted values; ignores a leading kramdown `:` so
+    # `{:layout=name}` and `{layout=name}` parse the same. Empty inner
+    # → {} (caller decides whether that's a parse failure or a no-op).
+    def parse_ial_attrs(inner)
+      stripped = inner.to_s.sub(/\A:?\s*/, '')
+      attrs = {}
+      stripped.scan(/(\w+)\s*[=:]\s*(?:"([^"]*)"|'([^']*)'|([^\s=:<>"',}]+))/) do |key, dq, sq, uq|
+        attrs[key.to_sym] = dq || sq || uq
+      end
+      attrs
     end
 
     # HTML4-style <font face="..." size="..." color="..."> attributes.
@@ -275,18 +490,71 @@ module Przn
       attrs.slice(:face, :size, :color)
     end
 
+    # Parse a code-fence `lines=` spec into an array of line-number Sets
+    # — one Set per pipe-separated step group. Inside a group, single
+    # integers and `a-b` ranges separate by commas (quoted IAL value
+    # required when commas are present, since `,` is the multi-attr
+    # separator at the IAL level). Returns nil for malformed input so a
+    # typo in the deck doesn't crash parsing.
+    #
+    #   "1-2|3|4"           → [Set[1, 2], Set[3], Set[4]]
+    #   "1-2,4|3"           → [Set[1, 2, 4], Set[3]]
+    #   "all" / "" / garbage → nil
+    def parse_line_steps(spec)
+      return nil if spec.nil?
+      str = spec.to_s.strip
+      return nil if str.empty? || str == 'all' || str == '*'
+
+      groups = str.split('|').map do |group|
+        set = group.split(',').each_with_object(Set.new) do |chunk, acc|
+          chunk = chunk.strip
+          next if chunk.empty?
+          if (m = chunk.match(/\A(\d+)\s*-\s*(\d+)\z/))
+            lo, hi = m[1].to_i, m[2].to_i
+            (lo..hi).each { |n| acc << n }
+          elsif chunk =~ /\A\d+\z/
+            acc << chunk.to_i
+          else
+            return nil
+          end
+        end
+        return nil if set.empty?
+        set
+      end
+      groups.empty? ? nil : groups
+    end
+
     # Generic attribute scanner — three value forms accepted:
     #   key="value"   key='value'   key=bareword
     # Returns a hash with symbolized keys. Doesn't validate which keys
     # are allowed; callers slice.
     def parse_xml_attrs(str)
       attrs = {}
-      str.scan(/(\w+)=(?:"([^"]*)"|'([^']*)'|([^\s=<>"'`]+))/) do |key, dq, sq, uq|
+      str.scan(/([\w-]+)=(?:"([^"]*)"|'([^']*)'|([^\s=<>"'`]+))/) do |key, dq, sq, uq|
         attrs[key.to_sym] = dq || sq || uq
       end
       attrs
     end
 
+    # Parse a `duration=` value off `<action>` into milliseconds as a
+    # Float. Accepts:
+    #   "500ms"  → 500.0
+    #   "0.5s"   →  500.0
+    #   "500"    → 500.0   (unit-less = ms)
+    # Returns nil for anything unparseable so a typo lets the action
+    # quietly fall back to the snap (v2) behavior.
+    def parse_duration_ms(raw)
+      return nil if raw.nil?
+      s = raw.to_s.strip
+      if (m = s.match(/\A(\d+(?:\.\d+)?)ms\z/))
+        m[1].to_f
+      elsif (m = s.match(/\A(\d+(?:\.\d+)?)s\z/))
+        m[1].to_f * 1000.0
+      elsif (m = s.match(/\A(\d+(?:\.\d+)?)\z/))
+        m[1].to_f
+      end
+    end
+
     def parse_image_attrs(str, attrs)
       str = str.sub(/\A:?\s*/, '')
       str.scan(/([\w-]+)=['"]([^'"]*)['"]/) do |key, value|
@@ -327,20 +595,33 @@ module Przn
       scanner = StringScanner.new(text)
 
       until scanner.eos?
-        if scanner.scan(/\{::tag\s+name="([^"]+)"\}(.*?)\{:\/tag\}/)
-          segments << [:tag, scanner[2], scanner[1]]
-        elsif scanner.scan(/<size=([^>\s]+)>(.*?)<\/size>/)
-          segments << [:tag, scanner[2], scanner[1]]
+        if scanner.scan(/<size=(?:"([^"]*)"|'([^']*)'|([^>\s]+))>(.*?)<\/size>/)
+          value = scanner[1] || scanner[2] || scanner[3]
+          push_with_breaks(segments, scanner[4]) { |chunk| [:tag, chunk, value] }
+        elsif scanner.scan(/<color=(?:"([^"]*)"|'([^']*)'|([^>\s]+))>(.*?)<\/color>/)
+          value = scanner[1] || scanner[2] || scanner[3]
+          push_with_breaks(segments, scanner[4]) { |chunk| [:tag, chunk, value] }
+        elsif scanner.scan(/\{::tag\s+name="([^"]+)"\}(.*?)\{:\/tag\}/)
+          # Rabbit-compatible kramdown spelling; covers both size and color.
+          push_with_breaks(segments, scanner[2]) { |chunk| [:tag, chunk, scanner[1]] }
         elsif scanner.scan(%r{<font((?:\s+#{ATTR_RE_SRC})+)\s*>(.*?)</font>}o)
-          segments << [:font, scanner[2], parse_font_attrs(scanner[1])]
+          font_attrs = parse_font_attrs(scanner[1])
+          push_with_breaks(segments, scanner[2]) { |chunk| [:font, chunk, font_attrs] }
         elsif scanner.scan(%r{\{::font((?:\s+#{ATTR_RE_SRC})+)\}(.*?)\{:/font\}}o)
-          segments << [:font, scanner[2], parse_font_attrs(scanner[1])]
-        elsif scanner.scan(/\{::note\}(.*?)\{:\/note\}/)
-          segments << [:note, scanner[1]]
+          font_attrs = parse_font_attrs(scanner[1])
+          push_with_breaks(segments, scanner[2]) { |chunk| [:font, chunk, font_attrs] }
         elsif scanner.scan(/<note>(.*?)<\/note>/)
-          segments << [:note, scanner[1]]
-        elsif scanner.scan('{::wait/}') || scanner.scan(/<wait\s*\/>/)
+          push_with_breaks(segments, scanner[1]) { |chunk| [:note, chunk] }
+        elsif scanner.scan(/\{::note\}(.*?)\{:\/note\}/)
+          push_with_breaks(segments, scanner[1]) { |chunk| [:note, chunk] }
+        elsif scanner.scan(/<wait\s*\/>/) || scanner.scan('{::wait/}')
           # skip wait markers in inline text
+        elsif scanner.scan(/<br\s*\/?>/i)
+          # Force a line break inside the current paragraph. All three
+          # spellings — `<br>`, `<br/>`, `<br />` — collapse to a
+          # `:break` sentinel that wrap_segments closes the current
+          # line on.
+          segments << [:break]
         elsif scanner.scan('&lt;')
           segments << [:text, '<']
         elsif scanner.scan('&gt;')
@@ -353,10 +634,17 @@ module Przn
           segments << [:bold, scanner[1]]
         elsif scanner.scan(/\*(.+?)\*/)
           segments << [:italic, scanner[1]]
+        # CommonMark spelling of bold / italic via underscores. Word-boundary
+        # guards (`(?<!\w)` / `(?!\w)`) keep `snake_case` and `foo__bar__baz`
+        # identifiers literal — only flanking underscores count.
+        elsif scanner.scan(/(?<!\w)__(.+?)__(?!\w)/)
+          segments << [:bold, scanner[1]]
+        elsif scanner.scan(/(?<!\w)_(.+?)_(?!\w)/)
+          segments << [:italic, scanner[1]]
         elsif scanner.scan(/~~(.+?)~~/)
           segments << [:strikethrough, scanner[1]]
         else
-          segments << [:text, scanner.scan(/[^`*~{<&]+|./)]
+          segments << [:text, scanner.scan(/[^`*~_{<&]+|./)]
         end
       end
 
@@ -376,5 +664,29 @@ module Przn
         end
       end
     end
+
+    # Push a styled segment to `segments`, splitting its inner content
+    # on `<br>` so a `<br>` written inside a `<size>` / `<color>` /
+    # `<font>` / `<note>` etc. wrapper closes the current line the same
+    # way it would inside plain text. Without this, the `.*?` inside
+    # the wrapper regex captures `<br>` literally and the styled
+    # segment carries it as text.
+    # Leading `<wait/>` (or `{::wait/}`) on a list item or paragraph.
+    # When matched, mutate the source text to drop the marker plus any
+    # trailing whitespace before the real content; callers attach a
+    # step-boundary flag to the surrounding block.
+    LEADING_WAIT_RE = %r{\A(?:<wait\s*/>|<wait>\s*</wait>|\{::wait/\})\s*}
+    def strip_leading_wait!(text)
+      !!text.sub!(LEADING_WAIT_RE, '')
+    end
+
+    BR_RE = /<br\s*\/?>/i
+    def push_with_breaks(segments, content)
+      chunks = content.split(BR_RE, -1)
+      chunks.each_with_index do |chunk, i|
+        segments << yield(chunk) unless chunk.empty?
+        segments << [:break] if i < chunks.size - 1
+      end
+    end
   end
 end