contract · 校验文档

把来路不明的数据变成可信的 DrawDocument。contract 只校验结构与引用，不读取注册表。

导出

DrawDocumentSchema、parseDocument 以及文档相关类型。

签名

function parseDocument(input: unknown): Result<DrawDocument>;

parseDocument 接受 version: 1 并升级为 v2；下游始终只处理 v2。

文档结构

type DrawDocument = {
  version: 2;
  nodes: DrawNode[];
  edges: DrawEdge[];
  styles?: Record<string, StyleDecl>;
  layout?: LayoutIntent;
};

type DrawNode = {
  id: string;
  type: string;
  props?: Record<string, unknown>;
  children?: string[];
  label?: Label;
  ports?: Port[];
  style?: string;
  layout?: LayoutIntent;
};

type DrawEdge = {
  id: string;
  type: string;
  source: EndpointRef;
  target: EndpointRef;
  props?: Record<string, unknown>;
  label?: Label;
  style?: string;
  route?: {
    kind?: "auto" | "straight" | "orthogonal" | "curved";
    sourceSide?: Side;
    targetSide?: Side;
  };
  weight?: number;
};

id 与 port

• id 只允许 A-Z a-z 0-9 _ . : -，长度 1–128，不能包含 / 或 #。
• Port.offset 接受 0..1 数字或百分比字符串。
• Port.constraint 取 fixed | side | free；省略时按 fixed 解释。

标签

type Label = string | {
  lines: string[];
  anchor?: "center" | "start";
  maxWidth?: number;
  overflow?: "wrap" | "ellipsis" | "none";
  position?: number;
};

position 只用于边标签，表示沿路径的比例。

只做 / 绝不做

只做：结构校验、id 唯一、children / port / pins 引用校验、v1 升级。

绝不做：不读取 registry，不归一化 shape props，不产几何，不校验主题。

shape props 与未知类型由 bindDocument 处理。

诊断

• UNKNOWN_FIELD：出现未声明字段；
• INVALID_ID：id 字符集非法；
• DANGLING_REFERENCE / UNKNOWN_PORT：引用不存在；
• PARENT_CYCLE / MULTIPLE_PARENTS：children 结构非法；
• PIN_DANGLING：pins 指向不存在的节点。