handle · 一步到位

把 Pipeline 接到 Host 上并记住上一帧：改一个 label 只发一条 patch；失败时保留上一帧。

导出

createDrawHandle、DrawHandle、DrawHandleOptions。

签名

interface DrawHandleOptions {
  document: DrawDocument;      // 已 parse 的可信文档
  host: DrawHost;
  registry?: DrawRegistry;     // 缺省 = builtinRegistry
  theme?: ThemeInput;
  engine?: LayoutEngine;
  engines?: Record<string, LayoutEngine>;
  router?: Router;
  measurer?: TextMeasurer;
  overlay?: StyleOverlay;
}
interface DrawHandle {
  update(next: DrawDocument): Diagnostic[];
  updateAsync(next: DrawDocument): Promise<Diagnostic[]>;
  setTheme(theme: ThemeInput): Diagnostic[];
  setOverlay(overlay: StyleOverlay): Diagnostic[];
  frame(): PipelineFrame;
  scene(): Scene;
  diagnostics(): readonly Diagnostic[];
  destroy(): void;
}
function createDrawHandle(options: DrawHandleOptions): DrawHandle;

它自己不含算法

它由 Pipeline 与 Host 组成。Pipeline 负责 bind、布局、构建与缓存；handle 只提交成功帧， 并记住宿主已经接受的上一帧。

正在渲染图表…

从第二帧起只向 host 产 patch；首帧 mount，之后 apply。frame() 返回当前已提交帧的 bind、theme、layout、scene、诊断和阶段统计；scene() 是当前场景的快捷方式。

updateAsync 用于异步布局引擎。多次调用时只提交最后发起的那一帧；较早的调用即使更晚返回， 也只会得到 ABORTED，不会覆盖已经显示的新帧。

四条状态口径

口径	行为
注册表快照	registry 不可变；派生新版本不会影响已经创建的 handle
失败保留上一帧	layout / build 失败只返回诊断，不打 patch，host 上仍是上一帧
host 失败	apply 抛 HostError 时转成 HOST_FAILED，介质保持上一帧
诊断累积	update 返回本次的，diagnostics() 返回自创建以来累积的（含主题回落）

只做 / 绝不做

只做：接收 Pipeline 的成功帧，调用 diffScene / host，并记住宿主已接受的上一帧与累积诊断。 绝不做：自己实现布局 / 画法；parseDocument 也不在这里——unknown 在边界处解析，handle 只收可信文档。

相关 BDD

C13 / C17–C20（经 handle 走通：两帧相等、只 update、失败保留上一帧）· C35（异步更新只提交最新帧）· C15（headless 全链路）。