@retikz/core 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/lib/compile/position.cjs

@@ -1,19 +1,46 @@
 //#region src/compile/position.ts
+/** 默认相对定位距离（user units）——CompileOptions.nodeDistance 未提供时使用 */
+var DEFAULT_NODE_DISTANCE = 1;
 /**
-* 把 IR 里出现的位置形态（笛卡尔 / 极坐标 / 节点 id）解析为笛卡尔位置。
-* 极坐标的 origin 可递归 / 可引用节点 id；按节点定义顺序处理（前向引用要求节点先定义）。
-* 解析失败返回 null（如引用了未定义节点）。
+* 8 方向到屏幕坐标系（y 向下）单位向量的映射。
+* 视觉语义：above 在视觉上方（y 减小），below 在视觉下方（y 增大）。
+* 4 对角分量为 1/√2，保证斜向距离与水平 / 垂直距离等长（对角点位于半径 = distance 的圆周上）。
 */
-var resolvePosition = (pos, nodeMap) => {
+var DIRECTION_VECTOR = {
+	above: [0, -1],
+	below: [0, 1],
+	left: [-1, 0],
+	right: [1, 0],
+	"above-left": [-Math.SQRT1_2, -Math.SQRT1_2],
+	"above-right": [Math.SQRT1_2, -Math.SQRT1_2],
+	"below-left": [-Math.SQRT1_2, Math.SQRT1_2],
+	"below-right": [Math.SQRT1_2, Math.SQRT1_2]
+};
+/**
+* 把 IR 里出现的位置形态（笛卡尔 / 极坐标 / 相对定位 / 节点 id）解析为笛卡尔位置。
+* - 极坐标的 origin 可递归 / 可引用节点 id
+* - 相对定位的 of 必须引用已定义的节点 / coordinate（前向引用要求被引节点先出现）
+* - 解析失败返回 null（如引用了未定义节点）
+*
+* `nodeDistance` 是 Tikz 容器 prop 注入的相对定位默认距离；AtPosition 自带 distance 时优先用自带值。
+*/
+var resolvePosition = (pos, nodeMap, nodeDistance = DEFAULT_NODE_DISTANCE) => {
 	if (typeof pos === "string") {
 		const node = nodeMap.get(pos);
 		return node ? [node.rect.x, node.rect.y] : null;
 	}
 	if (Array.isArray(pos)) return pos;
+	if ("direction" in pos) {
+		const ref = nodeMap.get(pos.of);
+		if (!ref) return null;
+		const distance = pos.distance ?? nodeDistance;
+		const [dx, dy] = DIRECTION_VECTOR[pos.direction];
+		return [ref.rect.x + dx * distance, ref.rect.y + dy * distance];
+	}
 	let origin;
 	if (!pos.origin) origin = [0, 0];
 	else {
-		const resolved = resolvePosition(pos.origin, nodeMap);
+		const resolved = resolvePosition(pos.origin, nodeMap, nodeDistance);
 		if (!resolved) return null;
 		origin = resolved;
 	}

package/dist/lib/compile/position.d.ts

@@ -1,9 +1,12 @@
-import { IRPosition, PolarPosition } from '../ir';
+import { IRAtPosition, IRPosition, PolarPosition } from '../ir';
 import { NodeLayout } from './node';
 /**
- * 把 IR 里出现的位置形态（笛卡尔 / 极坐标 / 节点 id）解析为笛卡尔位置。
- * 极坐标的 origin 可递归 / 可引用节点 id；按节点定义顺序处理（前向引用要求节点先定义）。
- * 解析失败返回 null（如引用了未定义节点）。
+ * 把 IR 里出现的位置形态（笛卡尔 / 极坐标 / 相对定位 / 节点 id）解析为笛卡尔位置。
+ * - 极坐标的 origin 可递归 / 可引用节点 id
+ * - 相对定位的 of 必须引用已定义的节点 / coordinate（前向引用要求被引节点先出现）
+ * - 解析失败返回 null（如引用了未定义节点）
+ *
+ * `nodeDistance` 是 Tikz 容器 prop 注入的相对定位默认距离；AtPosition 自带 distance 时优先用自带值。
  */
-export declare const resolvePosition: (pos: IRPosition | PolarPosition | string, nodeMap: Map<string, NodeLayout>) => IRPosition | null;
+export declare const resolvePosition: (pos: IRPosition | PolarPosition | IRAtPosition | string, nodeMap: Map<string, NodeLayout>, nodeDistance?: number) => IRPosition | null;
 //# sourceMappingURL=position.d.ts.map

package/dist/lib/compile/position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/compile/position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,UAAU,GAAG,aAAa,GAAG,MAAM,EACxC,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KAC/B,UAAU,GAAG,IAoBf,CAAC"}
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/compile/position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAClF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAqBzC;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,MAAM,EACvD,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,eAAc,MAA8B,KAC3C,UAAU,GAAG,IA4Bf,CAAC"}

package/dist/lib/geometry/arc.cjs

@@ -0,0 +1,55 @@
+//#region src/geometry/arc.ts
+var DEG_TO_RAD = Math.PI / 180;
+/**
+* 给定圆心、半径、角度（度，与 polar.toPosition 同约定），返回圆周上对应点。
+*/
+var arcEndPoint = (center, radius, angleDeg) => {
+	const rad = angleDeg * DEG_TO_RAD;
+	return [center[0] + Math.cos(rad) * radius, center[1] + Math.sin(rad) * radius];
+};
+/**
+* 计算 SVG `<path>` A 命令需要的 large-arc-flag 与 sweep-flag。
+*
+* - `largeArc`：弧跨度 `|endAngle - startAngle|` 严格大于 180° 时为 1。
+* - `sweep`：`endAngle >= startAngle` 时为 1，否则为 0；与"角度增加方向 = 在
+*   SVG 屏幕上视觉顺时针"一致——因为我们投影时未翻转 y，SVG sweep=1（屏幕 CW）
+*   恰好等价 math 角度增加。
+*
+* 边界：`|Δ|=180°` 时 `largeArc=0`（半弧不算大弧）；恰好同点 `|Δ|=0` 也返回 0。
+*/
+var arcSvgFlags = (startAngleDeg, endAngleDeg) => {
+	return {
+		largeArc: Math.abs(endAngleDeg - startAngleDeg) > 180 ? 1 : 0,
+		sweep: endAngleDeg >= startAngleDeg ? 1 : 0
+	};
+};
+/**
+* 弧的 bounding box 极值候选点：起点、终点，以及 `[startAngle, endAngle]` 区间
+* 里所有 90°·k 的基本方向（0°、90°、180°、270° 及其周期延拓）对应的圆周点。
+*
+* 这些点是计算视图框（viewBox）/ bbox 时必须考虑的候选——因为弧线投影到 x/y
+* 轴的极值只可能在弧端点或圆周上的轴向四点处出现。
+*
+* 说明：
+* - 接受 `endAngle < startAngle`（CW math 方向）：以 `min..max` 区间扫描 90°·k；
+*   语义上是"无论扫描方向，此弧覆盖到的角度区间内的基本方向都算极值候选"。
+* - 跨 360°（如 270° → 450°）也按数值区间处理，正确收录中间穿越的 0°、90° 等。
+* - 不去重：若起点恰好落在 90°·k 上会同时出现两次，调用方根据需要再处理。
+*/
+var arcBoundingPoints = (center, radius, startAngleDeg, endAngleDeg) => {
+	const points = [arcEndPoint(center, radius, startAngleDeg), arcEndPoint(center, radius, endAngleDeg)];
+	const lo = Math.min(startAngleDeg, endAngleDeg);
+	const hi = Math.max(startAngleDeg, endAngleDeg);
+	const kStart = Math.ceil(lo / 90);
+	const kEnd = Math.floor(hi / 90);
+	for (let k = kStart; k <= kEnd; k++) {
+		const angle = k * 90;
+		if (angle === startAngleDeg || angle === endAngleDeg) continue;
+		points.push(arcEndPoint(center, radius, angle));
+	}
+	return points;
+};
+//#endregion
+exports.arcBoundingPoints = arcBoundingPoints;
+exports.arcEndPoint = arcEndPoint;
+exports.arcSvgFlags = arcSvgFlags;

package/dist/lib/geometry/arc.d.ts

@@ -0,0 +1,34 @@
+import { Position } from './point';
+/**
+ * 给定圆心、半径、角度（度，与 polar.toPosition 同约定），返回圆周上对应点。
+ */
+export declare const arcEndPoint: (center: Position, radius: number, angleDeg: number) => Position;
+/**
+ * 计算 SVG `<path>` A 命令需要的 large-arc-flag 与 sweep-flag。
+ *
+ * - `largeArc`：弧跨度 `|endAngle - startAngle|` 严格大于 180° 时为 1。
+ * - `sweep`：`endAngle >= startAngle` 时为 1，否则为 0；与"角度增加方向 = 在
+ *   SVG 屏幕上视觉顺时针"一致——因为我们投影时未翻转 y，SVG sweep=1（屏幕 CW）
+ *   恰好等价 math 角度增加。
+ *
+ * 边界：`|Δ|=180°` 时 `largeArc=0`（半弧不算大弧）；恰好同点 `|Δ|=0` 也返回 0。
+ */
+export declare const arcSvgFlags: (startAngleDeg: number, endAngleDeg: number) => {
+    largeArc: 0 | 1;
+    sweep: 0 | 1;
+};
+/**
+ * 弧的 bounding box 极值候选点：起点、终点，以及 `[startAngle, endAngle]` 区间
+ * 里所有 90°·k 的基本方向（0°、90°、180°、270° 及其周期延拓）对应的圆周点。
+ *
+ * 这些点是计算视图框（viewBox）/ bbox 时必须考虑的候选——因为弧线投影到 x/y
+ * 轴的极值只可能在弧端点或圆周上的轴向四点处出现。
+ *
+ * 说明：
+ * - 接受 `endAngle < startAngle`（CW math 方向）：以 `min..max` 区间扫描 90°·k；
+ *   语义上是"无论扫描方向，此弧覆盖到的角度区间内的基本方向都算极值候选"。
+ * - 跨 360°（如 270° → 450°）也按数值区间处理，正确收录中间穿越的 0°、90° 等。
+ * - 不去重：若起点恰好落在 90°·k 上会同时出现两次，调用方根据需要再处理。
+ */
+export declare const arcBoundingPoints: (center: Position, radius: number, startAngleDeg: number, endAngleDeg: number) => Array<Position>;
+//# sourceMappingURL=arc.d.ts.map

package/dist/lib/geometry/arc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arc.d.ts","sourceRoot":"","sources":["../../../src/geometry/arc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAkBxC;;GAEG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,QAAQ,EAChB,QAAQ,MAAM,EACd,UAAU,MAAM,KACf,QAMF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GACtB,eAAe,MAAM,EACrB,aAAa,MAAM,KAClB;IAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAA;CAMjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,QAAQ,EAChB,QAAQ,MAAM,EACd,eAAe,MAAM,EACrB,aAAa,MAAM,KAClB,KAAK,CAAC,QAAQ,CAmBhB,CAAC"}

package/dist/lib/geometry/bend.cjs

@@ -0,0 +1,29 @@
+//#region src/geometry/bend.ts
+/**
+* 用 cubic Bezier 拟合 from→to 的弧形 bend。
+*
+* 算法（ADR-0001）：
+* 1. apex offset = chord × tan(bendAngle / 2)（沿 path 法向 left / right 偏移量）
+* 2. 控制点取 chord 1/3 / 2/3 处沿法向偏移；为让 cubic 在 t=0.5 处穿过 apex，
+*    控制点 offset = (4/3) × apex offset（推导：B(0.5) = midpoint + (3/4)·s·n）
+*
+* 法向定义（SVG y 向下，"left/right" 按视觉，不按数学）：
+*   chord direction = (dx, dy) / |chord|
+*   visual-left normal  =  ( dy, -dx) / |chord|   （从 from 看向 to，向左偏）
+*   visual-right normal =  (-dy,  dx) / |chord|
+*
+* chord 长度为 0 时无方向可推，两个控制点都返回 from。
+*/
+var bendControlPoints = (from, to, direction, bendAngle) => {
+	const dx = to[0] - from[0];
+	const dy = to[1] - from[1];
+	const chord = Math.hypot(dx, dy);
+	if (chord === 0) return [[from[0], from[1]], [from[0], from[1]]];
+	const sign = direction === "left" ? 1 : -1;
+	const nx = dy / chord * sign;
+	const ny = -dx / chord * sign;
+	const ctlOffset = 4 / 3 * (chord * Math.tan(bendAngle * Math.PI / 180 / 2));
+	return [[from[0] + dx / 3 + ctlOffset * nx, from[1] + dy / 3 + ctlOffset * ny], [from[0] + 2 * dx / 3 + ctlOffset * nx, from[1] + 2 * dy / 3 + ctlOffset * ny]];
+};
+//#endregion
+exports.bendControlPoints = bendControlPoints;

package/dist/lib/geometry/bend.d.ts

@@ -0,0 +1,18 @@
+import { Position } from './point';
+/**
+ * 用 cubic Bezier 拟合 from→to 的弧形 bend。
+ *
+ * 算法（ADR-0001）：
+ * 1. apex offset = chord × tan(bendAngle / 2)（沿 path 法向 left / right 偏移量）
+ * 2. 控制点取 chord 1/3 / 2/3 处沿法向偏移；为让 cubic 在 t=0.5 处穿过 apex，
+ *    控制点 offset = (4/3) × apex offset（推导：B(0.5) = midpoint + (3/4)·s·n）
+ *
+ * 法向定义（SVG y 向下，"left/right" 按视觉，不按数学）：
+ *   chord direction = (dx, dy) / |chord|
+ *   visual-left normal  =  ( dy, -dx) / |chord|   （从 from 看向 to，向左偏）
+ *   visual-right normal =  (-dy,  dx) / |chord|
+ *
+ * chord 长度为 0 时无方向可推，两个控制点都返回 from。
+ */
+export declare const bendControlPoints: (from: Position, to: Position, direction: "left" | "right", bendAngle: number) => [Position, Position];
+//# sourceMappingURL=bend.d.ts.map

package/dist/lib/geometry/bend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bend.d.ts","sourceRoot":"","sources":["../../../src/geometry/bend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,QAAQ,EACd,IAAI,QAAQ,EACZ,WAAW,MAAM,GAAG,OAAO,EAC3B,WAAW,MAAM,KAChB,CAAC,QAAQ,EAAE,QAAQ,CAgBrB,CAAC"}

package/dist/lib/geometry/index.d.ts

@@ -4,4 +4,7 @@ export * from './circle';
 export * from './ellipse';
 export * from './diamond';
 export * from './polar';
+export * from './bend';
+export * from './arc';
+export * from './segment';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/geometry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geometry/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geometry/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC"}

package/dist/lib/geometry/segment.cjs

@@ -0,0 +1,88 @@
+//#region src/geometry/segment.ts
+var DEG_TO_RAD = Math.PI / 180;
+var normalize = (v) => {
+	const len = Math.hypot(v[0], v[1]);
+	if (len === 0) return [1, 0];
+	return [v[0] / len, v[1] / len];
+};
+/** 直线段 from → to */
+var lineSegmentSample = (from, to, t) => ({
+	point: [from[0] + (to[0] - from[0]) * t, from[1] + (to[1] - from[1]) * t],
+	tangent: normalize([to[0] - from[0], to[1] - from[1]])
+});
+/**
+* 二次贝塞尔 from → control → to。
+* P(t)  = (1-t)²·P0 + 2(1-t)t·P1 + t²·P2
+* P'(t) = 2(1-t)(P1-P0) + 2t(P2-P1)
+*/
+var quadSegmentSample = (from, control, to, t) => {
+	const u = 1 - t;
+	return {
+		point: [u * u * from[0] + 2 * u * t * control[0] + t * t * to[0], u * u * from[1] + 2 * u * t * control[1] + t * t * to[1]],
+		tangent: normalize([2 * u * (control[0] - from[0]) + 2 * t * (to[0] - control[0]), 2 * u * (control[1] - from[1]) + 2 * t * (to[1] - control[1])])
+	};
+};
+/**
+* 三次贝塞尔 from → c1 → c2 → to。
+* P'(t) = 3(1-t)²(P1-P0) + 6(1-t)t(P2-P1) + 3t²(P3-P2)
+*/
+var cubicSegmentSample = (from, c1, c2, to, t) => {
+	const u = 1 - t;
+	return {
+		point: [u * u * u * from[0] + 3 * u * u * t * c1[0] + 3 * u * t * t * c2[0] + t * t * t * to[0], u * u * u * from[1] + 3 * u * u * t * c1[1] + 3 * u * t * t * c2[1] + t * t * t * to[1]],
+		tangent: normalize([3 * u * u * (c1[0] - from[0]) + 6 * u * t * (c2[0] - c1[0]) + 3 * t * t * (to[0] - c2[0]), 3 * u * u * (c1[1] - from[1]) + 6 * u * t * (c2[1] - c1[1]) + 3 * t * t * (to[1] - c2[1])])
+	};
+};
+/**
+* 折角段 from → corner → to。
+* t∈[0, 0.5] 走第一段（参数 2t）；t∈(0.5, 1] 走第二段（参数 2t-1）。
+* t=0.5 落在 corner，切线取第一段方向（与"靠近 prev 一侧"一致）。
+*/
+var foldSegmentSample = (from, corner, to, t) => {
+	if (t <= .5) return lineSegmentSample(from, corner, t * 2);
+	return lineSegmentSample(corner, to, t * 2 - 1);
+};
+/**
+* 弧段（与 ir/path arc 同约定，角度单位为度）。
+* 切线沿"扫描方向"——endAngle ≥ startAngle 时为 (-sin, cos)，否则反向。
+*/
+var arcSegmentSample = (center, radius, startAngleDeg, endAngleDeg, t) => {
+	const rad = (startAngleDeg + t * (endAngleDeg - startAngleDeg)) * DEG_TO_RAD;
+	const cos = Math.cos(rad);
+	const sin = Math.sin(rad);
+	const sweepSign = endAngleDeg >= startAngleDeg ? 1 : -1;
+	return {
+		point: [center[0] + radius * cos, center[1] + radius * sin],
+		tangent: normalize([-sin * sweepSign, cos * sweepSign])
+	};
+};
+/**
+* 整圆——从 0°（east）开始，与 compile/path circlePath 输出方向（右→左→右，sweep=1）一致。
+*/
+var circleSegmentSample = (center, radius, t) => {
+	const rad = t * 360 * DEG_TO_RAD;
+	const cos = Math.cos(rad);
+	const sin = Math.sin(rad);
+	return {
+		point: [center[0] + radius * cos, center[1] + radius * sin],
+		tangent: normalize([-sin, cos])
+	};
+};
+/** 整椭圆——参数化 (rx·cos(2πt), ry·sin(2πt)) */
+var ellipseSegmentSample = (center, rx, ry, t) => {
+	const rad = t * 360 * DEG_TO_RAD;
+	const cos = Math.cos(rad);
+	const sin = Math.sin(rad);
+	return {
+		point: [center[0] + rx * cos, center[1] + ry * sin],
+		tangent: normalize([-rx * sin, ry * cos])
+	};
+};
+//#endregion
+exports.arcSegmentSample = arcSegmentSample;
+exports.circleSegmentSample = circleSegmentSample;
+exports.cubicSegmentSample = cubicSegmentSample;
+exports.ellipseSegmentSample = ellipseSegmentSample;
+exports.foldSegmentSample = foldSegmentSample;
+exports.lineSegmentSample = lineSegmentSample;
+exports.quadSegmentSample = quadSegmentSample;

package/dist/lib/geometry/segment.d.ts

@@ -0,0 +1,38 @@
+import { Position } from './point';
+export type SegmentSample = {
+    /** t 处的点坐标 */
+    point: Position;
+    /** t 处的切线方向（单位向量；零向量时回退到 [1, 0]） */
+    tangent: Position;
+};
+/** 直线段 from → to */
+export declare const lineSegmentSample: (from: Position, to: Position, t: number) => SegmentSample;
+/**
+ * 二次贝塞尔 from → control → to。
+ * P(t)  = (1-t)²·P0 + 2(1-t)t·P1 + t²·P2
+ * P'(t) = 2(1-t)(P1-P0) + 2t(P2-P1)
+ */
+export declare const quadSegmentSample: (from: Position, control: Position, to: Position, t: number) => SegmentSample;
+/**
+ * 三次贝塞尔 from → c1 → c2 → to。
+ * P'(t) = 3(1-t)²(P1-P0) + 6(1-t)t(P2-P1) + 3t²(P3-P2)
+ */
+export declare const cubicSegmentSample: (from: Position, c1: Position, c2: Position, to: Position, t: number) => SegmentSample;
+/**
+ * 折角段 from → corner → to。
+ * t∈[0, 0.5] 走第一段（参数 2t）；t∈(0.5, 1] 走第二段（参数 2t-1）。
+ * t=0.5 落在 corner，切线取第一段方向（与"靠近 prev 一侧"一致）。
+ */
+export declare const foldSegmentSample: (from: Position, corner: Position, to: Position, t: number) => SegmentSample;
+/**
+ * 弧段（与 ir/path arc 同约定，角度单位为度）。
+ * 切线沿"扫描方向"——endAngle ≥ startAngle 时为 (-sin, cos)，否则反向。
+ */
+export declare const arcSegmentSample: (center: Position, radius: number, startAngleDeg: number, endAngleDeg: number, t: number) => SegmentSample;
+/**
+ * 整圆——从 0°（east）开始，与 compile/path circlePath 输出方向（右→左→右，sweep=1）一致。
+ */
+export declare const circleSegmentSample: (center: Position, radius: number, t: number) => SegmentSample;
+/** 整椭圆——参数化 (rx·cos(2πt), ry·sin(2πt)) */
+export declare const ellipseSegmentSample: (center: Position, rx: number, ry: number, t: number) => SegmentSample;
+//# sourceMappingURL=segment.d.ts.map

package/dist/lib/geometry/segment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment.d.ts","sourceRoot":"","sources":["../../../src/geometry/segment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAuBxC,MAAM,MAAM,aAAa,GAAG;IAC1B,cAAc;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;AAQF,oBAAoB;AACpB,eAAO,MAAM,iBAAiB,GAC5B,MAAM,QAAQ,EACd,IAAI,QAAQ,EACZ,GAAG,MAAM,KACR,aAGD,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,QAAQ,EACd,SAAS,QAAQ,EACjB,IAAI,QAAQ,EACZ,GAAG,MAAM,KACR,aASF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,QAAQ,EACd,IAAI,QAAQ,EACZ,IAAI,QAAQ,EACZ,IAAI,QAAQ,EACZ,GAAG,MAAM,KACR,aAqBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,QAAQ,EACd,QAAQ,QAAQ,EAChB,IAAI,QAAQ,EACZ,GAAG,MAAM,KACR,aAGF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,QAAQ,EAChB,QAAQ,MAAM,EACd,eAAe,MAAM,EACrB,aAAa,MAAM,EACnB,GAAG,MAAM,KACR,aAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,QAAQ,EAChB,QAAQ,MAAM,EACd,GAAG,MAAM,KACR,aASF,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,QAAQ,EAChB,IAAI,MAAM,EACV,IAAI,MAAM,EACV,GAAG,MAAM,KACR,aASF,CAAC"}

package/dist/lib/index.cjs

@@ -1,11 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_position = require("./ir/position/position.cjs");
 const require_polar_position = require("./ir/position/polar-position.cjs");
+const require_at_position = require("./ir/position/at-position.cjs");
 const require_arrow = require("./ir/path/arrow.cjs");
 const require_target = require("./ir/path/target.cjs");
 const require_step = require("./ir/path/step.cjs");
 const require_path = require("./ir/path/path.cjs");
 const require_node = require("./ir/node.cjs");
+const require_coordinate = require("./ir/coordinate.cjs");
 const require_scene = require("./ir/scene.cjs");
 const require_rect = require("./geometry/rect.cjs");
 const require_circle = require("./geometry/circle.cjs");
@@ -13,14 +15,25 @@ const require_diamond = require("./geometry/diamond.cjs");
 const require_ellipse = require("./geometry/ellipse.cjs");
 const require_text_metrics = require("./compile/text-metrics.cjs");
 const require_compile = require("./compile/compile.cjs");
+const require_parseTargetSugar = require("./parsers/parseTargetSugar.cjs");
 const require_parseWay = require("./parsers/parseWay.cjs");
 const require_polar = require("./geometry/polar.cjs");
 const require_point = require("./geometry/point.cjs");
 exports.ARROW_SHAPES = require_arrow.ARROW_SHAPES;
+exports.AT_DIRECTIONS = require_at_position.AT_DIRECTIONS;
+exports.ArcStepSchema = require_step.ArcStepSchema;
+exports.AtPositionSchema = require_at_position.AtPositionSchema;
+exports.BendStepSchema = require_step.BendStepSchema;
 exports.CURRENT_IR_VERSION = require_scene.CURRENT_IR_VERSION;
 exports.ChildSchema = require_scene.ChildSchema;
+exports.CirclePathStepSchema = require_step.CirclePathStepSchema;
+exports.ControlPointSchema = require_step.ControlPointSchema;
+exports.CoordinateSchema = require_coordinate.CoordinateSchema;
+exports.CubicStepSchema = require_step.CubicStepSchema;
+exports.CurveStepSchema = require_step.CurveStepSchema;
 exports.CycleStepSchema = require_step.CycleStepSchema;
 exports.DrawWay = require_parseWay.DrawWay;
+exports.EllipsePathStepSchema = require_step.EllipsePathStepSchema;
 exports.FoldStepSchema = require_step.FoldStepSchema;
 exports.FontSchema = require_node.FontSchema;
 exports.LineSpecSchema = require_node.LineSpecSchema;
@@ -28,13 +41,17 @@ exports.LineStepSchema = require_step.LineStepSchema;
 exports.MoveStepSchema = require_step.MoveStepSchema;
 exports.NODE_SHAPES = require_node.NODE_SHAPES;
 exports.NODE_TEXT_ALIGNS = require_node.NODE_TEXT_ALIGNS;
+exports.NodeLabelSchema = require_node.NodeLabelSchema;
 exports.NodeSchema = require_node.NodeSchema;
 exports.NodeTextSchema = require_node.NodeTextSchema;
 exports.PathSchema = require_path.PathSchema;
 exports.PolarPositionSchema = require_polar_position.PolarPositionSchema;
 exports.PositionSchema = require_position.PositionSchema;
 exports.RECT_ANCHORS = require_rect.RECT_ANCHORS;
+exports.RelAccumulateTargetSchema = require_target.RelAccumulateTargetSchema;
+exports.RelTargetSchema = require_target.RelTargetSchema;
 exports.SceneSchema = require_scene.SceneSchema;
+exports.StepLabelSchema = require_step.StepLabelSchema;
 exports.StepSchema = require_step.StepSchema;
 exports.TargetSchema = require_target.TargetSchema;
 exports.circle = require_circle.circle;
@@ -42,6 +59,7 @@ exports.compileToScene = require_compile.compileToScene;
 exports.diamond = require_diamond.diamond;
 exports.ellipse = require_ellipse.ellipse;
 exports.fallbackMeasurer = require_text_metrics.fallbackMeasurer;
+exports.parseTargetSugar = require_parseTargetSugar.parseTargetSugar;
 exports.parseWay = require_parseWay.parseWay;
 exports.point = require_point.point;
 exports.polar = require_polar.polar;

package/dist/lib/index.d.ts

@@ -6,14 +6,14 @@
  *
  * 本包零 React、零 DOM 依赖。
  */
-export { PositionSchema, PolarPositionSchema, TargetSchema, MoveStepSchema, LineStepSchema, FoldStepSchema, CycleStepSchema, StepSchema, NodeSchema, FontSchema, NodeTextSchema, LineSpecSchema, PathSchema, ChildSchema, SceneSchema, CURRENT_IR_VERSION, } from './ir';
-export type { IRPosition, IRTarget, IRMoveStep, IRLineStep, IRFoldStep, IRCycleStep, IRStep, IRNode, IRFont, IRLineSpec, IRPath, IRChild, IR, ArrowShape, NodeShape, NodeTextAlign, } from './ir';
+export { PositionSchema, PolarPositionSchema, AtPositionSchema, AT_DIRECTIONS, TargetSchema, RelTargetSchema, RelAccumulateTargetSchema, MoveStepSchema, LineStepSchema, FoldStepSchema, CycleStepSchema, CurveStepSchema, CubicStepSchema, BendStepSchema, ArcStepSchema, CirclePathStepSchema, EllipsePathStepSchema, ControlPointSchema, StepLabelSchema, StepSchema, NodeSchema, NodeLabelSchema, CoordinateSchema, FontSchema, NodeTextSchema, LineSpecSchema, PathSchema, ChildSchema, SceneSchema, CURRENT_IR_VERSION, } from './ir';
+export type { IRPosition, IRAtPosition, AtDirection, IRTarget, IRRelTarget, IRRelAccumulateTarget, IRMoveStep, IRLineStep, IRFoldStep, IRCycleStep, IRCurveStep, IRCubicStep, IRBendStep, IRArcStep, IRCirclePathStep, IREllipsePathStep, IRControlPoint, IRStepLabel, IRStep, IRNode, IRNodeLabel, IRCoordinate, IRFont, IRLineSpec, IRPath, IRChild, IR, ArrowShape, NodeShape, NodeTextAlign, } from './ir';
 export { ARROW_SHAPES, NODE_SHAPES, NODE_TEXT_ALIGNS } from './ir';
 export type { ScenePrimitive, RectPrim, EllipsePrim, TextPrim, TextLine, PathPrim, GroupPrim, ViewBox, Scene, } from './primitive';
 export type { FontSpec, TextMetrics, TextMeasurer, CompileOptions, } from './compile';
 export { fallbackMeasurer, compileToScene } from './compile';
-export type { WayItem, WayDSL, WayCycle, WayVia } from './parsers';
-export { parseWay, DrawWay } from './parsers';
+export type { WayItem, WayDSL, WayCycle, WayVia, WayRelItem, WayLabel, WayLabelOp, } from './parsers';
+export { parseWay, DrawWay, parseTargetSugar } from './parsers';
 export type { Position, Rect, RectAnchor, Circle, CircleAnchor, Ellipse, EllipseAnchor, Diamond, DiamondAnchor, PolarPosition, } from './geometry';
 export { point, rect, circle, ellipse, diamond, RECT_ANCHORS, polar } from './geometry';
 export type { ValueOf } from './types';

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,GACnB,MAAM,MAAM,CAAC;AACd,YAAY,EACV,UAAU,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,MAAM,EACN,MAAM,EACN,MAAM,EACN,UAAU,EACV,MAAM,EACN,OAAO,EACP,EAAE,EACF,UAAU,EACV,SAAS,EACT,aAAa,GACd,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAGnE,YAAY,EACV,cAAc,EACd,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,OAAO,EACP,KAAK,GACN,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG7D,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAI9C,YAAY,EACV,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,MAAM,EACN,YAAY,EACZ,OAAO,EACP,aAAa,EACb,OAAO,EACP,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxF,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,GACnB,MAAM,MAAM,CAAC;AACd,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,WAAW,EACX,qBAAqB,EACrB,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,MAAM,EACN,MAAM,EACN,WAAW,EACX,YAAY,EACZ,MAAM,EACN,UAAU,EACV,MAAM,EACN,OAAO,EACP,EAAE,EACF,UAAU,EACV,SAAS,EACT,aAAa,GACd,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAGnE,YAAY,EACV,cAAc,EACd,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,OAAO,EACP,KAAK,GACN,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG7D,YAAY,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,MAAM,EACN,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAIhE,YAAY,EACV,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,MAAM,EACN,YAAY,EACZ,OAAO,EACP,aAAa,EACb,OAAO,EACP,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxF,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/lib/ir/coordinate.cjs

@@ -0,0 +1,27 @@
+const require_position = require("./position/position.cjs");
+const require_polar_position = require("./position/polar-position.cjs");
+const require_at_position = require("./position/at-position.cjs");
+let zod = require("zod");
+//#region src/ir/coordinate.ts
+/**
+* Coordinate（占位节点）——TikZ `\coordinate (m) at (3,2);` 同义。
+*
+* 命名一个点供后续 path / at 引用，自身不绘制任何图形。
+* 支持笛卡尔 / 极坐标 / 相对定位三种 position 形态，与 `Node.position` 完全一致。
+*
+* 特点：
+* - 必须有 `id`（无 id 的占位节点没有意义）
+* - 不参与 viewBox 扩展（无视觉边界）；只在被引用时才间接影响 viewBox（通过引用它的 node / path）
+* - 与 Node 在同一个 nodeIndex 中注册——path target 字符串、`Node.position.of` 都能命中 coordinate id
+*/
+var CoordinateSchema = zod.z.object({
+	type: zod.z.literal("coordinate").describe("Discriminator marking this child as a coordinate placeholder"),
+	id: zod.z.string().min(1).describe("Required unique id; the whole point of a coordinate is to be referenced by paths or other nodes"),
+	position: zod.z.union([
+		require_position.PositionSchema,
+		require_polar_position.PolarPositionSchema,
+		require_at_position.AtPositionSchema
+	]).describe("Coordinate position; Cartesian [x, y], polar, or relative-to-another-node (`at`-style). Resolved at compile time.")
+}).describe("Coordinate placeholder: a named point with no visual; usable as a target for paths and as an anchor for relative positioning. Mirrors TikZ `\\coordinate (id) at (...);`");
+//#endregion
+exports.CoordinateSchema = CoordinateSchema;

package/dist/lib/ir/coordinate.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+/**
+ * Coordinate（占位节点）——TikZ `\coordinate (m) at (3,2);` 同义。
+ *
+ * 命名一个点供后续 path / at 引用，自身不绘制任何图形。
+ * 支持笛卡尔 / 极坐标 / 相对定位三种 position 形态，与 `Node.position` 完全一致。
+ *
+ * 特点：
+ * - 必须有 `id`（无 id 的占位节点没有意义）
+ * - 不参与 viewBox 扩展（无视觉边界）；只在被引用时才间接影响 viewBox（通过引用它的 node / path）
+ * - 与 Node 在同一个 nodeIndex 中注册——path target 字符串、`Node.position.of` 都能命中 coordinate id
+ */
+export declare const CoordinateSchema: z.ZodObject<{
+    type: z.ZodLiteral<"coordinate">;
+    id: z.ZodString;
+    position: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('./position').PolarPosition, z.ZodTypeDef, import('./position').PolarPosition>, z.ZodObject<{
+        direction: z.ZodNativeEnum<{
+            readonly above: "above";
+            readonly below: "below";
+            readonly left: "left";
+            readonly right: "right";
+            readonly 'above-left': "above-left";
+            readonly 'above-right': "above-right";
+            readonly 'below-left': "below-left";
+            readonly 'below-right': "below-right";
+        }>;
+        of: z.ZodString;
+        distance: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    }, {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    type: "coordinate";
+    position: [number, number] | import('./position').PolarPosition | {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    };
+    id: string;
+}, {
+    type: "coordinate";
+    position: [number, number] | import('./position').PolarPosition | {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    };
+    id: string;
+}>;
+/** Coordinate IR 类型——`{ type: 'coordinate', id, position }` */
+export type IRCoordinate = z.infer<typeof CoordinateSchema>;
+//# sourceMappingURL=coordinate.d.ts.map

package/dist/lib/ir/coordinate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate.d.ts","sourceRoot":"","sources":["../../../src/ir/coordinate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB1B,CAAC;AAEJ,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/lib/ir/index.d.ts

@@ -1,5 +1,6 @@
 export * from './position';
 export * from './path';
 export * from './node';
+export * from './coordinate';
 export * from './scene';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/ir/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ir/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ir/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}

package/dist/lib/ir/node.cjs

@@ -1,5 +1,6 @@
 const require_position = require("./position/position.cjs");
 const require_polar_position = require("./position/polar-position.cjs");
+const require_at_position = require("./position/at-position.cjs");
 let zod = require("zod");
 //#region src/ir/node.ts
 /**
@@ -70,11 +71,34 @@ var NODE_TEXT_ALIGNS = {
 	center: "center",
 	right: "right"
 };
+/**
+* 节点附属标签（label）——TikZ `[label=above:foo]` / `[label={[red]30:foo}]` 同义。
+*
+* 一个 Node 可挂多个 label（数组形态）；label 自身不参与 viewBox（视觉外延少时可接受）。
+*
+* `position` 接受两种形态：
+* - 8 方向枚举（`above` / `right` / `above-left` ...）：标签贴在 node 该方向边界外
+* - 数字角度：以 node 中心为原点，按该角度方向投射；约定与 polar 一致（0° = +x，90° = +y 屏幕下方）
+*
+* 默认 `position = 'above'`，`distance = 4`（user units，标签与 node 边界的距离）。
+*/
+var NodeLabelSchema = zod.z.object({
+	text: zod.z.string().describe("Label text content; rendered as a single line."),
+	position: zod.z.union([zod.z.nativeEnum(require_at_position.AT_DIRECTIONS), zod.z.number()]).optional().describe("Placement around the node border: 8-direction enum (above / right / above-left / ...) or numeric angle in degrees (`label=30:foo` for radial placement). Default `above`. Numeric uses the polar convention (0° = +x, 90° = +y, screen-down)."),
+	distance: zod.z.number().nonnegative().optional().describe("Gap between the node border and the label center, in user units. Default 4."),
+	textColor: zod.z.string().optional().describe("Label text color; falls back to currentColor."),
+	opacity: zod.z.number().min(0).max(1).optional().describe("Label-only opacity 0..1; multiplied with the node opacity if both are set."),
+	font: FontSchema.optional().describe("Label font overrides; missing fields inherit from the parent node font, then renderer defaults.")
+}).describe("Extra text attached around a node border. Multiple labels supported via array form on `Node.label`.");
 var NodeSchema = zod.z.object({
 	type: zod.z.literal("node").describe("Discriminator marking this child as a node"),
 	id: zod.z.string().min(1).optional().describe("Optional unique id; required if any path needs to reference this node by string"),
 	shape: zod.z.nativeEnum(NODE_SHAPES).optional().describe("Node visual shape; defaults to `rectangle`. The boundary fully contains text + padding (circumscribed for circle / ellipse / diamond)."),
-	position: zod.z.union([require_position.PositionSchema, require_polar_position.PolarPositionSchema]).describe("Center point of the node content box; Cartesian [x, y] or polar (resolved at compile time)"),
+	position: zod.z.union([
+		require_position.PositionSchema,
+		require_polar_position.PolarPositionSchema,
+		require_at_position.AtPositionSchema
+	]).describe("Center point of the node content box; Cartesian [x, y], polar, or relative-to-another-node (`at`-style with `direction` / `of` / `distance?`). All non-Cartesian forms resolve at compile time."),
 	rotate: zod.z.number().optional().describe("Rotation in degrees around the node center; positive = clockwise (matches TikZ rotate=...)"),
 	text: NodeTextSchema.optional(),
 	align: zod.z.nativeEnum(NODE_TEXT_ALIGNS).optional().describe("Multi-line text alignment within the text block; `left` / `center` / `right`. Defaults to `center` (matches TikZ)."),
@@ -101,12 +125,14 @@ var NodeSchema = zod.z.object({
 	outerSep: zod.z.number().nonnegative().optional().describe("Outer margin from border to path attachment point in user units; does NOT change the visible border. Falls back to `margin`."),
 	padding: zod.z.number().nonnegative().optional().describe("Symmetric inner padding (alias for `innerXSep` + `innerYSep`); axis-specific fields take precedence."),
 	margin: zod.z.number().nonnegative().optional().describe("Symmetric outer margin (alias for `outerSep`); axis-specific field takes precedence."),
-	font: FontSchema.optional().describe("Font spec for the inner text label (family / size / weight / style); all fields optional, all fall back to renderer defaults.")
+	font: FontSchema.optional().describe("Font spec for the inner text label (family / size / weight / style); all fields optional, all fall back to renderer defaults."),
+	label: zod.z.union([NodeLabelSchema, zod.z.array(NodeLabelSchema)]).optional().describe("Extra label(s) attached around the node border (TikZ `[label=above:foo]`); single object or array form. Compiled into one TextPrim per label, positioned by `position` direction / angle and `distance`.")
 }).describe("Node primitive: a positioned, optionally textual shape (rectangle / circle / ellipse / diamond)");
 //#endregion
 exports.FontSchema = FontSchema;
 exports.LineSpecSchema = LineSpecSchema;
 exports.NODE_SHAPES = NODE_SHAPES;
 exports.NODE_TEXT_ALIGNS = NODE_TEXT_ALIGNS;
+exports.NodeLabelSchema = NodeLabelSchema;
 exports.NodeSchema = NodeSchema;
 exports.NodeTextSchema = NodeTextSchema;