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

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

@@ -1,5 +1,6 @@
 export * from './compile';
 export * from './node';
+export * from './parseTarget';
 export * from './path';
 export * from './position';
 export * from './precision';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/compile/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/compile/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

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

@@ -1,15 +1,26 @@
-import { Rect } from '../geometry/rect';
-import { IRNode } from '../ir';
+import { Position } from '../geometry/point';
+import { Rect, RectAnchor } from '../geometry/rect';
+import { IRNode, NodeShape } from '../ir';
 import { ScenePrimitive } from '../primitive';
 import { TextMeasurer } from './text-metrics';
 export type NodeLayout = {
     /** 节点 id（如 IR Node 提供）；其他位置可通过 id 引用本节点 */
     id?: string;
-    /** 节点几何盒（x, y 是几何中心，rotate 是弧度，见 packages/core/AGENTS.md） */
+    /** 节点形状——所有几何 / 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 对齐）。
+     */
     rect: Rect;
     /** IR 中原始的旋转角（度数），保留供 emit 阶段写 SVG transform */
     rotateDeg: number;
-    /** 外边距（user units，≥ 0）；path 附着到 rect 外扩 margin 的虚拟 attachRect 上 */
+    /** 外边距（user units，≥ 0）；path 附着到形状外扩 margin 的虚拟边界上 */
     margin: number;
     /** 节点文本内容；空字符串视为无文本（undefined） */
     text?: string;
@@ -19,22 +30,35 @@ export type NodeLayout = {
     textHeight: number;
     /** 文本字号（user units） */
     fontSize: number;
-    /** 节点矩形背景色，CSS 颜色字符串；emit 时用 'transparent' 兜底 */
+    /** 节点背景色，CSS 颜色字符串；emit 时用 'transparent' 兜底 */
     fill?: string;
-    /** 节点矩形边框色，CSS 颜色字符串；emit 时用 'currentColor' 兜底 */
+    /** 节点边框色，CSS 颜色字符串；emit 时用 'currentColor' 兜底 */
     stroke?: string;
-    /** 节点矩形边框宽度（user units）；emit 时用 1 兜底 */
+    /** 节点边框宽度（user units）；emit 时用 1 兜底 */
     strokeWidth?: number;
 };
 /**
- * 取节点的"附着 rect"——用于 path 端点贴边的几何盒。
- * 在视觉 rect 基础上每边外扩 margin，保持中心与旋转不变。
- * margin = 0 时直接返回视觉 rect 自身（避免无意义复制）。
+ * 取节点 shape 在 toward 方向上的"附着点"——path 端点贴边用。
+ * 按 shape 多态：rect / circle / ellipse / diamond 各自的 boundaryPoint。
+ * margin > 0 时形状先外扩，让 path 在 border 外停 margin 个 user units。
  */
-export declare const attachRectOf: (layout: NodeLayout) => Rect;
+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'` 这种语法落点。
+ */
+export declare const anchorOf: (layout: NodeLayout, name: RectAnchor) => Position;
+/**
+ * 取节点 shape 在指定角度方向上的边界点。角度约定与 PolarPosition 一致（度数）：
+ *   0° = +x（east），90° = +y（screen 下方）。
+ * **不应用 margin**——同 anchorOf。用于 `'A.30'` 这种语法落点。
+ */
+export declare const angleBoundaryOf: (layout: NodeLayout, angleDeg: number) => Position;
 /**
  * 把 IR Node 解析为内部 NodeLayout：
- * - 算出文本度量与 padding 推导出的视觉 rect 尺寸
+ * - 算出文本度量与 padding 推导出"内框"半轴 (innerHalfW/H)
+ * - 按 shape 决定外接边界尺寸（circle 取半对角线、ellipse 各 ×√2、diamond 各 ×2）
  * - 解析 position（笛卡尔或极坐标）为几何中心
  * - IR 的 rotate（度数）转弧度存进 Rect.rotate
  * - 透传 margin / 样式属性
@@ -42,10 +66,11 @@ export declare const attachRectOf: (layout: NodeLayout) => Rect;
 export declare const layoutNode: (node: IRNode, measureText: TextMeasurer, nodeIndex: Map<string, NodeLayout>) => NodeLayout;
 /**
  * 把 NodeLayout 翻译为 Scene primitives：
- * - rect（背景边框；x/y 转为 SVG 风格的左上角）
- * - text（如有内容）
- * - 若有旋转，外面套一层 GroupPrim 用 SVG `rotate(deg cx cy)` 实现，
- *   内层 RectPrim/TextPrim 自身保持轴对齐
+ * - shape 主体：按 shape 分发（rect / ellipse / path）
+ * - text（如有内容）：始终走 TextPrim
+ * - 若有旋转：外面套一层 GroupPrim 用 SVG `rotate(deg cx cy)` 实现
+ *   （PathPrim 的 diamond 顶点已自带旋转坐标，但 text 需要 group 旋转，
+ *    所以仍统一用 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":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAMnD,MAAM,MAAM,UAAU,GAAG;IACvB,2CAA2C;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,IAAI,EAAE,IAAI,CAAC;IACX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,UAAU,KAAG,IASjD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,aAAa,YAAY,EACzB,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KACjC,UAqCF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,UAAU,EAClB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,KAAK,CAAC,cAAc,CAuCtB,CAAC"}
+{"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,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAOnD,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,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,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,UAmEF,CAAC;AAyDF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,UAAU,EAClB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,KAAK,CAAC,cAAc,CAyCtB,CAAC"}

package/dist/es/compile/node.js

@@ -1,26 +1,90 @@
+import { rect } from "../geometry/rect.js";
+import { circle } from "../geometry/circle.js";
+import { diamond } from "../geometry/diamond.js";
+import { ellipse } from "../geometry/ellipse.js";
 import { resolvePosition } from "./position.js";
 //#region src/compile/node.ts
 var DEFAULT_FONT_SIZE = 14;
 var DEFAULT_PADDING = 8;
 var DEG_TO_RAD = Math.PI / 180;
+var SQRT2 = Math.SQRT2;
+/** 由 layout 构造的 Rect（带 margin 扩张） */
+var rectOf = (layout, marginAdd) => ({
+	x: layout.rect.x,
+	y: layout.rect.y,
+	width: layout.rect.width + 2 * marginAdd,
+	height: layout.rect.height + 2 * marginAdd,
+	rotate: layout.rect.rotate
+});
+/** 由 layout 构造的 Circle（圆心 + 半径，半径=外接框边长/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） */
+var ellipseOf = (layout, marginAdd) => ({
+	x: layout.rect.x,
+	y: layout.rect.y,
+	rx: layout.rect.width / 2 + marginAdd,
+	ry: layout.rect.height / 2 + marginAdd,
+	rotate: layout.rect.rotate
+});
+/** 由 layout 构造的 Diamond（halfA/halfB 各加 margin） */
+var diamondOf = (layout, marginAdd) => ({
+	x: layout.rect.x,
+	y: layout.rect.y,
+	halfA: layout.rect.width / 2 + marginAdd,
+	halfB: layout.rect.height / 2 + marginAdd,
+	rotate: layout.rect.rotate
+});
 /**
-* 取节点的"附着 rect"——用于 path 端点贴边的几何盒。
-* 在视觉 rect 基础上每边外扩 margin，保持中心与旋转不变。
-* margin = 0 时直接返回视觉 rect 自身（避免无意义复制）。
+* 取节点 shape 在 toward 方向上的"附着点"——path 端点贴边用。
+* 按 shape 多态：rect / circle / ellipse / diamond 各自的 boundaryPoint。
+* margin > 0 时形状先外扩，让 path 在 border 外停 margin 个 user units。
 */
-var attachRectOf = (layout) => {
-	if (layout.margin === 0) return layout.rect;
-	return {
-		x: layout.rect.x,
-		y: layout.rect.y,
-		width: layout.rect.width + 2 * layout.margin,
-		height: layout.rect.height + 2 * layout.margin,
-		rotate: layout.rect.rotate
-	};
+var boundaryPointOf = (layout, toward) => {
+	const m = layout.margin;
+	switch (layout.shape) {
+		case "rectangle": return rect.boundaryPoint(rectOf(layout, m), toward);
+		case "circle": return circle.boundaryPoint(circleOf(layout, m), toward);
+		case "ellipse": return ellipse.boundaryPoint(ellipseOf(layout, m), toward);
+		case "diamond": return diamond.boundaryPoint(diamondOf(layout, m), toward);
+	}
+};
+/**
+* 取节点 shape 的命名 anchor（center / north / east / north-east 等 9 个）。
+* **不应用 margin**——TikZ 语义中 explicit anchor 取的是视觉边界点，不涉及 outer sep。
+* 用于 `'A.north'` 这种语法落点。
+*/
+var anchorOf = (layout, name) => {
+	switch (layout.shape) {
+		case "rectangle": return rect.anchor(rectOf(layout, 0), name);
+		case "circle": return circle.anchor(circleOf(layout, 0), name);
+		case "ellipse": return ellipse.anchor(ellipseOf(layout, 0), name);
+		case "diamond": return diamond.anchor(diamondOf(layout, 0), name);
+	}
+};
+/**
+* 取节点 shape 在指定角度方向上的边界点。角度约定与 PolarPosition 一致（度数）：
+*   0° = +x（east），90° = +y（screen 下方）。
+* **不应用 margin**——同 anchorOf。用于 `'A.30'` 这种语法落点。
+*/
+var angleBoundaryOf = (layout, angleDeg) => {
+	const rad = angleDeg * Math.PI / 180;
+	const toward = [layout.rect.x + Math.cos(rad), layout.rect.y + Math.sin(rad)];
+	switch (layout.shape) {
+		case "rectangle": return rect.boundaryPoint(rectOf(layout, 0), toward);
+		case "circle": return circle.boundaryPoint(circleOf(layout, 0), toward);
+		case "ellipse": return ellipse.boundaryPoint(ellipseOf(layout, 0), toward);
+		case "diamond": return diamond.boundaryPoint(diamondOf(layout, 0), toward);
+	}
 };
 /**
 * 把 IR Node 解析为内部 NodeLayout：
-* - 算出文本度量与 padding 推导出的视觉 rect 尺寸
+* - 算出文本度量与 padding 推导出"内框"半轴 (innerHalfW/H)
+* - 按 shape 决定外接边界尺寸（circle 取半对角线、ellipse 各 ×√2、diamond 各 ×2）
 * - 解析 position（笛卡尔或极坐标）为几何中心
 * - IR 的 rotate（度数）转弧度存进 Rect.rotate
 * - 透传 margin / 样式属性
@@ -32,18 +96,42 @@ var layoutNode = (node, measureText, nodeIndex) => {
 		width: 0,
 		height: 0
 	};
-	const width = Math.max(metrics.width + padding * 2, padding * 2);
-	const height = Math.max(metrics.height + padding * 2, padding * 2);
+	const innerHalfW = Math.max(metrics.width / 2 + padding, padding);
+	const innerHalfH = Math.max(metrics.height / 2 + padding, padding);
+	const shape = node.shape ?? "rectangle";
+	let boundsHalfW;
+	let boundsHalfH;
+	switch (shape) {
+		case "rectangle":
+			boundsHalfW = innerHalfW;
+			boundsHalfH = innerHalfH;
+			break;
+		case "circle": {
+			const r = Math.sqrt(innerHalfW * innerHalfW + innerHalfH * innerHalfH);
+			boundsHalfW = r;
+			boundsHalfH = r;
+			break;
+		}
+		case "ellipse":
+			boundsHalfW = innerHalfW * SQRT2;
+			boundsHalfH = innerHalfH * SQRT2;
+			break;
+		case "diamond":
+			boundsHalfW = innerHalfW * 2;
+			boundsHalfH = innerHalfH * 2;
+			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`);
 	return {
 		id: node.id,
+		shape,
 		rect: {
 			x: center[0],
 			y: center[1],
-			width,
-			height,
+			width: 2 * boundsHalfW,
+			height: 2 * boundsHalfH,
 			rotate: rotateDeg * DEG_TO_RAD
 		},
 		rotateDeg,
@@ -57,17 +145,11 @@ var layoutNode = (node, measureText, nodeIndex) => {
 		strokeWidth: node.strokeWidth
 	};
 };
-/**
-* 把 NodeLayout 翻译为 Scene primitives：
-* - rect（背景边框；x/y 转为 SVG 风格的左上角）
-* - text（如有内容）
-* - 若有旋转，外面套一层 GroupPrim 用 SVG `rotate(deg cx cy)` 实现，
-*   内层 RectPrim/TextPrim 自身保持轴对齐
-*/
-var emitNodePrimitives = (layout, round) => {
+/** rectangle shape 的 RectPrim */
+var emitRectShape = (layout, round) => {
 	const halfW = layout.rect.width / 2;
 	const halfH = layout.rect.height / 2;
-	const inner = [{
+	return {
 		type: "rect",
 		x: round(layout.rect.x - halfW),
 		y: round(layout.rect.y - halfH),
@@ -76,7 +158,57 @@ var emitNodePrimitives = (layout, round) => {
 		fill: layout.fill ?? "transparent",
 		stroke: layout.stroke ?? "currentColor",
 		strokeWidth: layout.strokeWidth ?? 1
-	}];
+	};
+};
+/** circle / ellipse shape 的 EllipsePrim（圆形 rx=ry） */
+var emitEllipseShape = (layout, round) => ({
+	type: "ellipse",
+	cx: round(layout.rect.x),
+	cy: round(layout.rect.y),
+	rx: round(layout.rect.width / 2),
+	ry: round(layout.rect.height / 2),
+	fill: layout.fill ?? "transparent",
+	stroke: layout.stroke ?? "currentColor",
+	strokeWidth: layout.strokeWidth ?? 1
+});
+/** diamond shape 的 PathPrim（4 顶点 + Z 闭合） */
+var emitDiamondShape = (layout, round) => {
+	const diam = diamondOf(layout, 0);
+	const e = diamond.anchor(diam, "east");
+	const n = diamond.anchor(diam, "north");
+	const w = diamond.anchor(diam, "west");
+	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`,
+		fill: layout.fill ?? "transparent",
+		stroke: layout.stroke ?? "currentColor",
+		strokeWidth: layout.strokeWidth ?? 1
+	};
+};
+/**
+* 把 NodeLayout 翻译为 Scene primitives：
+* - shape 主体：按 shape 分发（rect / ellipse / path）
+* - text（如有内容）：始终走 TextPrim
+* - 若有旋转：外面套一层 GroupPrim 用 SVG `rotate(deg cx cy)` 实现
+*   （PathPrim 的 diamond 顶点已自带旋转坐标，但 text 需要 group 旋转，
+*    所以仍统一用 group 包裹）
+*/
+var emitNodePrimitives = (layout, round) => {
+	let shapePrim;
+	switch (layout.shape) {
+		case "rectangle":
+			shapePrim = emitRectShape(layout, round);
+			break;
+		case "circle":
+		case "ellipse":
+			shapePrim = emitEllipseShape(layout, round);
+			break;
+		case "diamond":
+			shapePrim = emitDiamondShape(unrotated(layout), round);
+			break;
+	}
+	const inner = [shapePrim];
 	if (layout.text) inner.push({
 		type: "text",
 		x: round(layout.rect.x),
@@ -96,5 +228,13 @@ var emitNodePrimitives = (layout, round) => {
 		children: inner
 	}];
 };
+/** 返回 layout 的"未旋转"副本——用于先把 diamond 顶点按未旋转算，再由外层 group 统一旋转 */
+var unrotated = (layout) => ({
+	...layout,
+	rect: {
+		...layout.rect,
+		rotate: 0
+	}
+});
 //#endregion
-export { attachRectOf, emitNodePrimitives, layoutNode };
+export { anchorOf, angleBoundaryOf, boundaryPointOf, emitNodePrimitives, layoutNode };

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

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

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

@@ -0,0 +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"}

package/dist/es/compile/parseTarget.js

@@ -0,0 +1,48 @@
+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 + 字体改造时再支持）；角度纯数字（含可选 `.`/`-`）。
+*/
+/** alpha.1 支持的 anchor 名集合（RECT_ANCHORS 的 9 个值） */
+var ANCHOR_NAMES = new Set(Object.values(RECT_ANCHORS));
+/** 纯数字（可选小数 / 负号），用于识别 `A.30` / `A.-45` / `A.180.5` */
+var ANGLE_RE = /^-?\d+(\.\d+)?$/;
+/**
+* 解析节点 ref 字符串。
+*
+* - 不带 `.`：node（auto-clip）
+* - 带 `.` 后纯数字：angle（toward 方向上的边界点，与 PolarPosition 同角度约定）
+* - 带 `.` 后字母 / 连字符：anchor（命中 ANCHOR_NAMES 才合法，否则抛错）
+*
+* 抛错路径：未知 anchor 名（避免静默吞掉拼写错误）。
+*/
+var parseNodeRef = (s) => {
+	const dot = s.indexOf(".");
+	if (dot < 0) return {
+		kind: "node",
+		id: s
+	};
+	const id = s.slice(0, dot);
+	const tail = s.slice(dot + 1);
+	if (ANGLE_RE.test(tail)) return {
+		kind: "angle",
+		id,
+		angle: Number(tail)
+	};
+	if (!ANCHOR_NAMES.has(tail)) throw new Error(`parseNodeRef: unknown anchor '${tail}' in '${s}' (alpha.1 supports: ${[...ANCHOR_NAMES].join(", ")})`);
+	return {
+		kind: "anchor",
+		id,
+		anchor: tail
+	};
+};
+//#endregion
+export { parseNodeRef };

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