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

package/dist/lib/compile/path.cjs

@@ -1,52 +1,295 @@
-const require_rect = require("../geometry/rect.cjs");
 const require_position = require("./position.cjs");
 const require_node = require("./node.cjs");
+const require_parseTarget = require("./parseTarget.cjs");
 //#region src/compile/path.ts
 /**
-* 求一个 step.to 的"参考点"——给邻居 step 算节点边界方向用：
-* - string（节点 ref） → 节点中心
-* - Position / PolarPosition → 解析后的笛卡尔
-* 解析失败返回 null（与 resolvePosition 一致）。
+* IR 的 path-level `arrow` + `arrowShape` 映射到 PathPrim 的
+* arrowStart / arrowEnd（值就是 shape 名）。`arrowShape` 省略时默认 'normal'。
 */
-var refPointOfTarget = (target, nodeIndex) => require_position.resolvePosition(target, nodeIndex);
+var arrowMarkers = (arrow, shape = "normal") => {
+	switch (arrow) {
+		case "->": return { arrowEnd: shape };
+		case "<-": return { arrowStart: shape };
+		case "<->": return {
+			arrowStart: shape,
+			arrowEnd: shape
+		};
+		default: return {};
+	}
+};
+/**
+* 按 arrow shape 决定线段需要从端点向内"缩短"多少（单位：strokeWidth 倍）。
+*
+* 用途：避免 hollow shape（如 `open` / `openDiamond` / `openCircle`）的
+* 空心内部被 path 描边穿过——把线末端退到形状背面位置，marker 的 apex
+* 才能正好落在原始端点上。
+*
+* 这个值与 marker 几何配套，必须与 react/render/arrowMarkers.tsx 里
+* 各 shape 的 refX / 形状定义保持一致：
+*   shrink = (apexX - refX) × markerWidth / viewBoxWidth
+*   open:        apexX=9,    refX=1, scale=6/10 → 8  × 0.6 = 4.8
+*   openDiamond: apexX=9,    refX=1, scale=6/10 → 8  × 0.6 = 4.8
+*   openCircle:  apexX=10,   refX=0, scale=6/10 → 10 × 0.6 = 6
+* 实心 shape（normal / stealth / diamond / circle）apex / 边缘已贴 refX=10，
+* line 被 fill 覆盖看不见，shrink=0。
+*/
+var SHRINK_FOR_SHAPE = {
+	normal: 0,
+	open: 4.8,
+	stealth: 0,
+	diamond: 0,
+	openDiamond: 4.8,
+	circle: 0,
+	openCircle: 6
+};
+/** 把点 p 朝 target 方向移动 dist 个 path 单位 */
+var shiftToward = (p, target, dist) => {
+	const dx = target[0] - p[0];
+	const dy = target[1] - p[1];
+	const len = Math.sqrt(dx * dx + dy * dy);
+	if (len === 0 || dist === 0) return p;
+	return [p[0] + dx / len * dist, p[1] + dy / len * dist];
+};
+/**
+* 求一个 step.to 的"参考点"——给段内 boundary clip 算方向 / 折角 corner 用。
+*
+* 三态字符串语法（ADR-0004）：
+* - `'A'`（auto）：节点中心；邻居端点 clip 时按"A 中心 → toward"射线求边界
+* - `'A.<anchor>'`：命名 anchor 位置（位置即 endpoint，refPoint 也是它）
+* - `'A.<deg>'`：节点 deg 方向上的视觉边界点（位置即 endpoint）
+*
+* 后两种"显式锚点"模式下 refPoint = endpoint（位置不随邻居变），auto 模式
+* 下 refPoint 仍是中心。直接坐标 / 极坐标：解析后的笛卡尔。
+*/
+var refPointOfTarget = (target, nodeIndex) => {
+	if (typeof target === "string") {
+		const ref = require_parseTarget.parseNodeRef(target);
+		const node = nodeIndex.get(ref.id);
+		if (!node) return null;
+		switch (ref.kind) {
+			case "node": return [node.rect.x, node.rect.y];
+			case "anchor": return require_node.anchorOf(node, ref.anchor);
+			case "angle": return require_node.angleBoundaryOf(node, ref.angle);
+		}
+	}
+	return require_position.resolvePosition(target, nodeIndex);
+};
+/**
+* 折角中间点：基于"参考点"（节点中心或直接坐标）算直角拐点。
+* `-|` corner = (curr.x, prev.y)；`|-` corner = (prev.x, curr.y)。
+*/
+var cornerOf = (prev, curr, via) => via === "-|" ? [curr[0], prev[1]] : [prev[0], curr[1]];
+/**
+* 把 step.to 在给定方向 `toward` 上算出"实际绘制端点"：
+* - 节点 ref auto（`'A'`）：按 shape 多态走 boundaryPointOf——外扩 margin 后
+*   求边界与"中心→toward"射线交点
+* - 节点 ref 命名 anchor（`'A.north'`）/ 角度（`'A.30'`）：位置已被解析定死，
+*   直接返回，**不再受 toward 影响**
+* - 直接坐标 / 极坐标：解析后直接返回（不做 clip）
+* 解析失败返回 null。
+*/
+var clipForTarget = (target, toward, nodeIndex) => {
+	if (typeof target === "string") {
+		const ref = require_parseTarget.parseNodeRef(target);
+		const node = nodeIndex.get(ref.id);
+		if (!node) return null;
+		switch (ref.kind) {
+			case "node": return require_node.boundaryPointOf(node, toward);
+			case "anchor": return require_node.anchorOf(node, ref.anchor);
+			case "angle": return require_node.angleBoundaryOf(node, ref.angle);
+		}
+	}
+	return require_position.resolvePosition(target, nodeIndex);
+};
+/** 浅相等：两个 IRPosition 的两个分量都精确相等（未 round） */
+var samePoint = (a, b) => !!a && !!b && a[0] === b[0] && a[1] === b[1];
 /**
 * 把 IR Path 翻译为单个 PathPrim。
-* 算法：
-* 1. 第一遍：把每个 step.to 解析为"参考点"（节点中心 / 直接坐标 / 极坐标解算后），
-*    用于给邻居 step 算节点边界点的方向；
-* 2. 第二遍：算每个 step 的实际终点——节点引用调用 boundaryPoint 贴 attachRect；
-*    其他形态直接用解析后的笛卡尔。
-* 3. 把点序列写成 SVG path d 字符串。
-*
-* 引用未定义节点时返回 null（path 整体跳过）。
+*
+* 关键算法（v0.1.0-alpha.1）：每个绘制段（line / fold）**独立**地用节点中心
+* 算两端 boundary clip——一个节点在路径中段时，"入边"和"出边" boundary 点
+* 通常不同，路径会在该节点处可见地"断开"。这与 TikZ 原生语义一致：
+*
+*   `\draw (A) -- (B) -- (C);`
+*   段 1：A.center → B.center 决定 A 出口、B 入口的 boundary 交点
+*   段 2：B.center → C.center 决定 B 出口、C 入口的 boundary 交点
+*   B 在两段里 clip 出来的点不同——视觉上看到两条独立线段。
+*
+* 实现上仍只产一个 PathPrim：d 字符串里以多组 `M ... L ...` 表达多个 sub-path。
+* 当某段起点恰好等于上一段终点（例如直接坐标连续，或未触发 clip 差异）时，
+* 复用 cursor，省掉冗余 M。
+*
+* cycle 段：闭回最近一次 move 起点。若 cycle 起点 == lastEnd 且终点 == subPathStart，
+* 输出 `Z`（最优雅）；否则显式画一段 line（与"段独立 clip"一致）。
+*
+* 引用未定义节点 / 解析失败时返回 null（path 整体跳过）。
 */
 var emitPathPrimitive = (path, nodeIndex, round) => {
 	const steps = path.children;
 	if (steps.length < 2) return null;
-	const refPoints = steps.map((s) => refPointOfTarget(s.to, nodeIndex));
+	const anchors = steps.map((s) => s.kind === "cycle" ? null : refPointOfTarget(s.to, nodeIndex));
+	/** 找 i 之前最近的"有 to 字段的 step"（跳过 cycle） + 它的 anchor */
+	const findPrev = (i) => {
+		for (let j = i - 1; j >= 0; j--) {
+			const s = steps[j];
+			if (s.kind === "cycle") continue;
+			const a = anchors[j];
+			if (!a) return null;
+			return {
+				step: s,
+				anchor: a
+			};
+		}
+		return null;
+	};
+	/** 找 i 之前最近的 move 的 to——cycle 闭合的目标 */
+	const findRecentMoveTo = (i) => {
+		for (let j = i - 1; j >= 0; j--) if (steps[j].kind === "move") return steps[j].to;
+		return null;
+	};
+	const ops = [];
 	const points = [];
+	let lastEnd = null;
+	let subPathStart = null;
+	const emitM = (p) => {
+		ops.push({
+			cmd: "M",
+			point: p
+		});
+		points.push(p);
+		subPathStart = p;
+		lastEnd = p;
+	};
+	const emitL = (p) => {
+		ops.push({
+			cmd: "L",
+			point: p
+		});
+		points.push(p);
+		lastEnd = p;
+	};
+	const emitZ = () => {
+		ops.push({ cmd: "Z" });
+		lastEnd = subPathStart;
+	};
+	/** 段起点：与 lastEnd 相同就复用 cursor（省掉冗余 M），否则发 M */
+	const startSegment = (p) => {
+		if (samePoint(p, lastEnd)) return;
+		emitM(p);
+	};
 	for (let i = 0; i < steps.length; i++) {
-		const target = steps[i].to;
-		if (typeof target === "string") {
-			const node = nodeIndex.get(target);
-			if (!node) return null;
-			const neighbor = i > 0 ? refPoints[i - 1] : i + 1 < steps.length ? refPoints[i + 1] : null;
-			if (!neighbor) points.push([node.rect.x, node.rect.y]);
-			else points.push(require_rect.rect.boundaryPoint(require_node.attachRectOf(node), neighbor));
-		} else {
-			const resolved = require_position.resolvePosition(target, nodeIndex);
-			if (!resolved) return null;
-			points.push(resolved);
+		const step = steps[i];
+		if (step.kind === "move") continue;
+		if (step.kind === "cycle") {
+			const moveTo = findRecentMoveTo(i);
+			const prev = findPrev(i);
+			if (!moveTo || !prev) continue;
+			const moveAnchor = refPointOfTarget(moveTo, nodeIndex);
+			if (!moveAnchor) return null;
+			const fromClip = clipForTarget(prev.step.to, moveAnchor, nodeIndex);
+			const toClip = clipForTarget(moveTo, prev.anchor, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			if (samePoint(fromClip, lastEnd) && samePoint(toClip, subPathStart)) {
+				emitZ();
+				continue;
+			}
+			startSegment(fromClip);
+			emitL(toClip);
+			continue;
+		}
+		const prev = findPrev(i);
+		if (!prev) return null;
+		const currAnchor = anchors[i];
+		if (!currAnchor) return null;
+		if (step.kind === "line") {
+			const fromClip = clipForTarget(prev.step.to, currAnchor, nodeIndex);
+			const toClip = clipForTarget(step.to, prev.anchor, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitL(toClip);
+			continue;
 		}
+		const corner = cornerOf(prev.anchor, currAnchor, step.via);
+		const fromClip = clipForTarget(prev.step.to, corner, nodeIndex);
+		const toClip = clipForTarget(step.to, corner, nodeIndex);
+		if (!fromClip || !toClip) return null;
+		startSegment(fromClip);
+		emitL(corner);
+		emitL(toClip);
 	}
-	return {
+	const strokeWidth = path.strokeWidth ?? 1;
+	const baseProps = {
+		stroke: path.stroke ?? "currentColor",
+		strokeWidth,
+		fill: path.fill ?? "none",
+		fillRule: path.fillRule,
+		strokeDasharray: path.strokeDasharray
+	};
+	const markers = arrowMarkers(path.arrow, path.arrowShape);
+	const hasArrows = !!markers.arrowStart || !!markers.arrowEnd;
+	const shrinkStart = markers.arrowStart ? SHRINK_FOR_SHAPE[markers.arrowStart] : 0;
+	const shrinkEnd = markers.arrowEnd ? SHRINK_FOR_SHAPE[markers.arrowEnd] : 0;
+	if (shrinkStart > 0) {
+		const firstIdx = ops.findIndex((o) => o.cmd === "M");
+		if (firstIdx >= 0) {
+			const cur = ops[firstIdx];
+			const next = ops.slice(firstIdx + 1).find((o) => o.cmd !== "Z");
+			if (cur.cmd !== "Z" && next) cur.point = shiftToward(cur.point, next.point, shrinkStart * strokeWidth);
+		}
+	}
+	if (shrinkEnd > 0) {
+		let lastIdx = -1;
+		for (let i = ops.length - 1; i >= 0; i--) if (ops[i].cmd !== "Z") {
+			lastIdx = i;
+			break;
+		}
+		if (lastIdx > 0) {
+			let prevIdx = lastIdx - 1;
+			while (prevIdx >= 0 && ops[prevIdx].cmd === "Z") prevIdx--;
+			if (prevIdx >= 0) {
+				const cur = ops[lastIdx];
+				const prev = ops[prevIdx];
+				if (cur.cmd !== "Z" && prev.cmd !== "Z") cur.point = shiftToward(cur.point, prev.point, shrinkEnd * strokeWidth);
+			}
+		}
+	}
+	const tokens = ops.map((op) => {
+		if (op.cmd === "Z") return "Z";
+		return `${op.cmd} ${round(op.point[0])} ${round(op.point[1])}`;
+	});
+	const subPathStarts = [];
+	tokens.forEach((tok, idx) => {
+		if (tok.startsWith("M ")) subPathStarts.push(idx);
+	});
+	if (!hasArrows || subPathStarts.length <= 1) return {
 		primitive: {
 			type: "path",
-			d: points.map((p, i) => `${i === 0 ? "M" : "L"} ${round(p[0])} ${round(p[1])}`).join(" "),
-			stroke: path.stroke ?? "currentColor",
-			strokeWidth: path.strokeWidth ?? 1,
-			fill: "none",
-			strokeDasharray: path.strokeDasharray
+			d: tokens.join(" "),
+			...baseProps,
+			...markers
+		},
+		points
+	};
+	const subPathSlices = [];
+	for (let s = 0; s < subPathStarts.length; s++) {
+		const start = subPathStarts[s];
+		const end = s + 1 < subPathStarts.length ? subPathStarts[s + 1] : tokens.length;
+		subPathSlices.push(tokens.slice(start, end));
+	}
+	return {
+		primitive: {
+			type: "group",
+			children: subPathSlices.map((sub, i) => {
+				const isFirst = i === 0;
+				const isLast = i === subPathSlices.length - 1;
+				return {
+					type: "path",
+					d: sub.join(" "),
+					...baseProps,
+					...isFirst && markers.arrowStart ? { arrowStart: markers.arrowStart } : {},
+					...isLast && markers.arrowEnd ? { arrowEnd: markers.arrowEnd } : {}
+				};
+			})
 		},
 		points
 	};

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

@@ -3,14 +3,24 @@ import { ScenePrimitive } from '../primitive';
 import { NodeLayout } from './node';
 /**
  * 把 IR Path 翻译为单个 PathPrim。
- * 算法：
- * 1. 第一遍：把每个 step.to 解析为"参考点"（节点中心 / 直接坐标 / 极坐标解算后），
- *    用于给邻居 step 算节点边界点的方向；
- * 2. 第二遍：算每个 step 的实际终点——节点引用调用 boundaryPoint 贴 attachRect；
- *    其他形态直接用解析后的笛卡尔。
- * 3. 把点序列写成 SVG path d 字符串。
  *
- * 引用未定义节点时返回 null（path 整体跳过）。
+ * 关键算法（v0.1.0-alpha.1）：每个绘制段（line / fold）**独立**地用节点中心
+ * 算两端 boundary clip——一个节点在路径中段时，"入边"和"出边" boundary 点
+ * 通常不同，路径会在该节点处可见地"断开"。这与 TikZ 原生语义一致：
+ *
+ *   `\draw (A) -- (B) -- (C);`
+ *   段 1：A.center → B.center 决定 A 出口、B 入口的 boundary 交点
+ *   段 2：B.center → C.center 决定 B 出口、C 入口的 boundary 交点
+ *   B 在两段里 clip 出来的点不同——视觉上看到两条独立线段。
+ *
+ * 实现上仍只产一个 PathPrim：d 字符串里以多组 `M ... L ...` 表达多个 sub-path。
+ * 当某段起点恰好等于上一段终点（例如直接坐标连续，或未触发 clip 差异）时，
+ * 复用 cursor，省掉冗余 M。
+ *
+ * cycle 段：闭回最近一次 move 起点。若 cycle 起点 == lastEnd 且终点 == subPathStart，
+ * 输出 `Z`（最优雅）；否则显式画一段 line（与"段独立 clip"一致）。
+ *
+ * 引用未定义节点 / 解析失败时返回 null（path 整体跳过）。
  */
 export declare const emitPathPrimitive: (path: IRPath, nodeIndex: Map<string, NodeLayout>, round: (n: number) => number) => {
     primitive: ScenePrimitive;

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

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/compile/path.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAY,MAAM,OAAO,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,QAAQ,CAAC;AAcvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAClC,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CAAE,GAAG,IA6C7D,CAAC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/compile/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,MAAM,EAAE,UAAU,EAAoB,MAAM,OAAO,CAAC;AAC9E,OAAO,KAAK,EAAY,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAA8C,MAAM,QAAQ,CAAC;AAuIrF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAClC,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CAAE,GAAG,IAsN7D,CAAC"}

package/dist/lib/compile/text-metrics.d.ts

@@ -6,8 +6,8 @@ export type FontSpec = {
     size: number;
     /** 字重；可以是 'normal' / 'bold' / 100~900 数字等 */
     weight?: string | number;
-    /** 字形：normal 或 italic */
-    style?: 'normal' | 'italic';
+    /** 字形：normal / italic / oblique */
+    style?: 'normal' | 'italic' | 'oblique';
 };
 /** 文字度量结果：宽高 + 可选的基线 ascent/descent */
 export type TextMetrics = {

package/dist/lib/compile/text-metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-metrics.d.ts","sourceRoot":"","sources":["../../../src/compile/text-metrics.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,MAAM,MAAM,QAAQ,GAAG;IACrB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,yBAAyB;IACzB,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC7B,CAAC;AAEF,uCAAuC;AACvC,MAAM,MAAM,WAAW,GAAG;IACxB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,KAAK,WAAW,CAAC;AAEzE,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,EAAE,YAG7B,CAAC"}
+{"version":3,"file":"text-metrics.d.ts","sourceRoot":"","sources":["../../../src/compile/text-metrics.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,MAAM,MAAM,QAAQ,GAAG;IACrB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,mCAAmC;IACnC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF,uCAAuC;AACvC,MAAM,MAAM,WAAW,GAAG;IACxB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,KAAK,WAAW,CAAC;AAEzE,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,EAAE,YAG7B,CAAC"}

package/dist/lib/geometry/circle.cjs

@@ -0,0 +1,79 @@
+//#region src/geometry/circle.ts
+var SQRT_HALF = Math.SQRT1_2;
+var localToWorld = (c, local) => {
+	const angle = c.rotate ?? 0;
+	if (angle === 0) return [c.x + local[0], c.y + local[1]];
+	const cos = Math.cos(angle);
+	const sin = Math.sin(angle);
+	return [c.x + local[0] * cos - local[1] * sin, c.y + local[0] * sin + local[1] * cos];
+};
+var worldToLocal = (c, world) => {
+	const tx = world[0] - c.x;
+	const ty = world[1] - c.y;
+	const angle = c.rotate ?? 0;
+	if (angle === 0) return [tx, ty];
+	const cos = Math.cos(angle);
+	const sin = Math.sin(angle);
+	return [tx * cos + ty * sin, -tx * sin + ty * cos];
+};
+/** 圆形相关基础工具 */
+var circle = {
+	/** 圆心 */
+	center: (c) => [c.x, c.y],
+	/** 判断点是否在圆内（含边界） */
+	contains: (c, p) => {
+		const [lx, ly] = worldToLocal(c, p);
+		return lx * lx + ly * ly <= c.radius * c.radius;
+	},
+	/** 9 个标准 anchor 之一的世界坐标 */
+	anchor: (c, name) => {
+		const r = c.radius;
+		let lx = 0;
+		let ly = 0;
+		switch (name) {
+			case "center": break;
+			case "north":
+				ly = -r;
+				break;
+			case "south":
+				ly = r;
+				break;
+			case "east":
+				lx = r;
+				break;
+			case "west":
+				lx = -r;
+				break;
+			case "north-east":
+				lx = r * SQRT_HALF;
+				ly = -r * SQRT_HALF;
+				break;
+			case "north-west":
+				lx = -r * SQRT_HALF;
+				ly = -r * SQRT_HALF;
+				break;
+			case "south-east":
+				lx = r * SQRT_HALF;
+				ly = r * SQRT_HALF;
+				break;
+			case "south-west":
+				lx = -r * SQRT_HALF;
+				ly = r * SQRT_HALF;
+				break;
+		}
+		return localToWorld(c, [lx, ly]);
+	},
+	/**
+	* 从圆心向 toward 方向画射线，求与圆周的交点。
+	* 用于把 Path 端点贴到 Node 边界。
+	*/
+	boundaryPoint: (c, toward) => {
+		const [lx, ly] = worldToLocal(c, toward);
+		const len = Math.sqrt(lx * lx + ly * ly);
+		if (len === 0) return [c.x, c.y];
+		const t = c.radius / len;
+		return localToWorld(c, [lx * t, ly * t]);
+	}
+};
+//#endregion
+exports.circle = circle;

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

@@ -0,0 +1,32 @@
+import { Position } from './point';
+/** 圆形：几何中心 (x, y) + 半径；与 Rect 一样支持可选旋转（圆对自身旋转无影响，预留供 anchor 命名一致性） */
+export type Circle = {
+    /** 圆心横坐标 */
+    x: number;
+    /** 圆心纵坐标 */
+    y: number;
+    /** 半径（user units） */
+    radius: number;
+    /** 绕几何中心旋转弧度；保留与 Rect 同形 API，圆形本身旋转后视觉不变 */
+    rotate?: number;
+};
+/**
+ * 圆形 9 个标准 anchor 名集合，与 RECT_ANCHORS 同名同义。
+ * 圆的"4 方位 + 4 对角"在圆周上等距分布（每 45°）。
+ */
+export type CircleAnchor = 'center' | 'north' | 'south' | 'east' | 'west' | 'north-east' | 'north-west' | 'south-east' | 'south-west';
+/** 圆形相关基础工具 */
+export declare const circle: {
+    /** 圆心 */
+    center: (c: Circle) => Position;
+    /** 判断点是否在圆内（含边界） */
+    contains: (c: Circle, p: Position) => boolean;
+    /** 9 个标准 anchor 之一的世界坐标 */
+    anchor: (c: Circle, name: CircleAnchor) => Position;
+    /**
+     * 从圆心向 toward 方向画射线，求与圆周的交点。
+     * 用于把 Path 端点贴到 Node 边界。
+     */
+    boundaryPoint: (c: Circle, toward: Position) => Position;
+};
+//# sourceMappingURL=circle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"circle.d.ts","sourceRoot":"","sources":["../../../src/geometry/circle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,sEAAsE;AACtE,MAAM,MAAM,MAAM,GAAG;IACnB,YAAY;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,YAAY;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAIF;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,YAAY,CAAC;AAoBjB,eAAe;AACf,eAAO,MAAM,MAAM;IACjB,SAAS;gBACG,MAAM,KAAG,QAAQ;IAC7B,oBAAoB;kBACN,MAAM,KAAK,QAAQ,KAAG,OAAO;IAI3C,2BAA2B;gBACf,MAAM,QAAQ,YAAY,KAAG,QAAQ;IAsCjD;;;OAGG;uBACgB,MAAM,UAAU,QAAQ,KAAG,QAAQ;CAOvD,CAAC"}

package/dist/lib/geometry/diamond.cjs

@@ -0,0 +1,87 @@
+//#region src/geometry/diamond.ts
+var localToWorld = (d, local) => {
+	const angle = d.rotate ?? 0;
+	if (angle === 0) return [d.x + local[0], d.y + local[1]];
+	const cos = Math.cos(angle);
+	const sin = Math.sin(angle);
+	return [d.x + local[0] * cos - local[1] * sin, d.y + local[0] * sin + local[1] * cos];
+};
+var worldToLocal = (d, world) => {
+	const tx = world[0] - d.x;
+	const ty = world[1] - d.y;
+	const angle = d.rotate ?? 0;
+	if (angle === 0) return [tx, ty];
+	const cos = Math.cos(angle);
+	const sin = Math.sin(angle);
+	return [tx * cos + ty * sin, -tx * sin + ty * cos];
+};
+/** 菱形相关基础工具 */
+var diamond = {
+	/** 中心 */
+	center: (d) => [d.x, d.y],
+	/**
+	* 判断点是否在菱形内（含边界，考虑旋转）。
+	* 菱形方程：|x|/halfA + |y|/halfB ≤ 1。
+	*/
+	contains: (d, p) => {
+		const [lx, ly] = worldToLocal(d, p);
+		return Math.abs(lx) / d.halfA + Math.abs(ly) / d.halfB <= 1.000000001;
+	},
+	/**
+	* 9 个标准 anchor 的世界坐标。
+	* - N/S/E/W：四个顶点
+	* - NE/NW/SE/SW：四条边的中点
+	* - center：几何中心
+	*/
+	anchor: (d, name) => {
+		let lx = 0;
+		let ly = 0;
+		switch (name) {
+			case "center": break;
+			case "north":
+				ly = -d.halfB;
+				break;
+			case "south":
+				ly = d.halfB;
+				break;
+			case "east":
+				lx = d.halfA;
+				break;
+			case "west":
+				lx = -d.halfA;
+				break;
+			case "north-east":
+				lx = d.halfA / 2;
+				ly = -d.halfB / 2;
+				break;
+			case "north-west":
+				lx = -d.halfA / 2;
+				ly = -d.halfB / 2;
+				break;
+			case "south-east":
+				lx = d.halfA / 2;
+				ly = d.halfB / 2;
+				break;
+			case "south-west":
+				lx = -d.halfA / 2;
+				ly = d.halfB / 2;
+				break;
+		}
+		return localToWorld(d, [lx, ly]);
+	},
+	/**
+	* 从中心向 toward 方向画射线，求与菱形 4 条边之一的交点。
+	* 菱形方程：|x|/halfA + |y|/halfB = 1。
+	* 沿方向 (lx, ly) 缩放 t 倍命中：t × (|lx|/halfA + |ly|/halfB) = 1
+	* → t = 1 / (|lx|/halfA + |ly|/halfB)。
+	*/
+	boundaryPoint: (d, toward) => {
+		const [lx, ly] = worldToLocal(d, toward);
+		const denom = Math.abs(lx) / d.halfA + Math.abs(ly) / d.halfB;
+		if (denom === 0) return [d.x, d.y];
+		const t = 1 / denom;
+		return localToWorld(d, [lx * t, ly * t]);
+	}
+};
+//#endregion
+exports.diamond = diamond;

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

@@ -0,0 +1,44 @@
+import { Position } from './point';
+/**
+ * 菱形：几何中心 (x, y) + 半轴长 halfA（水平）/ halfB（垂直）+ 可选旋转。
+ * 4 个顶点位于 (±halfA, 0) 与 (0, ±halfB)，4 条边界线把这些顶点两两相连。
+ */
+export type Diamond = {
+    /** 中心横坐标 */
+    x: number;
+    /** 中心纵坐标 */
+    y: number;
+    /** 水平半轴长（中心到 east/west 顶点的距离） */
+    halfA: number;
+    /** 垂直半轴长（中心到 north/south 顶点的距离） */
+    halfB: number;
+    /** 绕几何中心旋转弧度；省略或 0 表示不旋转 */
+    rotate?: number;
+};
+/** 菱形 9 个标准 anchor 名（4 顶点 + 4 边中点 + 中心） */
+export type DiamondAnchor = 'center' | 'north' | 'south' | 'east' | 'west' | 'north-east' | 'north-west' | 'south-east' | 'south-west';
+/** 菱形相关基础工具 */
+export declare const diamond: {
+    /** 中心 */
+    center: (d: Diamond) => Position;
+    /**
+     * 判断点是否在菱形内（含边界，考虑旋转）。
+     * 菱形方程：|x|/halfA + |y|/halfB ≤ 1。
+     */
+    contains: (d: Diamond, p: Position) => boolean;
+    /**
+     * 9 个标准 anchor 的世界坐标。
+     * - N/S/E/W：四个顶点
+     * - NE/NW/SE/SW：四条边的中点
+     * - center：几何中心
+     */
+    anchor: (d: Diamond, name: DiamondAnchor) => Position;
+    /**
+     * 从中心向 toward 方向画射线，求与菱形 4 条边之一的交点。
+     * 菱形方程：|x|/halfA + |y|/halfB = 1。
+     * 沿方向 (lx, ly) 缩放 t 倍命中：t × (|lx|/halfA + |ly|/halfB) = 1
+     * → t = 1 / (|lx|/halfA + |ly|/halfB)。
+     */
+    boundaryPoint: (d: Diamond, toward: Position) => Position;
+};
+//# sourceMappingURL=diamond.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diamond.d.ts","sourceRoot":"","sources":["../../../src/geometry/diamond.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,YAAY;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,YAAY;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,YAAY,CAAC;AAoBjB,eAAe;AACf,eAAO,MAAM,OAAO;IAClB,SAAS;gBACG,OAAO,KAAG,QAAQ;IAC9B;;;OAGG;kBACW,OAAO,KAAK,QAAQ,KAAG,OAAO;IAI5C;;;;;OAKG;gBACS,OAAO,QAAQ,aAAa,KAAG,QAAQ;IAqCnD;;;;;OAKG;uBACgB,OAAO,UAAU,QAAQ,KAAG,QAAQ;CAOxD,CAAC"}