文档不是像素序列

把一份文档看成“若干页像素”，对阅读是够用的，对编译是不够的。像素没有块的身份，没有段落的边界，也没有“这一处改动影响了后面哪些页”的信息。想要增量编译、逐页 SVG 和编辑器定位，就必须先承认文档是结构。

IR 提供的不是抽象，而是可操作性

Somadoc 的 IR 把写作内容变成一组有身份的块：标题、段落、公式、表格、脚注、引用。块的身份让预览可以定位，让改动可以比较，让未变化的部分保留已有布局。没有这层结构，所谓“增量”只能退化成整页重排。

逐页 SVG 是这层结构在输出侧的证明：每一页仍然可以被当作图形显示，但页面里的块知道自己的来源。块级 source map 让编辑器与预览可以双向定位，而不是靠滚动位置猜测。

Typst 是排版内核，不是整个系统

边界需要说清楚。Typst 负责排版内核；Somadoc 负责解析、IR、增量上下文、source map 与输出。把两者混在一起，会得到“纯 Rust 排版引擎”这种听起来完整、实际上含糊的说法。对技术读者来说，准确说明依赖关系本身就是可信度的一部分。

“无需外部工具链”说的是部署边界：不需要 Pandoc、LaTeX 发行版或外部 CLI。它不意味着所有排版算法都由 Somadoc 从零实现，也不意味着可以忽略 Typst 的版本、字体和行为差异。

增量编译真正难的地方

缓存未变化的块只是第一步。真正困难的是块变化之后的分页重排：一个段落变长，可能推动脚注、改变浮动体位置、让交叉引用失效，甚至影响后续多页。可靠的增量编译必须知道哪些结构依赖被破坏，哪些布局可以保留。

这也是为什么“持久编译上下文”不是性能装饰，而是正确性问题。上下文如果保留了不该保留的布局，速度越快，错误越难发现。

目前公开到哪一步

Somadoc 的引擎与仓库仍在开源审查中。这个网站上的 Lab 只有接口壳和 mock adapter，不会生成真实 PDF。把这句话写清楚，比让读者点开一个假预览更尊重人。

文档值得被认真设计，不是因为它能变成一张漂亮的页面，而是因为结构决定了它能否被修改、验证、定位和长期维护。像素只是最后的呈现，不是文档本身。