mdom 0.2.0 → 0.4.0

data/lib/mdom/builder.rb

@@ -1,271 +1,610 @@
 # frozen_string_literal: true
 
+require_relative "error"
+require_relative "markdown_serializer"
+require_relative "node/inline_nodes"
+require_relative "node/nodes"
+
 module MDOM
-  # A builder (DSL) for constructing MDOM trees programmatically, as an
-  # alternative to parsing Markdown text.
+  # 文档构造 DSL（docs/IMPLEMENTATION.md §4.3、§4.4）。
+  #
+  # **排版**：节点挂到「当前容器」，也就是*游标栈*的栈顶。块方法进入一个新容器、
+  # 退出时恢复，嵌套调用因此自然形成层级。
+  #
+  # **嵌入**：+render+ 是嵌入代码进入文档树的唯一通道（CSM §3.3）。它的插入位置
+  # 就是调用位置——不需要槽位 id、回填，也不需要「0 个消失 / n 个展开」的规则。
   #
-  # Every method both appends the constructed node to the node currently being
-  # built and returns the builder itself, so calls chain. Blocks nest: while a
-  # block runs, the node it creates becomes the builder's current target, and
-  # the previous target is restored when the block returns.
+  # **当前文档**：`值.render` 与求值作用域里的裸 `render` 都要知道「往哪篇文档挂」。
+  # 载体是类级的 +Builder.current+（一个文档栈）：+Builder.new+ 入栈、+to_document+
+  # 出栈，+Builder.with+ 提供显式作用域。类实例变量在 **Ractor** 之间天然隔离，所以
+  # CRuby 上的并行用 Ractor；`Thread` 并行会串上下文，不支持（docs/IMPLEMENTATION.md
+  # §5.1、§8.1 #5）。
   #
-  #   doc = MDOM.build do |b|
-  #     b.h1 "Title"
-  #     b.p "A paragraph with *emphasis*."
-  #     b.list do
-  #       b.item "one"
-  #       b.item "two"
+  # **并发**：+render+ 内部持一把互斥锁（CSM §3.3），只保证结构不被撕裂、不保证挂载
+  # 位置；mruby 的默认构建没有 `Mutex`，此时退化为无锁。
+  #
+  #   doc = MDOM::Builder.build do |b|
+  #     b.heading(1, "标题")
+  #     b.paragraph("正文 *强调*。")
+  #     b.list do |l|
+  #       l.item "一"
+  #       l.item "二"
   #     end
   #   end
-  #   doc.to_markdown
   #
-  # String arguments to block- and inline-level methods are run through the
-  # inline parser, so *emphasis*, **strong**, `code`, [links](url) and
-  # ![images](src) are recognised. Use the explicit inline methods
-  # (+em+, +strong+, +code_span+, +link+, +image+) when you need an exact
-  # structure; their string arguments are treated as literal text unless you
-  # nest an explicit method inside a block.
+  # 块按**显式传参**取 builder（CSM §5.2.1）：块参数就是 builder 自身，不用
+  # +instance_eval+，因此不依赖 metaprog。
+  #
+  # 依赖边界（docs/IMPLEMENTATION.md §1.1）：本文件属 **builder 侧**——只用 mruby
+  # 子集、不 +require+ 任何**外部 gem**。行内内容的**结构化构造**（节点参数 / 块）
+  # 完全不需要解析器，因此既不需要 prism 也不依赖宿主的配置；只有字符串参数这一
+  # 便利形式需要行内解析器，且它是**注入**的：默认在首次需要时读取
+  # +MDOM::InlineParser+ / +MDOM::Parser+ 常量，宿主可以替换成别的实现。
+  #
+  # 块形式的行内内容会用 +MDOM::MarkdownSerializer+ 重建 +attributes[:text]+ 原文
+  # 缓存（`text` / `cite` 这类读取靠它）。它与本文件同属 builder 侧、零 gem 依赖，
+  # 所以是本文件唯一的 +require+。
   class Builder
-    # Build a document with +block+ (or a nested block passed to an explicit
-    # +builder+) and return it. See MDOM.build.
+    # 能直接收下行内节点的容器：内容策略为 **PHRASING** 的块
+    # （`docs/CSM.md` 元素表，与 Parser 的边界一致）。
+    PHRASING_CONTAINERS = %i[paragraph heading term cite table_header_cell table_cell].freeze
+
+    # +render+ 的互斥锁类（CSM §3.3）。mruby 的默认构建既没有 `Thread` 也没有
+    # `Mutex`（属外部 mrbgem），此时为 +nil+ ⇒ 退化为无锁。
+    LOCK_CLASS = defined?(Mutex) ? Mutex : nil
+
+    # 构造一个文档并返回它。块参数是 builder，见类说明。
     def self.build(builder = new, &block)
       builder.document(&block)
       builder.to_document
     end
 
-    def initialize
-      @document = Document.new
+    # -- 当前文档 -------------------------------------------------------------
+
+    # 「当前文档」的 builder；没有正在渲染的文档时为 +nil+（CSM §3.3）。
+    def self.current
+      (@current ||= []).last
+    end
+
+    # 把 +builder+ 设为当前文档。+new+ 会自动入栈，一般不必直接调用。
+    def self.enter(builder)
+      (@current ||= []).push(builder)
+      builder
+    end
+
+    # 退出当前文档。只在栈顶是 +builder+ 时出栈——因此可以反复调用（幂等），
+    # +to_document+ 被读多次也不会把栈弄乱。
+    def self.leave(builder)
+      stack = @current
+      stack.pop if stack && stack.last.equal?(builder)
+      builder
+    end
+
+    # 显式作用域：块内 +current+ 指向 +builder+，退出时恢复。
+    def self.with(builder)
+      enter(builder)
+      yield
+    ensure
+      leave(builder)
+    end
+
+    # +document+ 省略时新建一个空文档。
+    #
+    # +inline_parser+ / +parser+ / +text_serializer+ 省略时，在首次需要时读取
+    # +MDOM::InlineParser+ / +MDOM::Parser+ / +MDOM::MarkdownSerializer+ 常量。
+    def initialize(document: nil, inline_parser: nil, parser: nil, text_serializer: nil)
+      @document = document || Node::Document.new
       @stack = [@document]
+      @inline_parser = inline_parser
+      @parser = parser
+      @text_serializer = text_serializer
+      @lock = LOCK_CLASS&.new
+      Builder.enter(self)
     end
 
-    # -- block level ---------------------------------------------------------
+    # -- 结果 -----------------------------------------------------------------
+
+    # 正在构造的文档（根节点）。同时把它从「当前文档」栈上退出。
+    def to_document
+      Builder.leave(self)
+      @document
+    end
+    alias finish to_document
 
-    # Build a document (the root node). With a block, the block is evaluated
-    # against this builder and its content is added to the root document.
-    # Returns the builder; use +to_document+ / +finish+ for the tree.
+    # 把块的内容挂到文档根下。
     def document(&block)
-      push(@document) { instance_eval(&block) } if block
+      within(@document, &block) if block
       self
     end
 
-    # An ATX heading. +level+ defaults to 1; the remaining arguments are the
-    # heading's inline content.
-    def heading(level = 1, *parts, **attributes)
-      node = Heading.new(level, children: inline_nodes(parts), attributes: attributes)
+    # -- 块级 -----------------------------------------------------------------
+
+    # ATX 标题。+level+ 为 1–6，其余参数是行内内容。+closed+ 表示以等长 `#` 收尾
+    # （CSM §1.2 的 `<hgroup>` 用法）。
+    def heading(level = 1, *parts, closed: false, &block)
+      node = Node::Heading.new(level, closed: closed)
       append(node)
+      fill_inline(node, parts, &block)
+      self
     end
 
-    def h1(*parts, **attributes) = heading(1, *parts, **attributes)
-    def h2(*parts, **attributes) = heading(2, *parts, **attributes)
-    def h3(*parts, **attributes) = heading(3, *parts, **attributes)
-    def h4(*parts, **attributes) = heading(4, *parts, **attributes)
-    def h5(*parts, **attributes) = heading(5, *parts, **attributes)
-    def h6(*parts, **attributes) = heading(6, *parts, **attributes)
+    def h1(*parts, closed: false, &block) = heading(1, *parts, closed: closed, &block)
+    def h2(*parts, closed: false, &block) = heading(2, *parts, closed: closed, &block)
+    def h3(*parts, closed: false, &block) = heading(3, *parts, closed: closed, &block)
+    def h4(*parts, closed: false, &block) = heading(4, *parts, closed: closed, &block)
+    def h5(*parts, closed: false, &block) = heading(5, *parts, closed: closed, &block)
+    def h6(*parts, closed: false, &block) = heading(6, *parts, closed: closed, &block)
 
-    # A paragraph. With a block, the block's inline nodes become its children.
+    # 段落。字符串参数按 CSM 行内语法解析。
     def paragraph(*parts, &block)
-      node = Paragraph.new
-      build_inline(node, parts, &block)
+      node = Node::Paragraph.new
       append(node)
+      fill_inline(node, parts, &block)
+      self
     end
     alias p paragraph
 
-    # A list. +ordered: true+ produces an ordered list; +start:+ sets its first
-    # number. Without a block, +items+ are wrapped into single-paragraph list
-    # items.
-    def list(*items, ordered: false, tight: true, start: nil, &block)
-      node = List.new(ordered: ordered, tight: tight, start: start)
+    # 列表。+ordered+: 有序列表；+task+: 任务列表。无块时 +items+ 逐个成为列表项。
+    def list(*items, ordered: false, task: false, marker: nil, &block)
+      node = Node::List.new(ordered: ordered, task: task, marker: marker || (ordered ? "1." : "-"))
+      append(node)
       if block
-        push(node) { instance_eval(&block) }
+        within(node, &block)
       else
-        items.each { node.append(ListItem.new(children: [Paragraph.new])) }
-        refill_items(node, items)
+        item_marker = node.attributes[:marker]
+        within(node) do
+          items.each { |text| item(text, marker: item_marker, task: task, checked: task ? false : nil) }
+        end
       end
-      append(node)
+      self
     end
 
-    # An unordered list, as a shorthand for +list(ordered: false)+.
     def ul(*items, &block) = list(*items, ordered: false, &block)
-    # An ordered list, as a shorthand for +list(ordered: true)+.
-    def ol(*items, start: nil, &block) = list(*items, ordered: true, start: start, &block)
-
-    # A list item. Without a block, +parts+ become a single paragraph.
-    def item(*parts, task: nil, checked: false, &block)
-      node = ListItem.new
-      unless task.nil?
-        node.attributes[:task] = true
-        node.attributes[:checked] = checked ? true : false
-      end
-      if block
-        push(node) { instance_eval(&block) }
-      elsif !parts.empty?
-        node.append(Paragraph.new(children: inline_nodes(parts)))
-      end
+    def ol(*items, &block) = list(*items, ordered: true, &block)
+
+    # 列表项。+parts+ 各自成为一个段落（`li` 的内容策略是 FLOW，见 CSM 元素表）；
+    # 有块时在段落之后继续嵌套。省略 +marker+ 时沿用最近一层列表的标记形式；
+    # 省略 +task+ 时沿用最近一层列表的任务状态。
+    def item(*parts, marker: nil, task: nil, checked: nil, &block)
+      list = current_list
+      task = list.task? if task.nil? && list
+      task = false if task.nil?
+      list.attributes[:task] = true if task && list
+      checked = false if task && checked.nil?
+
+      node = Node::ListItem.new(marker: marker || current_list_marker, task: task, checked: checked)
       append(node)
+      fill_flow(node, parts, &block)
+      self
     end
     alias li item
 
-    # A task list item (+checked+ marks it done).
+    # 任务列表项。
     def task(checked, *parts, &block)
       item(*parts, task: true, checked: checked, &block)
     end
 
-    # A blockquote. +parts+/+block+ are parsed as block content.
-    def blockquote(*parts, &block)
-      node = Blockquote.new
-      build_blocks(node, parts, &block)
+    # 块引用。+parts+ 各自成为一个段落（FLOW 内容）；+cite+ 对应 `>-` 收尾。
+    def blockquote(*parts, cite: nil, &block)
+      node = Node::Blockquote.new
       append(node)
+      fill_flow(node, parts, &block)
+      append_cite(node, cite)
+      self
     end
     alias quote blockquote
 
-    # A fenced code block. +lang+ sets the info string.
-    def code_block(literal, lang: nil, fenced: true)
-      append(CodeBlock.new(literal.to_s, lang: lang, fenced: fenced))
+    # 引用来源（`<cite>`）。字符串参数按 CSM 行内语法解析。
+    def cite(*parts, &block)
+      node = Node::Cite.new(parts.grep(String).join)
+      append(node)
+      fill_inline(node, parts, &block)
+      self
     end
 
-    # A horizontal rule.
-    def hrule(*, **)
-      append(Hrule.new)
+    # 围栏代码块。+code+ 按字面收下。
+    def code_block(code, lang: nil, params: nil, fence: 3)
+      append(Node::CodeBlock.new(code.to_s, lang: lang, params: params, fence: fence))
+      self
+    end
+
+    # 块级公式（`$$…$$`）。+tex+ 按字面收下（CSM §1.11）。
+    def math_block(tex)
+      append(Node::MathBlock.new(tex.to_s))
+      self
+    end
+
+    # 表格（纯结构，CSM §1.12）：块内给出若干 #row。
+    def table(&block)
+      node = Node::Table.new
+      append(node)
+      within(node, &block) if block
+      self
+    end
+
+    # 表格行：块内给出若干单元格。
+    def row(&block)
+      node = Node::TableRow.new
+      append(node)
+      within(node, &block) if block
+      self
+    end
+
+    # 表头单元格（`th`）。+align+ 为 +:left+ / +:center+ / +:right+，省略为默认对齐。
+    # 内容策略是 PHRASING（CSM 元素表），因此正文与 #paragraph 一样可以给节点
+    # 参数或块——`cell` 从来不只是「一个字符串」。
+    def header_cell(*parts, align: nil, &block)
+      append_cell(Node::TableHeaderCell, parts, align, &block)
+    end
+
+    # 数据单元格（`td`）。+align+ 同上。
+    def cell(*parts, align: nil, &block)
+      append_cell(Node::TableCell, parts, align, &block)
+    end
+
+    # 分隔线。
+    def hrule
+      append(Node::Hrule.new)
+      self
     end
     alias hr hrule
 
-    # -- inline --------------------------------------------------------------
+    # 节块（`<div>`）。
+    def division(&block)
+      node = Node::Div.new
+      append(node)
+      within(node, &block) if block
+      self
+    end
+    alias div division
 
-    # Emphasis (*x*). With a block, nested explicit inline methods are used;
-    # otherwise string arguments are parsed as inline content. Appends to the
-    # current target and returns the node.
-    def em(*parts, &block)
-      node = Emphasis.new
-      build_inline(node, parts, &block)
+    # 定义列表：块内依次给出 #term 与 #definition。
+    def definition_list(&block)
+      node = Node::DefinitionList.new
       append(node)
-      node
+      within(node, &block) if block
+      self
+    end
+    alias dl definition_list
+
+    # 定义术语（`<dt>`）。字符串参数按 CSM 行内语法解析。
+    def term(*parts, &block)
+      node = Node::Term.new(parts.grep(String).join)
+      append(node)
+      fill_inline(node, parts, &block)
+      self
+    end
+
+    # 定义内容（`<dd>`）。+parts+ 各自成为一个段落（FLOW 内容）。
+    def definition(*parts, &block)
+      node = Node::Definition.new
+      append(node)
+      fill_flow(node, parts, &block)
+      self
+    end
+
+    # -- 行内 -----------------------------------------------------------------
+    #
+    # 每个 CSM 行内构造都有对应的构造方法。**结构化构造**是首选形式：内容给节点
+    # 参数或块，产物因此不依赖任何解析器；字符串参数是给手写用的便利形式，它需要
+    # 一个行内解析器（注入，或 `require "mdom/inline_parser"`）。
+
+    # `*斜体*` → `<em>`。
+    def em(*parts, &block)
+      inline_node(Node::Emphasis.new, parts, &block)
     end
     alias emphasis em
 
-    # Strong (**x**).
+    # `**加粗**` → `<strong>`。
     def strong(*parts, &block)
-      node = Strong.new
-      build_inline(node, parts, &block)
-      append(node)
-      node
+      inline_node(Node::Strong.new, parts, &block)
     end
 
-    # A code span (`x`). The argument is literal.
+    # `` `代码` `` → `<code>`。参数按字面。
     def code_span(value)
-      append(Code.new(value.to_s))
+      inline_node(Node::CodeSpan.new(value.to_s))
     end
 
-    # A link. Without a block the label is the literal +*label+ parts; with a
-    # block, nested explicit inline methods build the label.
-    def link(destination, *label, title: nil, &block)
-      node = Link.new(destination, title: title)
-      build_inline(node, label, &block)
-      append(node)
-      node
+    # `~~文本~~` → `<del>`。
+    def del(*parts, &block)
+      inline_node(Node::Del.new, parts, &block)
     end
 
-    # An image.
-    def image(destination, alt: nil, title: nil)
-      append(Image.new(destination, alt: alt, title: title))
+    # `~+文本+~` → `<ins>`。
+    def ins(*parts, &block)
+      inline_node(Node::Ins.new, parts, &block)
     end
 
-    # A soft line break.
-    def softbreak
-      append(Softbreak.new)
+    # 行内纯文本。参数按字面。
+    def text(value = "")
+      inline_node(Node::Text.new(value.to_s))
     end
 
-    # A hard line break (two trailing spaces).
-    def hardbreak
-      append(Hardbreak.new)
+    # `[标签](uri "title")` → `<a>`。
+    def link(uri, *label, title: nil, &block)
+      inline_node(Node::Link.new(uri, title: title), label, &block)
     end
 
-    # -- results -------------------------------------------------------------
+    # `[文本](@uri)` → `<q>`。
+    def inline_quote(uri, *parts, &block)
+      inline_node(Node::InlineQuote.new(uri), parts, &block)
+    end
 
-    # The document built so far.
-    def to_document
-      @document
+    # `[[target|label]]` → `<a>`。+label+ 省略时显示 +target+，行内内容也因此取
+    # +target+（与解析侧一致）。
+    def wiki_link(target, label = nil, *parts, &block)
+      literal_inline(Node::WikiLink.new(target, label: label), parts, label || target, &block)
+    end
+
+    # `@user` / `@project:x` → `<a>`。+kind+ 是 `:` 前的作用域。
+    def mention(name, kind: nil)
+      inline_node(Node::Mention.new(name.to_s, kind: kind))
+    end
+
+    # `![alt](uri "title")` → `<img>`（空元素）。+alt+ 是替代文本原文，行内内容
+    # （含 `#{}`）由 +parts+ / 块给出；省略时按**字面**解析 +alt+（CSM §2.3）。
+    def image(uri, *parts, alt: nil, title: nil, &block)
+      alt = alt&.to_s
+      literal_inline(Node::Image.new(uri, alt: alt, title: title), parts, alt, &block)
+    end
+
+    # `[=m/n]` → `<meter>`（CSM §1.10）。+value+ / +max+ 保持原文，行内内容省略时
+    # 按**字面**解析 `m/n`。
+    def meter(value, max, *parts, &block)
+      literal_inline(Node::Meter.new(value.to_s, max.to_s), parts, "#{value}/#{max}", &block)
+    end
+
+    # `[->m/n]` → `<progress>`。语义同 #meter。
+    def progress(value, max, *parts, &block)
+      literal_inline(Node::Progress.new(value.to_s, max.to_s), parts, "#{value}/#{max}", &block)
+    end
+
+    # `$\TeX$` → 行内 `<span class="math">`（CSM §1.11）。+tex+ 保持原文，行内内容
+    # 省略时按**字面**解析 +tex+。
+    def math(tex = "", *parts, &block)
+      literal_inline(Node::Math.new(tex.to_s), parts, tex.to_s, &block)
     end
-    alias finish to_document
 
-    # Serialize the document built so far to Markdown.
-    def to_markdown
-      @document.to_markdown
+    # 行尾 `\` → `<br>`。
+    def hardbreak
+      inline_node(Node::HardBreak.new)
     end
 
-    # A human-readable tree rendering of the document built so far.
-    def inspect
-      to_document.inspect
+    # `#{expr}`（CSM §3.13）。无块时构造**未求值**的插值节点，保存表达式原文
+    # （安全渲染用）；有块时块的值按 #render 的分派表插入当前位置（不安全渲染用，
+    # 此时表达式由 Ruby 求值）。
+    def interpolation(expr = nil, &block)
+      return render(block.call) if block
+
+      inline_node(Node::Interpolation.new(expr.to_s))
+    end
+
+    # -- 注入通道 -------------------------------------------------------------
+
+    # 嵌入代码进入文档树的唯一通道（CSM §3.3）：值挂在**当前容器**，插入位置就是
+    # 调用位置。`render` 是排版指令的一种，与 `heading` / `paragraph` / `list` 同级。
+    #
+    # 值按类型分派，**包装方式取决于当前容器**（行内容器收行内节点，块级容器收块）：
+    #
+    # | 值 | 行内容器中 | 块级容器中 |
+    # |----|-----------|-----------|
+    # | `nil` | 忽略 | 忽略 |
+    # | 节点 | 直接插入（自动从原父脱离） | 同左 |
+    # | 字符串 | 文本节点 | 段落 |
+    # | `Array` / `Enumerable` | 逐项递归 | 逐项递归 |
+    # | 其它 | `to_s` 后同上 | `to_s` 后同上 |
+    #
+    # +parse: true+ 时字符串按 CSM 递归解析，解析出的**子节点**逐个插入——不再按
+    # 容器包装，因为解析结果自带块级结构。
+    def render(value, parse: false)
+      if @lock
+        @lock.synchronize { emit(value, parse) }
+      else
+        emit(value, parse)
+      end
+      self
     end
 
     private
 
-    # Append +node+ to the current target and return the builder, so both
-    # +b.p "x"+ chains and top-level calls accumulate in the document.
-    def append(node)
-      @stack.last.append(node)
+    # 把 +>-+ 的出处作为 +Node::Cite+ 挂到引用末尾；正文按行内语法解析。
+    def append_cite(node, cite)
+      return if cite.nil?
+
+      source = Node::Cite.new
+      node << source
+      fill_inline(source, [cite.to_s])
+    end
+
+    # 单元格：正文是行内内容（PHRASING），填充方式与段落一致。
+    def append_cell(klass, parts, align, &block)
+      node = klass.new("", align: align)
+      append(node)
+      fill_inline(node, parts, &block)
       self
     end
 
-    # Make +node+ the current target while the block runs, then restore.
-    def push(node)
+    # 分派一个值。见 #render 的说明表。
+    def emit(value, parse)
+      case value
+      when nil then nil
+      when Node::BaseNode then @stack.last << value
+      when String then emit_string(value, parse)
+      when Enumerable then value.each { |item| emit(item, parse) }
+      else emit_string(value.to_s, parse)
+      end
+    end
+
+    def emit_string(text, parse)
+      return attach_tree(text) if parse
+      return @stack.last << Node::Text.new(text) if inline_container?
+
+      # 块级容器收不下裸文本，包成段落。
+      paragraph = Node::Paragraph.new(text)
+      paragraph << Node::Text.new(text)
+      @stack.last << paragraph
+    end
+
+    # 当前容器能否直接收下行内节点。
+    def inline_container?
+      PHRASING_CONTAINERS.include?(@stack.last.type)
+    end
+
+    # 进入 +node+ 作为当前容器，块结束后恢复。
+    def within(node)
       @stack.push(node)
-      yield
+      yield self
     ensure
       @stack.pop
     end
 
-    # Fill +node+ with inline content: a block plus direct parts, or the parts
-    # alone. With a block, parts are rejected (there is only one content site).
-    def build_inline(node, parts, &block)
+    def append(node)
+      @stack.last << node
+      node
+    end
+
+    # 最近一层列表，没有则 +nil+。
+    def current_list
+      @stack.reverse.find { |node| node.is_a?(Node::List) }
+    end
+
+    # 最近一层列表的标记形式（有序列表得到 `N.`），没有则 `-`。
+    def current_list_marker
+      list = current_list
+      list ? list.attributes[:marker] : "-"
+    end
+
+    # 解析 +source+，把结果的**子节点**逐个挂到当前容器（不是挂整个 Document）。
+    def attach_tree(source)
+      parser.parse(source).children.dup.each { |child| @stack.last << child }
+    end
+
+    # 行内节点方法：挂载后返回节点本身，便于 `b.p { b.em "x" }` 这样的显式构造。
+    def inline_node(node, parts = [], &block)
+      append(node)
+      fill_inline(node, parts, &block)
+      node
+    end
+
+    # 填充行内内容：给块就用块（进入节点作为容器），否则填充 +parts+（节点原样
+    # 收下，字符串交给行内解析器）。
+    def fill_inline(node, parts, &block)
       if block
         raise ArgumentError, "cannot combine inline arguments with a block" unless parts.empty?
 
-        push(node) { instance_eval(&block) }
-      else
-        node.append_parts(inline_nodes(parts))
+        within(node, &block)
+        return cache_text(node)
       end
+
+      fill_inline_parts(node, parts)
     end
 
-    # Fill +node+ with block content: a block plus direct parts (paragraphs),
-    # or the parts alone.
-    def build_blocks(node, parts, &block)
-      parts.each { |part| node.append(Paragraph.new(children: inline_nodes([part]))) }
-      push(node) { instance_eval(&block) } if block
+    # 行内子节点挂好后，用（可注入的）序列化器重建 +attributes[:text]+ 原文缓存。
+    #
+    # 块形式的内容没有原文可存（内容本身就是节点），所以从子节点重建——`text` /
+    # `cite` 这类读取因此对 builder 构造的节点同样成立。只对 PHRASING 容器做：
+    # 行内格式节点（`em` / `strong` …）不需要原文缓存。
+    def cache_text(node)
+      return node unless PHRASING_CONTAINERS.include?(node.type)
+      return node unless node.attributes[:text].to_s.empty? # 解析期原文优先
+
+      serializer = text_serializer.new
+      node.attributes[:text] = node.children.map { |child| serializer.serialize(child) }.join
+      node
     end
 
-    # Build the item paragraphs for a block-less +list(*items)+ call.
-    def refill_items(list_node, items)
-      list_node.children.each_with_index do |item_node, idx|
-        item_node.children.first.append_parts(inline_nodes([items[idx]]))
-      end
+    # 「字段 + 行内内容」型行内节点：内容给 +parts+ / 块，否则把 +literal+ 按字面
+    # 解析成子节点（与解析侧的策略一致）。
+    def literal_inline(node, parts, literal, &block)
+      append(node)
+      return fill_inline(node, parts, &block) if block || !parts.empty?
+
+      fill_inline(node, literal_nodes(literal)) if literal
+      node
+    end
+
+    # 一段原文的**字面**行内节点（只认 `#{}`，不认强调等；CSM §2.3 的字面策略）。
+    def literal_nodes(text)
+      inline_parser.parse(text.to_s, literal: true)
     end
 
-    # Convert arguments into inline nodes: strings are parsed as inline
-    # Markdown, existing nodes pass through (and are detached from any parent).
-    def inline_nodes(parts)
+    # FLOW 容器的填充（CSM 元素表：`blockquote` / `li` / `dd` 的内容策略是 FLOW）：
+    # +parts+ 各自成为一个段落，随后进入块（嵌套的块级子节点）。
+    def fill_flow(node, parts, &block)
+      parts.each { |part| append_paragraph(node, part) }
+      within(node, &block) if block
+      node
+    end
+
+    # 把一个 part 作为段落挂到 +node+ 下：字符串按 CSM 行内语法解析，节点原样收下。
+    def append_paragraph(node, part)
+      paragraph = Node::Paragraph.new
+      node << paragraph
+      return node << part if part.is_a?(Node::BaseNode)
+
+      fill_inline(paragraph, [part.to_s])
+      node
+    end
+
+    # 把 +parts+ 解析成行内节点挂到 +node+。
+    def fill_inline_parts(node, parts)
+      # `text` 保留原文，与 Parser 构造出的节点一致；只有全字符串参数才成立。
+      node.attributes[:text] = parts.join if !parts.empty? && parts.all?(String)
+      inline_parts(parts).each { |part| node << part }
+      node
+    end
+
+    # 把参数转成行内节点：字符串按 CSM 行内语法解析，节点原样收下。
+    def inline_parts(parts)
       parts.flat_map do |part|
-        if part.is_a?(Node)
-          part.remove
-          part
-        else
-          InlineParser.parse(part.to_s)
+        case part
+        when Node::BaseNode then [part]
+        when String then inline_parser.parse(part)
+        else [Node::Text.new(part.to_s)]
         end
       end
     end
-  end
 
-  def self.build(&block)
-    Builder.build(&block)
-  end
+    # 行内解析器（用于字符串参数）：默认取 +MDOM::InlineParser+，本文件不 require 它。
+    def inline_parser
+      @inline_parser ||= MDOM::InlineParser
+    rescue NameError
+      raise ArgumentError,
+            "string arguments need an inline parser: require \"mdom/inline_parser\" or pass inline_parser:"
+    end
 
-  # Adds a batch-append helper to the block/inline nodes that carry inline
-  # content, so the builder can attach parsed parts in one call.
-  module InlineContainer
-    def append_parts(nodes)
-      nodes.each { |node| append(node) }
-      self
+    # 块级解析器（用于 `render(parse: true)`）：默认取 +MDOM::Parser+。
+    def parser
+      @parser ||= MDOM::Parser
+    rescue NameError
+      raise ArgumentError,
+            "render(parse: true) needs a parser: require \"mdom/parser\" or pass parser:"
+    end
+
+    # 原文缓存（块形式的行内内容）用的序列化器：默认 +MDOM::MarkdownSerializer+。
+    # 它与本文件同属 builder 侧（零 gem 依赖），所以是唯一的直接依赖。
+    def text_serializer
+      @text_serializer ||= MarkdownSerializer
     end
   end
+end
 
-  [Paragraph, Emphasis, Strong, Link].each { |klass| klass.include(InlineContainer) }
+# `值.render`（CSM §3.3）：把值交给**当前文档**的 builder。
+#
+# 定义在 `Object` 上，所以 `begin ... end.render` 对任意块值都成立（`String`、
+# `Array`、`nil`……）。代价是给宿主的每个对象都加了 `render`——docs/IMPLEMENTATION.md
+# §5.2 已接受这一点，并说明为什么这是唯一可行的落点。
+class Object
+  # 把值渲染进当前文档；没有正在渲染的文档时抛错。
+  #
+  # 两种写法走同一条路（CSM §3.3）：**给了位置参数就用它，否则用接收者本身**——
+  # 于是块内裸 `render(value)` 与 `值.render` 等价。`render(nil)` 仍然是「渲染 nil」
+  # （按 §3.3 的值分派表被忽略），多余的位置参数由 Ruby 自己报错。
+  def render(value = self, **options)
+    builder = MDOM::Builder.current
+    raise MDOM::Error, "render outside of a document" if builder.nil?
+
+    builder.render(value, **options)
+    self
+  end
 end