mdom 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5fd39950b36dde37a473d2ed62086a94a218bf3d7fc17bfc107fe2b443c2003
-  data.tar.gz: 15d24864d48fe97e4d82e5990f9163578b6a4b55104d195e87c4e24f14d26f1f
+  metadata.gz: 2c46bd566d0a5adabb0b78754b949f0bed6dfa1bf1e1dd09b03a0d3f36ab1e63
+  data.tar.gz: 563befb0a98299ded7d5036d2ce18681a2433bba8a7f213175242c3dd206fa04
 SHA512:
-  metadata.gz: 995dfd2579600430baedb7592b22ef2c94908c2bf3e16b1daa33550f3058d25783275af0237d00e7152876e14156befe18a2894d087f9cc556acdc7fe36f32ad
-  data.tar.gz: f286b92331b99bb57250df4d13ea1d4e5e08dc9020b2c8cb3e90e5f5522430897cf112c0ffce0dd05f280a63de5f560869c8a8dda444946d072a0296977cb0c6
+  metadata.gz: 92de7744eea2e3304013ea24576bdd718df6ee63ce251ce03dce5e675754fca90f6f2f9228e5018d4c830da79d460e018ea9c32ba04603814af1275a5608aa60
+  data.tar.gz: 643519a175794000d681d1efad3cc7a684b6aa8be4983054a0384f16e842942399e1b13c7ec6a63b195cdd72b7fe8db7e0a8786453d9bd26d29f8362ed36b2a0

data/CHANGELOG.md

@@ -0,0 +1,71 @@
+## [Unreleased]
+
+## [0.3.0] - 2026-09-26
+
+从 0.2.0 的「Markdown DOM」重写为「CSM 工具链」：(1) 解析、(2) 翻译、(3)(5)
+`to_markdown`、(6) HTML 序列化四段可用；(4) 执行归宿主一行 `eval`。
+
+### Added
+
+- `MDOM::Hooks` + `Document.register_hook`：钩子 / 回调系统（CSM §5.3）——五个点
+  `:after_parse` / `:before_compile` / `:after_compile` / `:before_serialize` /
+  `:after_serialize`，类级全局与调用时临时两种作用域。
+- `MDOM.compile(source, ...)`：统一入口——(1)(2)(6) 全链路并触发钩子，返回
+  `MDOM::Compiled`（`document` / `ruby` / `html` / `meta`）；`MDOM.parse` 一并接线。
+- `MDOM::Node::Document#meta`：文档级元数据。
+- `MDOM::HtmlSerializer`：(6) AST → HTML（零 gem 依赖）——含 CSM §1.2 的
+  article/section 自动包裹、`hgroup`、WikiLink 的 `known_targets`、未求值嵌入的
+  `csm-ruby` 样式；公式输出 `math` 类元素（TeX 原文，不渲染 SVG）。
+- `MDOM::MarkdownSerializer`：(3)(5) AST → CSM 源——同一方法服务 AST1（保真往返）
+  与 AST2（降级还原）；从节点结构重建、保守转义、按节点深度重建缩进。`node.to_markdown`
+  是便捷入口。`MDOM.compile` 暂不产出 Markdown。
+- `USAGE.md`：使用指南（各阶段 API、可运行示例、配方，含程序化生成目录）。
+
+### Changed
+
+- 解析与翻译按 CSM 重写：`Tokenizer`（表格、块级公式）、`BlockDetector`（Prism）、
+  `Parser`（FLOW / PHRASING 内容策略）、`InlineParser`、`Translator`（`unsafe:` 默认
+  安全，安全时不写嵌入段）、`Builder`（游标栈 + `render` / `值.render` + 「当前文档」）。
+- `lib/mdom.rb` 从脚手架空壳改为真正的入口。
+- `mdom.gemspec`：摘要与描述改为 CSM 工具链（原先还是 0.2.0 的「Markdown DOM」，
+  且声称能序列化回 Markdown）；补上 `prism` 运行时依赖。`Gemfile` 补 `rubocop`
+  （`Rakefile` 一直在 require 它）。
+- `.rubocop.yml`：指标类 cop 改为非闸门（lib 侧是刻意的宽分类器与扫描循环，见该文件
+  注释）；`TargetRubyVersion` 与 gemspec 的 `required_ruby_version` 统一为 3.0。
+- `rake` 默认任务（`test` + `rubocop`）现在全绿。
+
+### Removed
+
+- `MDOM.serialize`：它指向已被移除的 `Serializer`，等 (3) `to_markdown` 落地再恢复。
+- `lib/mdom/scanner.rb`（没有消费者的空壳，块配对与插值边界早已交给 Prism）、
+  `lib/mdom/node.rb` 里零使用的 `ALLOWED_CHILD_TYPES`、空目录 `sig/`。
+
+### Fixed
+
+- 表格：`| a | b |` 行 + 分隔行 → `Table > TableRow > TableHeaderCell` / `TableCell`
+  （`align` 记在单元格上）。
+- 块级公式：单行 `$$…$$` 与 `$$` 独占一行的多行包围式两种写法。
+- 标题收尾的 `#` 只有与引导 `#` **等长**才算闭合。
+- heredoc（`<<~SQL` / `<<-SQL` 等）现在按 CSM §3.12 / 附录 E **明确报错**
+  （`MDOM::UnsupportedHeredocError`），不再被当作普通 Ruby 块收下；左移 `<<`
+  不受影响。
+- 标题锚点与 WikiLink 目标的 slug 统一为**小写**（CSM §2.1 要求 WikiLink 目标不区分
+  大小写），因此 `[[笔记#锚点]]` 能对上标题的 `id`。
+- `InlineParser::ESCAPABLE`：`%w[` * …]` 的首个元素 `\`` 在 `%w` 里其实是**两个
+  字符**（`\` + `` ` ``），于是集合里根本没有反引号，取而代之一个永远匹配不上的双字符
+  项——CSM §3.11 明列可转义的 `` \` `` 一直转不了。已改为 `` ` ``。
+
+## [0.2.0] - 2026-09-10
+
+- Add `MDOM::Builder` and the `MDOM.build` DSL for constructing trees
+  programmatically, with block nesting, chaining and whole-tree return.
+- Fix `ArgumentError: missing keyword: :marker` when serializing a `ListItem`
+  outside of its `List`; `Serializer#serialize` and `Serializer.serialize` now
+  accept a `marker:` keyword (default `"-"`).
+- Fill in real RBS signatures in `sig/mdom.rbs` (previously `module Mdom`
+  scaffolding only).
+- Fix the scaffold test referencing `Mdom::VERSION` instead of `MDOM::VERSION`.
+
+## [0.1.0] - 2026-09-07
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,285 @@
+# mdom
+
+**mdom** 是 [CSM](docs/CSM.md)（Complex Simple Markup）的 Ruby 工具链：把 CSM 文档解析成一棵文档树（AST），再翻译为 Ruby 源码、HTML 或 Markdown。
+
+CSM 把 Markdown 视为 **Ruby 的语法糖**——一份 `.rb.md` 文档既是可读的 Markdown，也是一段可执行的 Ruby 程序：
+
+```markdown
+# 销售报表
+
+~ total = orders.sum(&:amount)
+
+本月合计 #{total} 元。
+```
+
+> **仓库状态**：已从 0.2.0 的「Markdown DOM」重写为「CSM 工具链」。(1) 解析、(2) 翻译、(3)(5) `to_markdown`、(6) HTML 序列化四段可用，入口 `MDOM.parse` / `MDOM.compile` 已接线；(4) 执行归宿主一行 `eval`。见[当前状态](#当前状态)。
+
+## 处理模型
+
+CSM 的处理由六个转换关系定义，围绕**一棵树的两种状态**展开：
+
+```
+         (1) parse              (2) to_ruby
+CSM 源 ───────────> AST1 ──────────────────> Ruby 源
+                     │                          │
+              (3) to_markdown              (4) eval
+                     │                          │
+                     v                          v
+                  CSM 源                    AST2 ──(6) to_html──> HTML
+```
+
+| # | 转换 | 说明 | 状态 |
+|---|------|------|------|
+| (1) | CSM → AST1 | 解析。嵌入部分以**源码原文 + 位置**存于树中，尚未求值 | ✅ 已实现 |
+| (2) | AST1 → Ruby | 翻译。排版变 builder 调用；嵌入块在 `unsafe: true` 下保留为 Ruby | ✅ 已实现 |
+| (3) | AST1 → CSM | `to_markdown`，不执行代码，嵌入部分原样回吐 → 保真往返 | ✅ 已实现 |
+| (4) | Ruby → AST2 | 执行（`eval`）。嵌入部分被替换为求值产出的子树 | ➖ 由宿主 `eval`，mdom 不含求值器 |
+| (5) | AST2 → CSM | `to_markdown`，已无源码，**降级还原** | ✅ 已实现（降级是设计后果） |
+| (6) | AST2 → HTML | `to_html` 序列化（AST1 / AST2 均可） | ✅ 已实现 |
+
+**AST1 与 AST2 是同一棵树类型**，区别只在于是否还残留未求值的嵌入节点。对一棵 AST1 直接 `to_html` 也是允许的——未求值的嵌入部分会以独立的嵌入样式输出。
+
+## 当前状态
+
+| 模块 | 职责 | 状态 |
+|------|------|------|
+| `lib/mdom/tokenizer.rb` | 逐行分类：围栏 → 表格 → 块级公式 → `\` 转义 → `~` → 候选嵌入 → 排版 | ✅ |
+| `lib/mdom/block_detector.rb` | 用 Prism 增量 parse 判定 Ruby 块（A/B 两类） | ✅ |
+| `lib/mdom/parser.rb` | Token Stream → AST1（按 CSM 缩进建层级；按内容策略区分 FLOW / PHRASING 容器） | ✅ |
+| `lib/mdom/inline_parser.rb` | 行内解析：强调/代码/链接/增删/进度条/公式/插值/转义/换行 | ✅ |
+| `lib/mdom/node.rb`、`node/nodes.rb`、`node/inline_nodes.rb` | 块级与行内节点定义、树操作（挂载/遍历/导航/深度） | ✅ |
+| `lib/mdom/error.rb` | 解析错误（含文档行号） | ✅ |
+| `lib/mdom/builder.rb` | 文档构造 DSL + 游标栈 + `render` / `值.render` + 「当前文档」栈（零 gem 依赖） | ✅ |
+| `lib/mdom/translator.rb` | AST1 → Ruby 源码（`unsafe:` 默认安全，安全时不写嵌入段） | ✅ |
+| `lib/mdom/html_serializer.rb` | AST → HTML（零 gem 依赖，安全模式下嵌入按独立样式输出） | ✅ |
+| `lib/mdom/hooks.rb` | 钩子 / 回调注册表：五个点、类级全局 + 调用时临时（CSM §5.3） | ✅ |
+| `lib/mdom.rb` | 总入口：`MDOM.parse` / `MDOM.compile`（(1)(2)(6) + 钩子） | ✅ |
+| `lib/mdom/markdown_serializer.rb` | AST → CSM（(3)(5)；零 gem 依赖，保守转义 + 按深度重建缩进） | ✅ |
+| `test/` | minitest 用例（`rake test`，覆盖 tokenizer / block_detector / parser / inline_parser / builder / translator / html_serializer / markdown_serializer / node / hooks / compile） | ✅ |
+
+`require "mdom"` 是一个可用入口：`MDOM.parse` 给 AST1，`MDOM.compile` 走完 (1)(2)(6) 并在五个点上触发钩子，返回 `MDOM::Compiled`（`document` / `ruby` / `html` / `meta`）。回写 CSM 用 `node.to_markdown`（≡ `MDOM::MarkdownSerializer.serialize`）——AST1 保真往返，AST2 只能降级。旧版 `MDOM.serialize` 未恢复，`MDOM.compile` 也暂不产出 Markdown。
+
+`rake`（默认任务 = `test` + `rubocop`）全绿：343 例、0 skip、32 个文件无 rubocop 告警。指标类 cop 在 `.rubocop.yml` 里关掉了，理由见该文件的注释。
+
+## 用法
+
+各阶段可以单独 `require`；想一次走完 (1)(2)(6)（并触发钩子）用总入口 `MDOM.compile`，细节见 [USAGE.md](USAGE.md)。下面按阶段演示：
+
+```ruby
+require "mdom/parser"
+
+doc = MDOM::Parser.parse(<<~CSM)
+  # 标题
+
+  - 一
+  - 二
+
+  ~ total = 1 + 2
+CSM
+
+doc.children.map(&:type)   # => [:heading, :list, :ruby_embed]
+```
+
+正文按 CSM 元素表的内容策略落在 `children` 上：**PHRASING** 容器（段落、标题、定义术语）直接收行内节点；**FLOW** 容器（引用、列表项、定义）只收块级节点，正文先成为一个段落。原文仍保留在 `attributes[:text]`：
+
+```ruby
+heading = doc.children.first
+heading.level                     # => 1
+heading.text                      # => "标题"
+heading.children.map(&:type)      # => [:text]
+
+paragraph = MDOM::Parser.parse("**粗** 与 *斜* 与 `code`\n").children.first
+paragraph.children.map(&:type)    # => [:strong, :text, :emphasis, :text, :code_span]
+paragraph.text                    # => "**粗** 与 *斜* 与 `code`"
+
+quote = MDOM::Parser.parse("> 引用 **粗**\n>- 出处\n").children.first
+quote.children.map(&:type)                  # => [:paragraph, :cite]
+quote.children.first.children.map(&:type)   # => [:text, :strong]
+quote.cite                                  # => "出处"     （`>-` 收尾，内容策略 PHRASING）
+
+table = MDOM::Parser.parse("| a | b |\n|:--|--:|\n| 1 | 2 |\n").children.first
+table.children.map(&:type)                  # => [:table_row, :table_row]
+table.children.first.children.map(&:type)   # => [:table_header_cell, :table_header_cell]
+table.children.first.children.map(&:align)  # => [:left, :right]
+
+MDOM::Parser.parse("$$x^2$$\n").children.first.type   # => :math_block
+```
+
+行内节点覆盖 CSM 的全部行内语法，`MDOM::InlineParser.parse` 可单独调用：
+
+```ruby
+MDOM::InlineParser.parse(%q{[文本](@note) #{Date.today}}).map(&:type)
+# => [:inline_quote, :text, :interpolation]
+```
+
+Ruby 嵌入节点保存源码原文、文档行号区间、CSM 缩进与形态：
+
+```ruby
+embed = MDOM::Parser.parse("list.each do |item|\n  puts item\nend.render\n").children.first
+
+embed.type                 # => :ruby_embed
+embed.form                 # => :free   （:begin / :free / :tilde）
+embed.render?              # => true    （以 `.render` 收尾）
+embed.lines                # => 1..3
+embed.source               # => "list.each do |item|\n  puts item\nend.render"
+```
+
+块判定的失败方式遵循 CSM §3.5.3——散文不会被误判为代码：
+
+```ruby
+MDOM::Parser.parse("time flies\n").children.first.type   # => :paragraph
+
+MDOM::Parser.parse("    list.each do |x|\n      y\n  end\n")
+# => MDOM::CrossLevelError: ruby block opens with 4 space(s) of indentation (line 1)
+#                            but closes with 2 (line 3)
+```
+
+### 翻译为 Ruby
+
+`MDOM::Translator` 实现 (2)：把 AST1 翻成一段顶层顺序执行的 Ruby 程序。排版节点
+变成 `builder.*` 调用——产物不绑定执行方式，`eval`、落盘 `require`、交给 mruby
+都行。
+
+**`unsafe` 是翻译期参数，默认安全**（CSM §3.14）。`to_ruby(node)` 默认
+`unsafe: false`：嵌入段**不写进产物**——块级嵌入只留一行注释占位，行内插值退化为
+字面 `#{expr}`，因此产物静态上不含用户代码。`to_ruby(node, unsafe: true)` 才把
+嵌入块（`begin...end` / `~` 行）原样注入、把行内插值交 Ruby 求值。
+
+安全渲染不需要拿产物去执行：未求值的嵌入还留在 AST1 里，直接交给 `to_html` 即可。
+（执行本身只是宿主的一行 `eval`，mdom 不含求值器。）
+
+```ruby
+require "mdom/parser"
+require "mdom/translator"
+
+puts MDOM::Translator.to_ruby(MDOM::Parser.parse("- 一\n- 二\n"))
+# builder = MDOM::Builder.new
+# builder.list(ordered: false, task: false, marker: "-") do
+#   builder.item("一", marker: "-")
+#   builder.item("二", marker: "-")
+# end
+# builder.to_document
+```
+
+`Translator.to_ruby(node, **options)` 与 `node.to_ruby(**options)` 等价。
+
+### 序列化为 HTML
+
+`MDOM::HtmlSerializer` 实现 (6)。AST1 与 AST2 都能喂给它——未求值的嵌入（块级
+`RubyEmbed` / 行内插值）按独立的嵌入样式输出（与代码块同构，另加 `csm-ruby`
+class），所以「安全渲染」与「不安全渲染」的差别只在于嵌入代码是否执行。
+
+```ruby
+require "mdom/parser"
+require "mdom/html_serializer"
+
+puts MDOM::HtmlSerializer.serialize(MDOM::Parser.parse("## 标题\n\n正文 **粗**。\n"))
+# <section>
+# <h2 id="标题">标题</h2>
+# <p>正文 <strong>粗</strong>。</p>
+# </section>
+```
+
+`HtmlSerializer.serialize(node)` 与 `node.to_html` 等价；给 `known_targets:` 时，
+不在其中的 WikiLink 会带上 `orphan-link` class。
+
+### 序列化为 CSM
+
+`MDOM::MarkdownSerializer` 实现 (3)/(5)，把树写回 CSM 源。同一个方法服务两种输入
+状态：**AST1**（嵌入还留着源码）逐字保真往返；**AST2**（嵌入已被求值结果替换）只能
+降级——源码位置只剩结果，无法还原成 Ruby。
+
+```ruby
+require "mdom/parser"
+require "mdom/markdown_serializer"
+
+MDOM::MarkdownSerializer.serialize(MDOM::Parser.parse("# 标题\n"))
+# => "# 标题"
+
+MDOM::Parser.parse("**粗** 与 `code`\n").to_markdown
+# => "**粗** 与 `code`"
+```
+
+序列化**从节点结构重建**（不读 `attributes[:text]` 那类原文缓存，所以改树之后输出
+反映改动），并采取**保守转义**：文本里凡是可能重新触发解析的字符都会被转义，代价是
+输出比手写的 CSM 更谨慎，换来的是「内容不会被自己的标记重新解析」。
+
+### 用 DSL 构造
+
+除了解析，也可以用 builder 从零构造文档。节点挂到「当前容器」；块参数就是 builder 自身（显式传参，不用 `instance_eval`）：
+
+```ruby
+require "mdom/parser"    # 字符串参数要走行内解析，需要解析侧
+require "mdom/builder"
+
+doc = MDOM::Builder.build do |b|
+  b.heading(1, "标题")
+  b.paragraph("正文 *强调*。")
+  b.list do |l|
+    %w[一 二].each { |item| l.item { |i| i.render(item) } }   # render 是唯一的注入通道
+  end
+end
+```
+
+`render(value, parse: false)` 把值挂到调用位置：字符串按**当前容器**包装（行内容器 → 文本节点，块级容器 → 段落），`Array` / `Enumerable` 逐项递归，节点直接插入；`parse: true` 时字符串按 CSM 递归解析。
+
+builder 属**零 gem 依赖**的一侧：它不 `require` 任何东西，字符串参数的行内解析与 `render(parse: true)` 的 CSM 解析都通过构造参数注入（默认为 `MDOM::InlineParser` / `MDOM::Parser`）。
+
+## 文档
+
+| 文件 | 内容 |
+|------|------|
+| [USAGE.md](USAGE.md) | **使用指南**：各阶段的 API、可运行示例、常见配方 |
+| [docs/CSM.md](docs/CSM.md) | **语言规格**：语法、嵌入机制、处理模型（`docs/CSM.md` 自身就是一份合法 CSM 文档） |
+| [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md) | 实现方案：管线、模块划分、算法要点、风险清单、测试用例清单 |
+| [docs/GFM-NOTES.md](docs/GFM-NOTES.md) | GitHub Flavored Markdown 规范阅读笔记（CSM 语法的来源之一） |
+| [docs/STRICT-GFM.md](docs/STRICT-GFM.md) | SMD：基于 GFM 裁剪的确定性优先标记语言 |
+| [docs/ROBUSTNESS.md](docs/ROBUSTNESS.md) | 元数据索引鲁棒性的纸面推演（非实测） |
+| [CHANGELOG.md](CHANGELOG.md) | 版本记录 |
+
+## 开发
+
+需要 **Ruby 3.0+**；解析侧硬依赖 [`prism`](https://github.com/ruby/prism)（Ruby 3.3 起随发行版作为 default gem 提供）。builder 侧不依赖 prism，目标是 mruby 子集。
+
+```sh
+rake test                                  # 运行全部测试
+ruby -Ilib test/parser_test.rb             # 运行单个测试文件
+ruby -Ilib -e 'require "mdom/parser"; p MDOM::Parser.parse("# T\n").children'
+```
+
+## 目录结构
+
+```
+lib/
+  mdom.rb                 # 入口：MDOM.parse / MDOM.compile
+  mdom/
+    parser.rb             # Token Stream → AST1          （解析侧）
+    tokenizer.rb          # 逐行分类                     （解析侧）
+    block_detector.rb     # Prism 块判定                 （解析侧）
+    inline_parser.rb      # 行内解析                     （解析侧）
+    translator.rb         # AST1 → Ruby 源码             （解析侧）
+    error.rb              # 解析错误
+    node.rb               # 节点基类与树操作
+    node/nodes.rb         # 块级节点定义
+    node/inline_nodes.rb  # 行内节点定义
+    builder.rb            # 构建 DSL + 游标栈 + render
+    hooks.rb              # 钩子 / 回调注册表（CSM §5.3）
+    html_serializer.rb    # AST → HTML（零 gem 依赖）
+    markdown_serializer.rb # AST → CSM 源（(3)(5)，零 gem 依赖）
+    version.rb
+test/                     # minitest 用例
+docs/                     # 语言规格与实现文档
+```
+
+## 设计边界
+
+- **两个目标平台**。builder 侧（节点、builder、钩子、HTML 序列化）只用 mruby 子集，可在 WASM 等受限环境运行；解析侧真正硬依赖 `prism` 的是 `block_detector`（块判定）与 `inline_parser`（行内），`tokenizer` / `parser` 经由它们间接依赖，只在 CRuby 上运行。两侧没有硬调用关系——builder 要重解析字符串参数时靠 `MDOM::InlineParser` 的**依赖注入**，本侧不 require 它。
+- **`prism` 只在解析期使用**。块判定必须交给 Ruby 原装解析器：`do` / `end` 在英语里也是常见单词，纯词法无法区分「Ruby 块」与「英文散文」。AST1 一旦产出，后续阶段不再需要词法能力。
+- **注入文档树的唯一通道是 `render`**。裸 `end` 与不带 `render` 的 `~` 行都只是执行，不产生输出；默认**安全渲染**——`to_ruby` 的 `unsafe` 默认 `false`，此时产物不含嵌入段（CSM §3.14）。
+- **「当前文档」是类级状态**。`值.render` 与裸 `render` 靠 `MDOM::Builder.current`（文档栈）定位目标文档，所以并行请用 **Ractor**（类实例变量天然隔离），**`Thread` 并行不支持**。`render` 内部持互斥锁，无 `Mutex` 的平台（mruby 默认构建）退化为无锁。
+
+细节见 [docs/CSM.md](docs/CSM.md) 与 [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md)。
+
+## License
+
+MIT