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

package/dist/es/compile/path.js

@@ -1,6 +1,10 @@
 import { resolvePosition } from "./position.js";
 import { anchorOf, angleBoundaryOf, boundaryPointOf } from "./node.js";
+import { arcBoundingPoints, arcEndPoint, arcSvgFlags } from "../geometry/arc.js";
+import { bendControlPoints } from "../geometry/bend.js";
+import { arcSegmentSample, circleSegmentSample, cubicSegmentSample, ellipseSegmentSample, foldSegmentSample, lineSegmentSample, quadSegmentSample } from "../geometry/segment.js";
 import { parseNodeRef } from "./parseTarget.js";
+import { fallbackMeasurer } from "./text-metrics.js";
 //#region src/compile/path.ts
 /**
 * IR 的 path-level `arrow` + `arrowShape` 映射到 PathPrim 的
@@ -72,6 +76,7 @@ var refPointOfTarget = (target, nodeIndex) => {
 			case "angle": return angleBoundaryOf(node, ref.angle);
 		}
 	}
+	if (typeof target === "object" && !Array.isArray(target) && ("rel" in target || "relAccumulate" in target)) return null;
 	return resolvePosition(target, nodeIndex);
 };
 /**
@@ -99,11 +104,179 @@ var clipForTarget = (target, toward, nodeIndex) => {
 			case "angle": return angleBoundaryOf(node, ref.angle);
 		}
 	}
+	if (typeof target === "object" && !Array.isArray(target) && ("rel" in target || "relAccumulate" in target)) return null;
 	return resolvePosition(target, nodeIndex);
 };
 /** 浅相等：两个 IRPosition 的两个分量都精确相等（未 round） */
 var samePoint = (a, b) => !!a && !!b && a[0] === b[0] && a[1] === b[1];
 /**
+* 语义 stroke 档位 → 数值映射（user units）。
+*
+* 对齐 TikZ 比例（thin = 默认 0.4pt，retikz 默认 strokeWidth = 1，所以 thin → 1）：
+*   ultra thin  0.1pt → 0.25
+*   very thin   0.2pt → 0.5
+*   thin        0.4pt → 1     （= 默认 strokeWidth）
+*   semithick   0.6pt → 1.5
+*   thick       0.8pt → 2
+*   very thick  1.2pt → 3
+*   ultra thick 1.6pt → 4
+*
+* 显式 `strokeWidth` 始终覆盖 `thickness`——thickness 仅在 strokeWidth 缺省时生效。
+*/
+var THICKNESS_TO_WIDTH = {
+	ultraThin: .25,
+	veryThin: .5,
+	thin: 1,
+	semithick: 1.5,
+	thick: 2,
+	veryThick: 3,
+	ultraThick: 4
+};
+/** ADR-0004：边标注的默认字号 / 偏移量（user units） */
+var LABEL_FONT_SIZE = 14;
+var LABEL_LINE_HEIGHT_FACTOR = 1.2;
+var LABEL_SIDE_OFFSET = 4;
+var RAD_TO_DEG = 180 / Math.PI;
+/** label.position → 段参数 t */
+var tForLabelPosition = (pos) => pos === "near-start" ? .25 : pos === "near-end" ? .75 : .5;
+/**
+* 把 step.label + 段采样结果翻成 TextPrim（sloped 时再裹一层 group 旋转）。
+*
+* 几何（默认 side='above'，position='midway'）：
+* - 'above': 锚点 (x, y - LABEL_SIDE_OFFSET)，align=middle, baseline=bottom
+* - 'below': 锚点 (x, y + LABEL_SIDE_OFFSET)，align=middle, baseline=top
+* - 'left' : 锚点 (x - LABEL_SIDE_OFFSET, y)，align=end,    baseline=middle
+* - 'right': 锚点 (x + LABEL_SIDE_OFFSET, y)，align=start,  baseline=middle
+* - 'sloped': 锚点 (x, y) 不偏移，align=middle baseline=bottom，外裹 group
+*   `transform="rotate(angle x y)"`，angle 由切线 atan2 算出（SVG y-down，CW 正向）
+*
+* 文本宽高交给 measureText；fallbackMeasurer 时只是估算，但不影响渲染坐标。
+* 返回 primitive + 用于 viewBox 的若干外接点（sloped 时按"近似最大半径"四角扩张）。
+*/
+var emitLabelPrimitive = (label, sample, measureText, round) => {
+	const fontSize = LABEL_FONT_SIZE;
+	const lineHeight = fontSize * LABEL_LINE_HEIGHT_FACTOR;
+	const m = measureText(label.text, { size: fontSize });
+	const measuredWidth = m.width;
+	const measuredHeight = m.height || lineHeight;
+	const side = label.side ?? "above";
+	let x = sample.point[0];
+	let y = sample.point[1];
+	let align = "middle";
+	let baseline = "middle";
+	if (side === "above") {
+		y -= LABEL_SIDE_OFFSET;
+		baseline = "bottom";
+	} else if (side === "below") {
+		y += LABEL_SIDE_OFFSET;
+		baseline = "top";
+	} else if (side === "left") {
+		x -= LABEL_SIDE_OFFSET;
+		align = "end";
+	} else if (side === "right") {
+		x += LABEL_SIDE_OFFSET;
+		align = "start";
+	} else baseline = "bottom";
+	const text = {
+		type: "text",
+		x: round(x),
+		y: round(y),
+		lines: [{ text: label.text }],
+		fontSize,
+		align,
+		baseline,
+		lineHeight: round(lineHeight),
+		measuredWidth: round(measuredWidth),
+		measuredHeight: round(measuredHeight),
+		fill: "currentColor"
+	};
+	if (side === "sloped") {
+		const groupPrim = {
+			type: "group",
+			transform: `rotate(${round(Math.atan2(sample.tangent[1], sample.tangent[0]) * RAD_TO_DEG)} ${round(x)} ${round(y)})`,
+			children: [text]
+		};
+		const r = Math.max(measuredWidth / 2, measuredHeight / 2);
+		return {
+			primitive: groupPrim,
+			points: [
+				[x - r, y - r],
+				[x + r, y - r],
+				[x - r, y + r],
+				[x + r, y + r]
+			]
+		};
+	}
+	const halfW = measuredWidth / 2;
+	const halfH = measuredHeight / 2;
+	return {
+		primitive: text,
+		points: [
+			[x - halfW, y - halfH],
+			[x + halfW, y - halfH],
+			[x - halfW, y + halfH],
+			[x + halfW, y + halfH]
+		]
+	};
+};
+/**
+* 把 rel / relAccumulate 目标解析为绝对 Position，产出 step kind 不变但
+* `to` 字段全为绝对坐标的步序列。
+*
+* 决策（ADR-0003 §影响 与 §背景 文本有矛盾）：
+*   两者都相对 prevEnd 解析，区别仅在是否更新 prevEnd——
+*   rel 不更新（保持 TikZ `+` 语义），relAccumulate 更新（TikZ `++` 累积）。
+*   选这个语义因为：(1) 与 TikZ `+`/`++` 一致；(2) 与字段名"Accumulate"
+*   语义匹配；(3) 与 ADR 背景段一致；§影响 段写"pathStart + offset"是 typo。
+*
+* 跨 step kind 的 prevEnd 推进：
+* - 有 to 的 kind（move/line/step/curve/cubic/bend）：prevEnd = refPointOfTarget(to)
+* - arc：prevEnd = arcEndPoint(prevEnd, radius, endAngle)
+* - circlePath / ellipsePath：prevEnd 不变（画完留圆心，即 prevEnd 本身）
+* - cycle：prevEnd 不变（不重置到 pathStart，保持简单；后续如有需要再扩）
+*
+* prevEnd 为 null（首步是 rel）时回退到 [0, 0] 当锚点；解析失败保持原 step。
+*/
+var normalizeRelativeTargets = (steps, nodeIndex) => {
+	let prevEnd = null;
+	const out = [];
+	for (const step of steps) {
+		if (step.kind === "cycle") {
+			out.push(step);
+			continue;
+		}
+		if (step.kind === "circlePath" || step.kind === "ellipsePath") {
+			out.push(step);
+			continue;
+		}
+		if (step.kind === "arc") {
+			out.push(step);
+			if (prevEnd) prevEnd = arcEndPoint(prevEnd, step.radius, step.endAngle);
+			continue;
+		}
+		const original = step.to;
+		let resolvedTo = original;
+		let updatePrevEnd = true;
+		if (typeof original === "object" && !Array.isArray(original) && "rel" in original) {
+			const ref = prevEnd ?? [0, 0];
+			resolvedTo = [ref[0] + original.rel[0], ref[1] + original.rel[1]];
+			updatePrevEnd = false;
+		} else if (typeof original === "object" && !Array.isArray(original) && "relAccumulate" in original) {
+			const ref = prevEnd ?? [0, 0];
+			resolvedTo = [ref[0] + original.relAccumulate[0], ref[1] + original.relAccumulate[1]];
+		}
+		out.push({
+			...step,
+			to: resolvedTo
+		});
+		if (updatePrevEnd) {
+			const pos = refPointOfTarget(resolvedTo, nodeIndex);
+			if (pos) prevEnd = pos;
+		}
+	}
+	return out;
+};
+/**
 * 把 IR Path 翻译为单个 PathPrim。
 *
 * 关键算法（v0.1.0-alpha.1）：每个绘制段（line / fold）**独立**地用节点中心
@@ -124,15 +297,27 @@ var samePoint = (a, b) => !!a && !!b && a[0] === b[0] && a[1] === b[1];
 *
 * 引用未定义节点 / 解析失败时返回 null（path 整体跳过）。
 */
-var emitPathPrimitive = (path, nodeIndex, round) => {
-	const steps = path.children;
+var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer) => {
+	const steps = normalizeRelativeTargets(path.children, nodeIndex);
 	if (steps.length < 2) return null;
-	const anchors = steps.map((s) => s.kind === "cycle" ? null : refPointOfTarget(s.to, nodeIndex));
-	/** 找 i 之前最近的"有 to 字段的 step"（跳过 cycle） + 它的 anchor */
+	/** ADR-0004：每段 step.label 翻译出的 TextPrim（或裹 sloped 旋转的 group），
+	*  与 path 主体 primitive 同级返回；调用方 push 进 scene.primitives */
+	const labelPrims = [];
+	/** 为当前 step 收 label：算 sample 后调用 emitLabelPrimitive，结果累积到 labelPrims / points */
+	const collectLabel = (step, sampleAt) => {
+		if (step.kind === "move" || step.kind === "cycle" || !("label" in step) || !step.label) return;
+		const sample = sampleAt(tForLabelPosition(step.label.position));
+		const r = emitLabelPrimitive(step.label, sample, measureText, round);
+		labelPrims.push(r.primitive);
+		for (const p of r.points) points.push(p);
+	};
+	const hasTo = (s) => s.kind !== "cycle" && s.kind !== "arc" && s.kind !== "circlePath" && s.kind !== "ellipsePath";
+	const anchors = steps.map((s) => hasTo(s) ? refPointOfTarget(s.to, nodeIndex) : null);
+	/** 找 i 之前最近的"有 to 字段的 step" + 它的 anchor */
 	const findPrev = (i) => {
 		for (let j = i - 1; j >= 0; j--) {
 			const s = steps[j];
-			if (s.kind === "cycle") continue;
+			if (!hasTo(s)) continue;
 			const a = anchors[j];
 			if (!a) return null;
 			return {
@@ -144,13 +329,27 @@ var emitPathPrimitive = (path, nodeIndex, round) => {
 	};
 	/** 找 i 之前最近的 move 的 to——cycle 闭合的目标 */
 	const findRecentMoveTo = (i) => {
-		for (let j = i - 1; j >= 0; j--) if (steps[j].kind === "move") return steps[j].to;
+		for (let j = i - 1; j >= 0; j--) {
+			const s = steps[j];
+			if (s.kind === "move") return s.to;
+		}
 		return null;
 	};
 	const ops = [];
 	const points = [];
 	let lastEnd = null;
 	let subPathStart = null;
+	/**
+	* "笔位覆盖"——arc / circlePath / ellipsePath 这种没有 `to` 字段的 step
+	* 不能通过 `prev.step.to` 重算下一段的起点。它们设置 penOverride，下一个
+	* 绘制段（line/curve/cubic/bend/step）直接用这个点当 fromClip，之后清空。
+	*
+	*   - arc：endpoint（弧终点）—— 与 SVG 实际 cursor 一致
+	*   - circlePath/ellipsePath：center（圆心）—— ADR-0002 决策"画完留在圆心"，
+	*     注意 SVG 实际 cursor 在弧端点而不在 center，必须靠 startSegment 发 M
+	*     teleport 回中心
+	*/
+	let penOverride = null;
 	const emitM = (p) => {
 		ops.push({
 			cmd: "M",
@@ -172,6 +371,40 @@ var emitPathPrimitive = (path, nodeIndex, round) => {
 		ops.push({ cmd: "Z" });
 		lastEnd = subPathStart;
 	};
+	const emitQ = (control, p) => {
+		ops.push({
+			cmd: "Q",
+			control,
+			point: p
+		});
+		points.push(control);
+		points.push(p);
+		lastEnd = p;
+	};
+	const emitC = (c1, c2, p) => {
+		ops.push({
+			cmd: "C",
+			control1: c1,
+			control2: c2,
+			point: p
+		});
+		points.push(c1);
+		points.push(c2);
+		points.push(p);
+		lastEnd = p;
+	};
+	const emitA = (rx, ry, largeArc, sweep, p) => {
+		ops.push({
+			cmd: "A",
+			rx,
+			ry,
+			largeArc,
+			sweep,
+			point: p
+		});
+		points.push(p);
+		lastEnd = p;
+	};
 	/** 段起点：与 lastEnd 相同就复用 cursor（省掉冗余 M），否则发 M */
 	const startSegment = (p) => {
 		if (samePoint(p, lastEnd)) return;
@@ -199,31 +432,114 @@ var emitPathPrimitive = (path, nodeIndex, round) => {
 		}
 		const prev = findPrev(i);
 		if (!prev) return null;
+		if (step.kind === "arc") {
+			const center = prev.anchor;
+			const startPt = arcEndPoint(center, step.radius, step.startAngle);
+			const endPt = arcEndPoint(center, step.radius, step.endAngle);
+			const flags = arcSvgFlags(step.startAngle, step.endAngle);
+			startSegment(startPt);
+			emitA(step.radius, step.radius, flags.largeArc, flags.sweep, endPt);
+			for (const p of arcBoundingPoints(center, step.radius, step.startAngle, step.endAngle)) points.push(p);
+			collectLabel(step, (t) => arcSegmentSample(center, step.radius, step.startAngle, step.endAngle, t));
+			penOverride = endPt;
+			continue;
+		}
+		if (step.kind === "circlePath") {
+			const center = prev.anchor;
+			const r = step.radius;
+			const right = [center[0] + r, center[1]];
+			const left = [center[0] - r, center[1]];
+			startSegment(right);
+			emitA(r, r, 0, 1, left);
+			emitA(r, r, 0, 1, right);
+			points.push([center[0] + r, center[1]]);
+			points.push([center[0] - r, center[1]]);
+			points.push([center[0], center[1] + r]);
+			points.push([center[0], center[1] - r]);
+			collectLabel(step, (t) => circleSegmentSample(center, r, t));
+			penOverride = center;
+			continue;
+		}
+		if (step.kind === "ellipsePath") {
+			const center = prev.anchor;
+			const rx = step.radiusX;
+			const ry = step.radiusY;
+			const right = [center[0] + rx, center[1]];
+			const left = [center[0] - rx, center[1]];
+			startSegment(right);
+			emitA(rx, ry, 0, 1, left);
+			emitA(rx, ry, 0, 1, right);
+			points.push([center[0] + rx, center[1]]);
+			points.push([center[0] - rx, center[1]]);
+			points.push([center[0], center[1] + ry]);
+			points.push([center[0], center[1] - ry]);
+			collectLabel(step, (t) => ellipseSegmentSample(center, rx, ry, t));
+			penOverride = center;
+			continue;
+		}
 		const currAnchor = anchors[i];
 		if (!currAnchor) return null;
+		const usedOverride = penOverride;
+		penOverride = null;
 		if (step.kind === "line") {
-			const fromClip = clipForTarget(prev.step.to, currAnchor, nodeIndex);
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, currAnchor, nodeIndex);
 			const toClip = clipForTarget(step.to, prev.anchor, nodeIndex);
 			if (!fromClip || !toClip) return null;
 			startSegment(fromClip);
 			emitL(toClip);
+			collectLabel(step, (t) => lineSegmentSample(fromClip, toClip, t));
+			continue;
+		}
+		if (step.kind === "curve") {
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control, nodeIndex);
+			const toClip = clipForTarget(step.to, step.control, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitQ(step.control, toClip);
+			collectLabel(step, (t) => quadSegmentSample(fromClip, step.control, toClip, t));
+			continue;
+		}
+		if (step.kind === "cubic") {
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control1, nodeIndex);
+			const toClip = clipForTarget(step.to, step.control2, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitC(step.control1, step.control2, toClip);
+			collectLabel(step, (t) => cubicSegmentSample(fromClip, step.control1, step.control2, toClip, t));
+			continue;
+		}
+		if (step.kind === "bend") {
+			const angle = step.bendAngle ?? 30;
+			const [c1, c2] = bendControlPoints(prev.anchor, currAnchor, step.bendDirection, angle);
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, c1, nodeIndex);
+			const toClip = clipForTarget(step.to, c2, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitC(c1, c2, toClip);
+			collectLabel(step, (t) => cubicSegmentSample(fromClip, c1, c2, toClip, t));
 			continue;
 		}
 		const corner = cornerOf(prev.anchor, currAnchor, step.via);
-		const fromClip = clipForTarget(prev.step.to, corner, nodeIndex);
+		const fromClip = usedOverride ?? clipForTarget(prev.step.to, corner, nodeIndex);
 		const toClip = clipForTarget(step.to, corner, nodeIndex);
 		if (!fromClip || !toClip) return null;
 		startSegment(fromClip);
 		emitL(corner);
 		emitL(toClip);
+		collectLabel(step, (t) => foldSegmentSample(fromClip, corner, toClip, t));
 	}
-	const strokeWidth = path.strokeWidth ?? 1;
+	const strokeWidth = path.strokeWidth ?? (path.thickness ? THICKNESS_TO_WIDTH[path.thickness] : 1);
 	const baseProps = {
 		stroke: path.stroke ?? "currentColor",
 		strokeWidth,
 		fill: path.fill ?? "none",
 		fillRule: path.fillRule,
-		strokeDasharray: path.strokeDasharray
+		strokeDasharray: path.strokeDasharray,
+		strokeLinecap: path.lineCap,
+		strokeLinejoin: path.lineJoin,
+		opacity: path.opacity,
+		fillOpacity: path.fillOpacity,
+		strokeOpacity: path.drawOpacity
 	};
 	const markers = arrowMarkers(path.arrow, path.arrowShape);
 	const hasArrows = !!markers.arrowStart || !!markers.arrowEnd;
@@ -255,6 +571,9 @@ var emitPathPrimitive = (path, nodeIndex, round) => {
 	}
 	const tokens = ops.map((op) => {
 		if (op.cmd === "Z") return "Z";
+		if (op.cmd === "Q") return `Q ${round(op.control[0])} ${round(op.control[1])} ${round(op.point[0])} ${round(op.point[1])}`;
+		if (op.cmd === "C") return `C ${round(op.control1[0])} ${round(op.control1[1])} ${round(op.control2[0])} ${round(op.control2[1])} ${round(op.point[0])} ${round(op.point[1])}`;
+		if (op.cmd === "A") return `A ${round(op.rx)} ${round(op.ry)} 0 ${op.largeArc} ${op.sweep} ${round(op.point[0])} ${round(op.point[1])}`;
 		return `${op.cmd} ${round(op.point[0])} ${round(op.point[1])}`;
 	});
 	const subPathStarts = [];
@@ -262,12 +581,12 @@ var emitPathPrimitive = (path, nodeIndex, round) => {
 		if (tok.startsWith("M ")) subPathStarts.push(idx);
 	});
 	if (!hasArrows || subPathStarts.length <= 1) return {
-		primitive: {
+		primitives: [{
 			type: "path",
 			d: tokens.join(" "),
 			...baseProps,
 			...markers
-		},
+		}, ...labelPrims],
 		points
 	};
 	const subPathSlices = [];
@@ -277,7 +596,7 @@ var emitPathPrimitive = (path, nodeIndex, round) => {
 		subPathSlices.push(tokens.slice(start, end));
 	}
 	return {
-		primitive: {
+		primitives: [{
 			type: "group",
 			children: subPathSlices.map((sub, i) => {
 				const isFirst = i === 0;
@@ -290,7 +609,7 @@ var emitPathPrimitive = (path, nodeIndex, round) => {
 					...isLast && markers.arrowEnd ? { arrowEnd: markers.arrowEnd } : {}
 				};
 			})
-		},
+		}, ...labelPrims],
 		points
 	};
 };

package/dist/es/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/es/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/es/compile/position.js

@@ -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/es/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/es/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/es/geometry/arc.js

@@ -0,0 +1,53 @@
+//#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
+export { arcBoundingPoints, arcEndPoint, arcSvgFlags };

package/dist/es/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/es/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"}