主题
架构与设计
这一组页面给实现者、评审者和后续维护者看。API Reference 说明“怎么调用”，这里说明 “为什么这样分层、模块之间允许怎样依赖、哪些约束不能破”。
设计文档
| 页面 | 回答什么 |
|---|---|
| 架构设计 | 系统边界、三层数据、五段契约、扩展点和错误模型 |
| 组件图 | @ggn/draw 的模块组成、运行期依赖和外部边界 |
| 端到端泳道图 | 一份文档从输入到 SVG / DOM 的完整流转 |
| API 设计 | 公开面的形状、统一返回模型、扩展契约和明确不做的 API |
| API Reference | 每个导出、签名、诊断码和模块细节 |
建议顺序：先看架构设计，再看组件图和泳道图，最后对照 API 设计检查公开面。
系统边界
@ggn/draw 是领域无关的绘制内核。上层知道“这是 UML 组件、系统节点还是任务”；draw 只知道 文档、形状注册项、几何、场景和宿主。
一页记住
| 约束 | 含义 |
|---|---|
| 文档没有最终坐标 | 唯一例外是 layout.pins，只给 explicit 引擎使用 |
| 只有 layout 解析引用几何 | 父子、端口、边路由的绝对坐标都来自 layoutDocument |
| render 看不到别的元素 | 形状只能在自己的 box 和 anchors 里画 |
| host 只读场景 | renderToSvg / createDomHost 不改几何 |
| 扩展点是值 | ShapeSpec、EdgeSpec、LayoutEngine、Router、TextMeasurer、DrawHost |
| 失败统一返回诊断 | 可回落的问题返回 ok: true + diagnostics |
数据流
三段数据各自可保存、可断言、可单独测试。页面里的实时示例也是沿这条链路生成的， 不是静态截图。