API 设计

API Reference 列的是“有哪些导出”。这里说明公开面为什么只有这些形状，以及哪些行为属于稳定契约。

完整的逐模块签名和诊断码见 API Reference。

公开面的形状

类别	例子	用途
纯函数阶段	`parseDocument`、`bindDocument`、`resolveTheme`、四个 layout 原子、`buildScene`	一段输入，一段输出
纯转换函数	`diffScene`、`hitTest`、`polylineD`、`resolveToken`	不持有状态
状态口	`createRegistry`、`emptyRegistry`、`createDomHost`	显式创建，不靠全局变量
组合根	`createPipeline`、`createDrawHandle`	缓存阶段 / 接上宿主
类型契约	`ShapeSpec`、`EdgeSpec`、`LayoutEngine`、`Router`	扩展点

核心原则：

type Result<T> =
  | { ok: true; value: T; diagnostics: Diagnostic[] }
  | { ok: false; diagnostics: Diagnostic[] };

调用方必须同时看 ok 和 diagnostics。成功不代表没有警告。

入口	内容	约束
`@ggn/draw`	contract、bind、theme、registry、layout、scene、build、svg、pipeline、handle	主入口不接触 DOM
`@ggn/draw/contract`	schema / parse / 文档类型	按需加载
`@ggn/draw/registry`	注册表与扩展契约	按需加载
`@ggn/draw/layout`	四个几何原子、引擎、路由	按需加载
`@ggn/draw/scene`	Scene、diff、hitTest	按需加载
`@ggn/draw/svg`	`renderToSvg`	按需加载
`@ggn/draw/dom`	`createDomHost`	直接操作 DOM
`@ggn/draw/measure-canvas`	Canvas 度量器	直接操作 Canvas

子路径与主入口是同一套实现，不是两套 API。

契约	负责	边界
`ShapeSpec`	schema、container、measure、anchors、render	只看自己的 box / props / anchors / style
`EdgeSpec`	线、标签、marker	只看 route / props / style
`MarkerSpec`	端点装饰	只看连接点、角度、大小
`LayoutEngine`	节点摆放	只消费测量后的节点树、边、布局意图与上一帧
`Router`	折点与标签落点	只消费盒子、端口、容器与边
`TextMeasurer`	文本尺寸	不参与布局顺序
`DrawHost`	场景落到介质	不计算几何

扩展点按值传入。注册表不可变，with 返回新实例；冲突默认抛 RegistryConflictError。

节点注册项可以提供同步 Standard Schema。bind 阶段校验并补默认值，产出的 BoundDocument 同时供 layout 与 build 使用。非法 props 只在 bind 报一次。