@retikz/core 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/es/compile/compile.d.ts

@@ -8,20 +8,19 @@ export type CompileOptions = {
     /** viewBox 周围的留白（user units），默认 10 */
     padding?: number;
     /**
-     * 输出坐标的小数位精度；默认 2（保留 2 位小数四舍五入）。
-     * 仅在写入 Scene primitive / path d 字符串 / viewBox 时生效；
-     * 内部几何计算保持完整 double 精度，避免误差累积。
+     * 输出坐标的小数位精度；默认 2
+     * @description 仅作用于 Scene primitive / path d / viewBox；内部几何计算保持完整 double 精度
      */
     precision?: number;
+    /**
+     * 相对定位的默认距离（对应 TikZ `node distance`，user units）
+     * @description `Node.position` 为 `{ direction, of }` 且未自带 `distance` 时取此值；未配回退到 1
+     */
+    nodeDistance?: number;
 };
 /**
- * IR → Scene。纯函数。
- * 这是所有 adapter 共享的最深层共享代码。
- *
- * 流程：
- * 1. Pass 1：按 IR children 源码顺序处理 Node——计算 layout、注册 nodeIndex、发出 RectPrim/TextPrim、累积 bbox 角点
- * 2. Pass 2：处理 Path——解析每个 step 端点（节点 ref 走 boundaryPoint，其他走 resolvePosition），写 d 字符串
- * 3. 末端用 computeViewBox 折算最终 viewBox（按 precision 四舍五入）
+ * IR → Scene 纯函数转换，所有 adapter 共享
+ * @description Pass 1 处理 Node/coordinate 并注册 nodeIndex、发 primitive、累积 bbox；Pass 2 解析 Path 端点写 d 字符串；末端按 precision 折算 viewBox
  */
 export declare const compileToScene: (ir: IR, options?: CompileOptions) => Scene;
 //# sourceMappingURL=compile.d.ts.map

package/dist/es/compile/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAkB,MAAM,cAAc,CAAC;AAI1D,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAGrE,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KA2CrE,CAAC"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAkB,MAAM,cAAc,CAAC;AAK1D,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAuBrE,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAsDrE,CAAC"}

package/dist/es/compile/compile.js

@@ -1,4 +1,5 @@
 import { rect } from "../geometry/rect.js";
+import { resolvePosition } from "./position.js";
 import { emitNodePrimitives, layoutNode } from "./node.js";
 import { fallbackMeasurer } from "./text-metrics.js";
 import { emitPathPrimitive } from "./path.js";
@@ -6,26 +7,48 @@ import { makeRound } from "./precision.js";
 import { computeViewBox } from "./view-box.js";
 //#region src/compile/compile.ts
 /**
-* IR → Scene。纯函数。
-* 这是所有 adapter 共享的最深层共享代码。
-*
-* 流程：
-* 1. Pass 1：按 IR children 源码顺序处理 Node——计算 layout、注册 nodeIndex、发出 RectPrim/TextPrim、累积 bbox 角点
-* 2. Pass 2：处理 Path——解析每个 step 端点（节点 ref 走 boundaryPoint，其他走 resolvePosition），写 d 字符串
-* 3. 末端用 computeViewBox 折算最终 viewBox（按 precision 四舍五入）
+* 把 coordinate 注册成 0×0 NodeLayout
+* @description 让后续 path target / `at.of` 引用时 boundaryPoint 命中中心，符合"占位无形状边界"语义
+*/
+var coordinateAsLayout = (id, center) => ({
+	id,
+	shape: "rectangle",
+	rect: {
+		x: center[0],
+		y: center[1],
+		width: 0,
+		height: 0,
+		rotate: 0
+	},
+	rotateDeg: 0,
+	margin: 0,
+	textWidth: 0,
+	textHeight: 0,
+	align: "middle",
+	lineHeight: 0,
+	fontSize: 0
+});
+/**
+* IR → Scene 纯函数转换，所有 adapter 共享
+* @description Pass 1 处理 Node/coordinate 并注册 nodeIndex、发 primitive、累积 bbox；Pass 2 解析 Path 端点写 d 字符串；末端按 precision 折算 viewBox
 */
 var compileToScene = (ir, options = {}) => {
 	const measureText = options.measureText ?? fallbackMeasurer;
 	const viewBoxPadding = options.padding ?? 10;
 	const round = makeRound(options.precision ?? 2);
+	const nodeDistance = options.nodeDistance;
 	const primitives = [];
 	const nodeIndex = /* @__PURE__ */ new Map();
 	const allPoints = [];
 	for (const child of ir.children) if (child.type === "node") {
-		const layout = layoutNode(child, measureText, nodeIndex);
+		const layout = layoutNode(child, measureText, nodeIndex, nodeDistance);
 		if (child.id) nodeIndex.set(child.id, layout);
 		for (const prim of emitNodePrimitives(layout, round)) primitives.push(prim);
 		allPoints.push(rect.anchor(layout.rect, "north-west"), rect.anchor(layout.rect, "north-east"), rect.anchor(layout.rect, "south-west"), rect.anchor(layout.rect, "south-east"));
+	} else if (child.type === "coordinate") {
+		const center = resolvePosition(child.position, nodeIndex, nodeDistance);
+		if (!center) throw new Error(`Cannot resolve position for coordinate ${child.id}; polar.origin or at.of may reference an undefined node`);
+		nodeIndex.set(child.id, coordinateAsLayout(child.id, center));
 	}
 	for (const child of ir.children) if (child.type === "path") {
 		const result = emitPathPrimitive(child, nodeIndex, round, measureText);

package/dist/es/compile/node.d.ts

@@ -1,102 +1,104 @@
 import { Position } from '../geometry/point';
 import { Rect, RectAnchor } from '../geometry/rect';
-import { IRNode, NodeShape } from '../ir';
+import { AtDirection, IRNode, NodeShape } from '../ir';
 import { ScenePrimitive, TextLine } from '../primitive';
 import { TextMeasurer } from './text-metrics';
 export type NodeLayout = {
-    /** 节点 id（如 IR Node 提供）；其他位置可通过 id 引用本节点 */
+    /** 节点 id（其他位置可引用） */
     id?: string;
-    /** 节点形状——所有几何 / boundaryPoint 计算按 shape 多态 */
+    /** 节点形状，所有几何 / boundaryPoint 按 shape 多态 */
     shape: NodeShape;
     /**
-     * 节点视觉边界框（所有 shape 共享语义）：
-     * - rectangle: rect 即矩形本身
-     * - circle:    rect.width = rect.height = 2 × radius（外接正方形）
-     * - ellipse:   rect.width = 2 × rx，rect.height = 2 × ry（外接矩形）
-     * - diamond:   rect.width = 2 × halfA，rect.height = 2 × halfB（外接矩形）
-     *
-     * x, y 是几何中心；rotate 是弧度（与 packages/core/AGENTS.md 对齐）。
+     * 节点视觉边界框（所有 shape 共享语义）
+     * @description rectangle: rect 本身；circle: width=height=2×radius；ellipse: 2×rx,2×ry；diamond: 2×halfA,2×halfB。x,y 是几何中心，rotate 弧度
      */
     rect: Rect;
-    /** IR 中原始的旋转角（度数），保留供 emit 阶段写 SVG transform */
+    /** IR 原始旋转角（度数），供 emit 写 SVG transform */
     rotateDeg: number;
-    /** 外边距（user units，≥ 0）；path 附着到形状外扩 margin 的虚拟边界上 */
+    /** 外边距（≥ 0），path 附着到外扩 margin 的虚拟边界 */
     margin: number;
     /**
-     * 节点文本行；undefined 表示无文本，否则非空数组。
-     * 每行可带覆盖样式（fill / opacity / fontSize / fontFamily / fontWeight / fontStyle）；
-     * 未覆盖的字段在 emit 阶段不写出，由下游走 TextPrim 块级默认。
+     * 节点文本行（undefined 表示无文本，否则非空数组）
+     * @description 每行可带覆盖样式（fill/opacity/fontSize/fontFamily/fontWeight/fontStyle），未覆盖字段 emit 阶段不写出由下游走块级默认
      */
     lines?: Array<TextLine>;
-    /** 文本块宽度（user units）= max(per-line measureText.width) */
+    /** 文本块宽度 = max(per-line measureText.width) */
     textWidth: number;
-    /** 文本块高度（user units）≈ lines × lineHeight */
+    /** 文本块高度 ≈ lines × lineHeight */
     textHeight: number;
-    /** 文本对齐（已映射到 SVG textAnchor 三态）；emit 时透传给 TextPrim.align */
+    /** 文本对齐（已映射到 SVG textAnchor 三态） */
     align: 'start' | 'middle' | 'end';
-    /** 行高（user units），已应用默认值；emit 时透传给 TextPrim.lineHeight */
+    /** 行高（已应用默认值） */
     lineHeight: number;
-    /** 文本字号（user units），已应用默认值 */
+    /** 文本字号（已应用默认值） */
     fontSize: number;
-    /** 字体族；CSS font-family；emit 时透传给 TextPrim */
+    /** 字体族（CSS font-family） */
     fontFamily?: string;
-    /** 字重；emit 时透传给 TextPrim */
+    /** 字重 */
     fontWeight?: string | number;
-    /** 字形：normal / italic / oblique；emit 时透传给 TextPrim */
+    /** 字形 */
     fontStyle?: 'normal' | 'italic' | 'oblique';
-    /** 节点背景色，CSS 颜色字符串；emit 时用 'transparent' 兜底 */
+    /** 节点背景色，emit 时 'transparent' 兜底 */
     fill?: string;
-    /** 节点填充透明度 0~1；透传 shape primitive */
+    /** 填充透明度 0~1 */
     fillOpacity?: number;
-    /** 节点边框色，CSS 颜色字符串；emit 时用 'currentColor' 兜底 */
+    /** 节点边框色，emit 时 'currentColor' 兜底 */
     stroke?: string;
-    /** 节点描边透明度 0~1；TikZ `draw opacity`，透传 shape primitive */
+    /** 描边透明度 0~1（TikZ `draw opacity`） */
     strokeOpacity?: number;
-    /** 节点边框宽度（user units）；emit 时用 1 兜底 */
+    /** 边框宽度，emit 时 1 兜底 */
     strokeWidth?: number;
-    /** SVG stroke-dasharray 字符串；compile 已把 dashed / dotted 预设解析为具体 pattern */
+    /** SVG stroke-dasharray，已把 dashed/dotted 预设解析为具体 pattern */
     strokeDasharray?: string;
-    /** rectangle shape 的圆角半径（user units）；非 rect shape 该字段无效 */
+    /** rectangle 圆角半径（非 rect shape 无效） */
     roundedCorners?: number;
-    /** 文字颜色；emit 时透传给 TextPrim.fill，兜底 'currentColor' */
+    /** 文字颜色，emit 时 'currentColor' 兜底 */
     textColor?: string;
-    /** 整节点透明度 0~1；emit 时同时挂 shape 与 text primitive */
+    /** 整节点透明度 0~1（同时挂 shape 与 text primitive） */
     opacity?: number;
+    /**
+     * 已解析的 label 列表
+     * @description IR 层 `Node.label` 标准化：position 默认 'above'、distance 默认 DEFAULT_LABEL_DISTANCE、font 从 Node 继承
+     */
+    labels?: Array<NodeLabelLayout>;
+};
+/** 节点附属标签 layout（layoutNode 已合并默认值与样式继承） */
+export type NodeLabelLayout = {
+    text: string;
+    /** 8 方向枚举或数字角度 */
+    position: AtDirection | number;
+    /** 已应用默认值 */
+    distance: number;
+    textColor?: string;
+    opacity?: number;
+    fontSize: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    fontStyle?: 'normal' | 'italic' | 'oblique';
 };
 /**
- * 取节点 shape 在 toward 方向上的"附着点"——path 端点贴边用。
- * 按 shape 多态：rect / circle / ellipse / diamond 各自的 boundaryPoint。
- * margin > 0 时形状先外扩，让 path 在 border 外停 margin 个 user units。
+ * 取节点 shape 在 toward 方向的附着点（path 端点贴边用）
+ * @description 按 shape 多态调用各自 boundaryPoint；margin > 0 时形状先外扩，让 path 在 border 外停 margin
  */
 export declare const boundaryPointOf: (layout: NodeLayout, toward: Position) => Position;
 /**
- * 取节点 shape 的命名 anchor（center / north / east / north-east 等 9 个）。
- * **不应用 margin**——TikZ 语义中 explicit anchor 取的是视觉边界点，不涉及 outer sep。
- * 用于 `'A.north'` 这种语法落点。
+ * 取节点 shape 命名 anchor（center / north / east / north-east 等 9 个）
+ * @description 不应用 margin——TikZ 语义中 explicit anchor 取视觉边界点不涉及 outer sep；用于 `'A.north'` 落点
  */
 export declare const anchorOf: (layout: NodeLayout, name: RectAnchor) => Position;
 /**
- * 取节点 shape 在指定角度方向上的边界点。角度约定与 PolarPosition 一致（度数）：
- *   0° = +x（east），90° = +y（screen 下方）。
- * **不应用 margin**——同 anchorOf。用于 `'A.30'` 这种语法落点。
+ * 取节点 shape 在指定角度方向的边界点
+ * @description 角度约定与 PolarPosition 一致（度数：0°=+x，90°=+y 即 screen 下方）；不应用 margin（同 anchorOf）；用于 `'A.30'` 落点
  */
 export declare const angleBoundaryOf: (layout: NodeLayout, angleDeg: number) => Position;
 /**
- * 把 IR Node 解析为内部 NodeLayout：
- * - 算出文本度量与 padding 推导出"内框"半轴 (innerHalfW/H)
- * - 按 shape 决定外接边界尺寸（circle 取半对角线、ellipse 各 ×√2、diamond 各 ×2）
- * - 解析 position（笛卡尔或极坐标）为几何中心
- * - IR 的 rotate（度数）转弧度存进 Rect.rotate
- * - 透传 margin / 样式属性
+ * IR Node → 内部 NodeLayout
+ * @description 文本度量 + padding 推内框半轴；按 shape 算外接边界（circle 取半对角线、ellipse ×√2、diamond ×2）；解析 position 为几何中心；rotate 度数转弧度
  */
-export declare const layoutNode: (node: IRNode, measureText: TextMeasurer, nodeIndex: Map<string, NodeLayout>) => NodeLayout;
+export declare const layoutNode: (node: IRNode, measureText: TextMeasurer, nodeIndex: Map<string, NodeLayout>, nodeDistance?: number) => NodeLayout;
 /**
- * 把 NodeLayout 翻译为 Scene primitives：
- * - shape 主体：按 shape 分发（rect / ellipse / path）
- * - text（如有内容）：始终走 TextPrim
- * - 若有旋转：外面套一层 GroupPrim 用 SVG `rotate(deg cx cy)` 实现
- *   （PathPrim 的 diamond 顶点已自带旋转坐标，但 text 需要 group 旋转，
- *    所以仍统一用 group 包裹）
+ * NodeLayout → Scene primitives
+ * @description shape 主体按 shape 分发（rect/ellipse/path）；text 始终走 TextPrim；有旋转时外层 GroupPrim 用 `rotate(deg cx cy)` 统一包裹（text 必须靠 group 旋转）
  */
 export declare const emitNodePrimitives: (layout: NodeLayout, round: (n: number) => number) => Array<ScenePrimitive>;
 //# sourceMappingURL=node.d.ts.map

package/dist/es/compile/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/compile/node.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAc,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA8BnD,MAAM,MAAM,UAAU,GAAG;IACvB,2CAA2C;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;OAQG;IACH,IAAI,EAAE,IAAI,CAAC;IACX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,sDAAsD;IACtD,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAsCF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,UAAU,EAAE,QAAQ,QAAQ,KAAG,QAYtE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,UAAU,EAAE,MAAM,UAAU,KAAG,QAW/D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,UAAU,EAAE,UAAU,MAAM,KAAG,QActE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,aAAa,YAAY,EACzB,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KACjC,UAgJF,CAAC;AAsEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,UAAU,EAClB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,KAAK,CAAC,cAAc,CAoDtB,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/compile/node.ts"],"names":[],"mappings":"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"}

package/dist/es/compile/node.js

@@ -8,20 +8,22 @@ var DEFAULT_FONT_SIZE = 14;
 var DEFAULT_PADDING = 8;
 var DEFAULT_LINE_HEIGHT_FACTOR = 1.2;
 var DEG_TO_RAD = Math.PI / 180;
+/** Node label 与 node 边界默认距离（TikZ 默认 0pt 视觉太贴） */
+var DEFAULT_LABEL_DISTANCE = 4;
 var SQRT2 = Math.SQRT2;
-/** dashed 预设：SVG stroke-dasharray "4 2"——4 px 实线 + 2 px 间隙循环 */
+/** dashed 预设：4 px 实线 + 2 px 间隙循环 */
 var DASHED_PATTERN = "4 2";
-/** dotted 预设：SVG stroke-dasharray "1 2"——1 px 圆点 + 2 px 间隙 */
+/** dotted 预设：1 px 圆点 + 2 px 间隙 */
 var DOTTED_PATTERN = "1 2";
-/** 解析 dashed / dotted / dashArray 优先级：dashArray > dashed > dotted */
+/** dashed / dotted / dashArray 优先级：dashArray > dashed > dotted */
 var resolveDashArray = (dashArray, dashed, dotted) => {
 	if (dashArray !== void 0) return dashArray;
 	if (dashed) return DASHED_PATTERN;
 	if (dotted) return DOTTED_PATTERN;
 };
-/** IR `align` ('left' | 'center' | 'right') → SVG textAnchor ('start' | 'middle' | 'end') */
+/** IR align → SVG textAnchor */
 var alignToTextAnchor = (a) => a === "left" ? "start" : a === "right" ? "end" : "middle";
-/** 由 layout 构造的 Rect（带 margin 扩张） */
+/** 从 layout 构造 Rect（带 margin 扩张） */
 var rectOf = (layout, marginAdd) => ({
 	x: layout.rect.x,
 	y: layout.rect.y,
@@ -29,14 +31,14 @@ var rectOf = (layout, marginAdd) => ({
 	height: layout.rect.height + 2 * marginAdd,
 	rotate: layout.rect.rotate
 });
-/** 由 layout 构造的 Circle（圆心 + 半径，半径=外接框边长/2 + margin） */
+/** 从 layout 构造 Circle（radius=外接框边长/2 + margin） */
 var circleOf = (layout, marginAdd) => ({
 	x: layout.rect.x,
 	y: layout.rect.y,
 	radius: layout.rect.width / 2 + marginAdd,
 	rotate: layout.rect.rotate
 });
-/** 由 layout 构造的 Ellipse（rx/ry 各加 margin） */
+/** 从 layout 构造 Ellipse（rx/ry 各加 margin） */
 var ellipseOf = (layout, marginAdd) => ({
 	x: layout.rect.x,
 	y: layout.rect.y,
@@ -44,7 +46,7 @@ var ellipseOf = (layout, marginAdd) => ({
 	ry: layout.rect.height / 2 + marginAdd,
 	rotate: layout.rect.rotate
 });
-/** 由 layout 构造的 Diamond（halfA/halfB 各加 margin） */
+/** 从 layout 构造 Diamond（halfA/halfB 各加 margin） */
 var diamondOf = (layout, marginAdd) => ({
 	x: layout.rect.x,
 	y: layout.rect.y,
@@ -53,9 +55,8 @@ var diamondOf = (layout, marginAdd) => ({
 	rotate: layout.rect.rotate
 });
 /**
-* 取节点 shape 在 toward 方向上的"附着点"——path 端点贴边用。
-* 按 shape 多态：rect / circle / ellipse / diamond 各自的 boundaryPoint。
-* margin > 0 时形状先外扩，让 path 在 border 外停 margin 个 user units。
+* 取节点 shape 在 toward 方向的附着点（path 端点贴边用）
+* @description 按 shape 多态调用各自 boundaryPoint；margin > 0 时形状先外扩，让 path 在 border 外停 margin
 */
 var boundaryPointOf = (layout, toward) => {
 	const m = layout.margin;
@@ -67,9 +68,8 @@ var boundaryPointOf = (layout, toward) => {
 	}
 };
 /**
-* 取节点 shape 的命名 anchor（center / north / east / north-east 等 9 个）。
-* **不应用 margin**——TikZ 语义中 explicit anchor 取的是视觉边界点，不涉及 outer sep。
-* 用于 `'A.north'` 这种语法落点。
+* 取节点 shape 命名 anchor（center / north / east / north-east 等 9 个）
+* @description 不应用 margin——TikZ 语义中 explicit anchor 取视觉边界点不涉及 outer sep；用于 `'A.north'` 落点
 */
 var anchorOf = (layout, name) => {
 	switch (layout.shape) {
@@ -79,10 +79,58 @@ var anchorOf = (layout, name) => {
 		case "diamond": return diamond.anchor(diamondOf(layout, 0), name);
 	}
 };
+/** 8 方向 label position → (anchorName, 单位向量)；above 视觉上方即 y 减小 */
+var LABEL_DIRECTION_MAP = {
+	above: {
+		anchor: "north",
+		vec: [0, -1]
+	},
+	below: {
+		anchor: "south",
+		vec: [0, 1]
+	},
+	left: {
+		anchor: "west",
+		vec: [-1, 0]
+	},
+	right: {
+		anchor: "east",
+		vec: [1, 0]
+	},
+	"above-left": {
+		anchor: "north-west",
+		vec: [-Math.SQRT1_2, -Math.SQRT1_2]
+	},
+	"above-right": {
+		anchor: "north-east",
+		vec: [Math.SQRT1_2, -Math.SQRT1_2]
+	},
+	"below-left": {
+		anchor: "south-west",
+		vec: [-Math.SQRT1_2, Math.SQRT1_2]
+	},
+	"below-right": {
+		anchor: "south-east",
+		vec: [Math.SQRT1_2, Math.SQRT1_2]
+	}
+};
+/**
+* 算 label 中心点
+* @description 8 方向：节点对应 anchor 出发按单位向量 × distance 外推；数字角度：先取 angleBoundary 边界点再沿 (cos,sin) × distance 外推
+*/
+var labelCenter = (layout, label) => {
+	if (typeof label.position === "number") {
+		const rad = label.position * Math.PI / 180;
+		const [bx, by] = angleBoundaryOf(layout, label.position);
+		return [bx + Math.cos(rad) * label.distance, by + Math.sin(rad) * label.distance];
+	}
+	const { anchor, vec } = LABEL_DIRECTION_MAP[label.position];
+	const [bx, by] = anchorOf(layout, anchor);
+	return [bx + vec[0] * label.distance, by + vec[1] * label.distance];
+};
 /**
-* 取节点 shape 在指定角度方向上的边界点。角度约定与 PolarPosition 一致（度数）：
-*   0° = +x（east），90° = +y（screen 下方）。
-* **不应用 margin**——同 anchorOf。用于 `'A.30'` 这种语法落点。
+* 取节点 shape 在指定角度方向的边界点
+* @description 角度约定与 PolarPosition 一致（度数：0°=+x，90°=+y 即 screen 下方）；不应用 margin（同 anchorOf）；用于 `'A.30'` 落点
 */
 var angleBoundaryOf = (layout, angleDeg) => {
 	const rad = angleDeg * Math.PI / 180;
@@ -95,14 +143,10 @@ var angleBoundaryOf = (layout, angleDeg) => {
 	}
 };
 /**
-* 把 IR Node 解析为内部 NodeLayout：
-* - 算出文本度量与 padding 推导出"内框"半轴 (innerHalfW/H)
-* - 按 shape 决定外接边界尺寸（circle 取半对角线、ellipse 各 ×√2、diamond 各 ×2）
-* - 解析 position（笛卡尔或极坐标）为几何中心
-* - IR 的 rotate（度数）转弧度存进 Rect.rotate
-* - 透传 margin / 样式属性
+* IR Node → 内部 NodeLayout
+* @description 文本度量 + padding 推内框半轴；按 shape 算外接边界（circle 取半对角线、ellipse ×√2、diamond ×2）；解析 position 为几何中心；rotate 度数转弧度
 */
-var layoutNode = (node, measureText, nodeIndex) => {
+var layoutNode = (node, measureText, nodeIndex, nodeDistance) => {
 	const sx = node.xScale ?? node.scale ?? 1;
 	const sy = node.yScale ?? node.scale ?? 1;
 	const fontScale = Math.min(sx, sy);
@@ -173,8 +217,22 @@ var layoutNode = (node, measureText, nodeIndex) => {
 			break;
 	}
 	const rotateDeg = node.rotate ?? 0;
-	const center = resolvePosition(node.position, nodeIndex);
-	if (!center) throw new Error(`Cannot resolve position for node ${node.id ?? "(unnamed)"}; polar.origin may reference an undefined node`);
+	const center = resolvePosition(node.position, nodeIndex, nodeDistance);
+	if (!center) throw new Error(`Cannot resolve position for node ${node.id ?? "(unnamed)"}; polar.origin or at.of may reference an undefined node`);
+	const labels = (node.label === void 0 ? void 0 : Array.isArray(node.label) ? node.label : [node.label])?.map((lab) => {
+		const labFont = lab.font;
+		return {
+			text: lab.text,
+			position: lab.position ?? "above",
+			distance: lab.distance ?? DEFAULT_LABEL_DISTANCE,
+			textColor: lab.textColor ?? node.textColor,
+			opacity: lab.opacity,
+			fontSize: (labFont?.size ?? baseFontSize) * fontScale,
+			fontFamily: labFont?.family ?? fontFamily,
+			fontWeight: labFont?.weight ?? fontWeight,
+			fontStyle: labFont?.style ?? fontStyle
+		};
+	});
 	return {
 		id: node.id,
 		shape,
@@ -204,10 +262,11 @@ var layoutNode = (node, measureText, nodeIndex) => {
 		strokeDasharray: resolveDashArray(node.dashArray, node.dashed, node.dotted),
 		roundedCorners: node.roundedCorners,
 		textColor: node.textColor,
-		opacity: node.opacity
+		opacity: node.opacity,
+		labels
 	};
 };
-/** rectangle shape 的 RectPrim */
+/** rectangle → RectPrim */
 var emitRectShape = (layout, round) => {
 	const halfW = layout.rect.width / 2;
 	const halfH = layout.rect.height / 2;
@@ -227,7 +286,7 @@ var emitRectShape = (layout, round) => {
 		opacity: layout.opacity
 	};
 };
-/** circle / ellipse shape 的 EllipsePrim（圆形 rx=ry） */
+/** circle/ellipse → EllipsePrim（圆形 rx=ry） */
 var emitEllipseShape = (layout, round) => ({
 	type: "ellipse",
 	cx: round(layout.rect.x),
@@ -242,7 +301,7 @@ var emitEllipseShape = (layout, round) => ({
 	strokeDasharray: layout.strokeDasharray,
 	opacity: layout.opacity
 });
-/** diamond shape 的 PathPrim（4 顶点 + Z 闭合） */
+/** diamond → PathPrim（4 顶点 + close 闭合） */
 var emitDiamondShape = (layout, round) => {
 	const diam = diamondOf(layout, 0);
 	const e = diamond.anchor(diam, "east");
@@ -251,7 +310,25 @@ var emitDiamondShape = (layout, round) => {
 	const s = diamond.anchor(diam, "south");
 	return {
 		type: "path",
-		d: `M ${round(e[0])} ${round(e[1])} L ${round(n[0])} ${round(n[1])} L ${round(w[0])} ${round(w[1])} L ${round(s[0])} ${round(s[1])} Z`,
+		commands: [
+			{
+				kind: "move",
+				to: [round(e[0]), round(e[1])]
+			},
+			{
+				kind: "line",
+				to: [round(n[0]), round(n[1])]
+			},
+			{
+				kind: "line",
+				to: [round(w[0]), round(w[1])]
+			},
+			{
+				kind: "line",
+				to: [round(s[0]), round(s[1])]
+			},
+			{ kind: "close" }
+		],
 		fill: layout.fill ?? "transparent",
 		fillOpacity: layout.fillOpacity,
 		stroke: layout.stroke ?? "currentColor",
@@ -262,12 +339,8 @@ var emitDiamondShape = (layout, round) => {
 	};
 };
 /**
-* 把 NodeLayout 翻译为 Scene primitives：
-* - shape 主体：按 shape 分发（rect / ellipse / path）
-* - text（如有内容）：始终走 TextPrim
-* - 若有旋转：外面套一层 GroupPrim 用 SVG `rotate(deg cx cy)` 实现
-*   （PathPrim 的 diamond 顶点已自带旋转坐标，但 text 需要 group 旋转，
-*    所以仍统一用 group 包裹）
+* NodeLayout → Scene primitives
+* @description shape 主体按 shape 分发（rect/ellipse/path）；text 始终走 TextPrim；有旋转时外层 GroupPrim 用 `rotate(deg cx cy)` 统一包裹（text 必须靠 group 旋转）
 */
 var emitNodePrimitives = (layout, round) => {
 	let shapePrim;
@@ -305,14 +378,39 @@ var emitNodePrimitives = (layout, round) => {
 			measuredHeight: round(layout.textHeight)
 		});
 	}
+	if (layout.labels) for (const lab of layout.labels) {
+		const [lx, ly] = labelCenter(layout, lab);
+		inner.push({
+			type: "text",
+			x: round(lx),
+			y: round(ly),
+			lines: [{ text: lab.text }],
+			fontSize: lab.fontSize,
+			fontFamily: lab.fontFamily,
+			fontWeight: lab.fontWeight,
+			fontStyle: lab.fontStyle,
+			align: "middle",
+			baseline: "middle",
+			lineHeight: round(lab.fontSize * DEFAULT_LINE_HEIGHT_FACTOR),
+			fill: lab.textColor ?? "currentColor",
+			opacity: lab.opacity ?? layout.opacity,
+			measuredWidth: 0,
+			measuredHeight: round(lab.fontSize)
+		});
+	}
 	if (layout.rotateDeg === 0) return inner;
 	return [{
 		type: "group",
-		transform: `rotate(${round(layout.rotateDeg)} ${round(layout.rect.x)} ${round(layout.rect.y)})`,
+		transforms: [{
+			kind: "rotate",
+			degrees: round(layout.rotateDeg),
+			cx: round(layout.rect.x),
+			cy: round(layout.rect.y)
+		}],
 		children: inner
 	}];
 };
-/** 返回 layout 的"未旋转"副本——用于先把 diamond 顶点按未旋转算，再由外层 group 统一旋转 */
+/** layout 的"未旋转"副本，让 diamond 顶点先按未旋转算，外层 group 统一旋转 */
 var unrotated = (layout) => ({
 	...layout,
 	rect: {

package/dist/es/compile/parseTarget.d.ts

@@ -1,5 +1,5 @@
 import { RectAnchor } from '../geometry/rect';
-/** 解析后的节点 ref 三态 */
+/** 节点 ref 解析后三态 */
 export type ParsedNodeRef = {
     kind: 'node';
     id: string;
@@ -13,13 +13,8 @@ export type ParsedNodeRef = {
     angle: number;
 };
 /**
- * 解析节点 ref 字符串。
- *
- * - 不带 `.`：node（auto-clip）
- * - 带 `.` 后纯数字：angle（toward 方向上的边界点，与 PolarPosition 同角度约定）
- * - 带 `.` 后字母 / 连字符：anchor（命中 ANCHOR_NAMES 才合法，否则抛错）
- *
- * 抛错路径：未知 anchor 名（避免静默吞掉拼写错误）。
+ * 解析节点 ref 字符串
+ * @description 不带 `.`→node(auto-clip)；带 `.` 后纯数字→angle；带 `.` 后字母/连字符→anchor（不命中 ANCHOR_NAMES 抛错避免静默吞拼写错误）
  */
 export declare const parseNodeRef: (s: string) => ParsedNodeRef;
 //# sourceMappingURL=parseTarget.d.ts.map

package/dist/es/compile/parseTarget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseTarget.d.ts","sourceRoot":"","sources":["../../../src/compile/parseTarget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQjE,oBAAoB;AACpB,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,KAAG,aAcxC,CAAC"}
+{"version":3,"file":"parseTarget.d.ts","sourceRoot":"","sources":["../../../src/compile/parseTarget.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQjE,mBAAmB;AACnB,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,KAAG,aAcxC,CAAC"}

package/dist/es/compile/parseTarget.js

@@ -1,28 +1,16 @@
 import { RECT_ANCHORS } from "../geometry/rect.js";
 //#region src/compile/parseTarget.ts
 /**
-* 节点 ref 字符串扩展语法（ADR-0004）：
-*
-*   `'A'`         → 节点 A，由 path 自动 boundary clip（auto 模式）
-*   `'A.<name>'`  → 节点 A 的命名 anchor（center/north/south/east/west/north-east/...）
-*   `'A.<deg>'`   → 节点 A 在 degree 角度方向上的边界点（同 PolarPosition 角度约定）
-*
-* id 约束：`[A-Za-z_][\w-]*`——禁数字开头、禁含 `.`（与 anchor 分隔符冲突）；
-* anchor 名只接受 alpha.1 首批 9 个 RECT_ANCHORS（其余如 'text' / 'base' / 'mid'
-* 留 alpha.2 + 字体改造时再支持）；角度纯数字（含可选 `.`/`-`）。
+* 节点 ref 字符串扩展语法
+* @description `'A'`→节点（auto boundary clip）；`'A.<name>'`→命名 anchor（center/north/.../north-east）；`'A.<deg>'`→角度方向边界点（同 PolarPosition 约定）。id 约束 `[A-Za-z_][\w-]*` 禁数字开头与 `.`；角度纯数字含可选 `.`/`-`
 */
-/** alpha.1 支持的 anchor 名集合（RECT_ANCHORS 的 9 个值） */
+/** RECT_ANCHORS 的 9 个 anchor 名 */
 var ANCHOR_NAMES = new Set(Object.values(RECT_ANCHORS));
-/** 纯数字（可选小数 / 负号），用于识别 `A.30` / `A.-45` / `A.180.5` */
+/** 纯数字识别 `A.30` / `A.-45` / `A.180.5` */
 var ANGLE_RE = /^-?\d+(\.\d+)?$/;
 /**
-* 解析节点 ref 字符串。
-*
-* - 不带 `.`：node（auto-clip）
-* - 带 `.` 后纯数字：angle（toward 方向上的边界点，与 PolarPosition 同角度约定）
-* - 带 `.` 后字母 / 连字符：anchor（命中 ANCHOR_NAMES 才合法，否则抛错）
-*
-* 抛错路径：未知 anchor 名（避免静默吞掉拼写错误）。
+* 解析节点 ref 字符串
+* @description 不带 `.`→node(auto-clip)；带 `.` 后纯数字→angle；带 `.` 后字母/连字符→anchor（不命中 ANCHOR_NAMES 抛错避免静默吞拼写错误）
 */
 var parseNodeRef = (s) => {
 	const dot = s.indexOf(".");
@@ -37,7 +25,7 @@ var parseNodeRef = (s) => {
 		id,
 		angle: Number(tail)
 	};
-	if (!ANCHOR_NAMES.has(tail)) throw new Error(`parseNodeRef: unknown anchor '${tail}' in '${s}' (alpha.1 supports: ${[...ANCHOR_NAMES].join(", ")})`);
+	if (!ANCHOR_NAMES.has(tail)) throw new Error(`parseNodeRef: unknown anchor '${tail}' in '${s}' (supports: ${[...ANCHOR_NAMES].join(", ")})`);
 	return {
 		kind: "anchor",
 		id,