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

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,40 +1,90 @@
-import { Rect } from '../geometry/rect';
-import { IRNode } from '../ir';
-import { ScenePrimitive } from '../primitive';
+import { Position } from '../geometry/point';
+import { Rect, RectAnchor } from '../geometry/rect';
+import { IRNode, NodeShape } from '../ir';
+import { ScenePrimitive, TextLine } 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;
-    /** 文本宽度（user units），由 TextMeasurer 算出 */
+    /**
+     * 节点文本行；undefined 表示无文本，否则非空数组。
+     * 每行可带覆盖样式（fill / opacity / fontSize / fontFamily / fontWeight / fontStyle）；
+     * 未覆盖的字段在 emit 阶段不写出，由下游走 TextPrim 块级默认。
+     */
+    lines?: Array<TextLine>;
+    /** 文本块宽度（user units）= max(per-line measureText.width) */
     textWidth: number;
-    /** 文本高度（user units），由 TextMeasurer 算出 */
+    /** 文本块高度（user units）≈ lines × lineHeight */
     textHeight: number;
-    /** 文本字号（user units） */
+    /** 文本对齐（已映射到 SVG textAnchor 三态）；emit 时透传给 TextPrim.align */
+    align: 'start' | 'middle' | 'end';
+    /** 行高（user units），已应用默认值；emit 时透传给 TextPrim.lineHeight */
+    lineHeight: number;
+    /** 文本字号（user units），已应用默认值 */
     fontSize: number;
-    /** 节点矩形背景色，CSS 颜色字符串；emit 时用 'transparent' 兜底 */
+    /** 字体族；CSS font-family；emit 时透传给 TextPrim */
+    fontFamily?: string;
+    /** 字重；emit 时透传给 TextPrim */
+    fontWeight?: string | number;
+    /** 字形：normal / italic / oblique；emit 时透传给 TextPrim */
+    fontStyle?: 'normal' | 'italic' | 'oblique';
+    /** 节点背景色，CSS 颜色字符串；emit 时用 'transparent' 兜底 */
     fill?: string;
-    /** 节点矩形边框色，CSS 颜色字符串；emit 时用 'currentColor' 兜底 */
+    /** 节点填充透明度 0~1；透传 shape primitive */
+    fillOpacity?: number;
+    /** 节点边框色，CSS 颜色字符串；emit 时用 'currentColor' 兜底 */
     stroke?: string;
-    /** 节点矩形边框宽度（user units）；emit 时用 1 兜底 */
+    /** 节点描边透明度 0~1；TikZ `draw opacity`，透传 shape primitive */
+    strokeOpacity?: number;
+    /** 节点边框宽度（user units）；emit 时用 1 兜底 */
     strokeWidth?: number;
+    /** SVG stroke-dasharray 字符串；compile 已把 dashed / dotted 预设解析为具体 pattern */
+    strokeDasharray?: string;
+    /** rectangle shape 的圆角半径（user units）；非 rect shape 该字段无效 */
+    roundedCorners?: number;
+    /** 文字颜色；emit 时透传给 TextPrim.fill，兜底 'currentColor' */
+    textColor?: string;
+    /** 整节点透明度 0~1；emit 时同时挂 shape 与 text primitive */
+    opacity?: 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 +92,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,EAAc,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA8BnD,MAAM,MAAM,UAAU,GAAG;IACvB,2CAA2C;IAC3C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;OAQG;IACH,IAAI,EAAE,IAAI,CAAC;IACX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,sDAAsD;IACtD,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAsCF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,UAAU,EAAE,QAAQ,QAAQ,KAAG,QAYtE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,UAAU,EAAE,MAAM,UAAU,KAAG,QAW/D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,UAAU,EAAE,UAAU,MAAM,KAAG,QActE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,aAAa,YAAY,EACzB,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KACjC,UAgJF,CAAC;AAsEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,UAAU,EAClB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,KAAK,CAAC,cAAc,CAoDtB,CAAC"}

package/dist/es/compile/node.js

@@ -1,94 +1,310 @@
+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 DEFAULT_LINE_HEIGHT_FACTOR = 1.2;
 var DEG_TO_RAD = Math.PI / 180;
+var SQRT2 = Math.SQRT2;
+/** dashed 预设：SVG stroke-dasharray "4 2"——4 px 实线 + 2 px 间隙循环 */
+var DASHED_PATTERN = "4 2";
+/** dotted 预设：SVG stroke-dasharray "1 2"——1 px 圆点 + 2 px 间隙 */
+var DOTTED_PATTERN = "1 2";
+/** 解析 dashed / dotted / dashArray 优先级：dashArray > dashed > dotted */
+var resolveDashArray = (dashArray, dashed, dotted) => {
+	if (dashArray !== void 0) return dashArray;
+	if (dashed) return DASHED_PATTERN;
+	if (dotted) return DOTTED_PATTERN;
+};
+/** IR `align` ('left' | 'center' | 'right') → SVG textAnchor ('start' | 'middle' | 'end') */
+var alignToTextAnchor = (a) => a === "left" ? "start" : a === "right" ? "end" : "middle";
+/** 由 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 / 样式属性
 */
 var layoutNode = (node, measureText, nodeIndex) => {
-	const fontSize = node.fontSize ?? DEFAULT_FONT_SIZE;
-	const padding = node.padding ?? DEFAULT_PADDING;
-	const metrics = node.text ? measureText(node.text, { size: fontSize }) : {
-		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 sx = node.xScale ?? node.scale ?? 1;
+	const sy = node.yScale ?? node.scale ?? 1;
+	const fontScale = Math.min(sx, sy);
+	const baseFontSize = node.font?.size ?? DEFAULT_FONT_SIZE;
+	const fontSize = baseFontSize * fontScale;
+	const fontFamily = node.font?.family;
+	const fontWeight = node.font?.weight;
+	const fontStyle = node.font?.style;
+	const xSep = (node.innerXSep ?? node.padding ?? DEFAULT_PADDING) * sx;
+	const ySep = (node.innerYSep ?? node.padding ?? DEFAULT_PADDING) * sy;
+	const outerSep = (node.outerSep ?? node.margin ?? 0) * Math.max(sx, sy);
+	const lineHeight = (node.lineHeight ?? baseFontSize * DEFAULT_LINE_HEIGHT_FACTOR) * sy;
+	const align = alignToTextAnchor(node.align ?? "center");
+	const rawLines = node.text === void 0 ? void 0 : typeof node.text === "string" ? [node.text] : node.text;
+	let textWidth = 0;
+	let textHeight = 0;
+	let lines;
+	if (rawLines) {
+		lines = rawLines.map((spec) => {
+			const isObj = typeof spec !== "string";
+			const text = isObj ? spec.text : spec;
+			const lineFont = isObj ? spec.font : void 0;
+			const m = measureText(text, {
+				size: lineFont?.size ?? fontSize,
+				family: lineFont?.family ?? fontFamily,
+				weight: lineFont?.weight ?? fontWeight,
+				style: lineFont?.style ?? fontStyle
+			});
+			if (m.width > textWidth) textWidth = m.width;
+			const out = { text };
+			if (isObj) {
+				if (spec.fill !== void 0) out.fill = spec.fill;
+				if (spec.opacity !== void 0) out.opacity = spec.opacity;
+				if (lineFont?.size !== void 0) out.fontSize = lineFont.size;
+				if (lineFont?.family !== void 0) out.fontFamily = lineFont.family;
+				if (lineFont?.weight !== void 0) out.fontWeight = lineFont.weight;
+				if (lineFont?.style !== void 0) out.fontStyle = lineFont.style;
+			}
+			return out;
+		});
+		textHeight = lines.length * lineHeight;
+	}
+	const minW = node.minimumWidth ?? node.minimumSize ?? 0;
+	const minH = node.minimumHeight ?? node.minimumSize ?? 0;
+	const innerHalfW = Math.max(textWidth / 2 + xSep, xSep, minW / 2);
+	const innerHalfH = Math.max(textHeight / 2 + ySep, ySep, minH / 2);
+	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,
-		margin: node.margin ?? 0,
-		text: node.text,
-		textWidth: metrics.width,
-		textHeight: metrics.height,
+		margin: outerSep,
+		lines,
+		textWidth,
+		textHeight,
+		align,
+		lineHeight,
 		fontSize,
+		fontFamily,
+		fontWeight,
+		fontStyle,
 		fill: node.fill,
+		fillOpacity: node.fillOpacity,
 		stroke: node.stroke,
-		strokeWidth: node.strokeWidth
+		strokeOpacity: node.drawOpacity,
+		strokeWidth: node.strokeWidth,
+		strokeDasharray: resolveDashArray(node.dashArray, node.dashed, node.dotted),
+		roundedCorners: node.roundedCorners,
+		textColor: node.textColor,
+		opacity: node.opacity
 	};
 };
-/**
-* 把 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),
 		width: round(layout.rect.width),
 		height: round(layout.rect.height),
 		fill: layout.fill ?? "transparent",
+		fillOpacity: layout.fillOpacity,
 		stroke: layout.stroke ?? "currentColor",
-		strokeWidth: layout.strokeWidth ?? 1
-	}];
-	if (layout.text) inner.push({
-		type: "text",
-		x: round(layout.rect.x),
-		y: round(layout.rect.y),
-		content: layout.text,
-		fontSize: layout.fontSize,
-		align: "middle",
-		baseline: "middle",
-		fill: "currentColor",
-		measuredWidth: round(layout.textWidth),
-		measuredHeight: round(layout.textHeight)
-	});
+		strokeOpacity: layout.strokeOpacity,
+		strokeWidth: layout.strokeWidth ?? 1,
+		strokeDasharray: layout.strokeDasharray,
+		cornerRadius: layout.roundedCorners,
+		opacity: layout.opacity
+	};
+};
+/** 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",
+	fillOpacity: layout.fillOpacity,
+	stroke: layout.stroke ?? "currentColor",
+	strokeOpacity: layout.strokeOpacity,
+	strokeWidth: layout.strokeWidth ?? 1,
+	strokeDasharray: layout.strokeDasharray,
+	opacity: layout.opacity
+});
+/** 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",
+		fillOpacity: layout.fillOpacity,
+		stroke: layout.stroke ?? "currentColor",
+		strokeOpacity: layout.strokeOpacity,
+		strokeWidth: layout.strokeWidth ?? 1,
+		strokeDasharray: layout.strokeDasharray,
+		opacity: layout.opacity
+	};
+};
+/**
+* 把 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.lines) {
+		const halfBlockW = layout.textWidth / 2;
+		const xOffset = layout.align === "start" ? -halfBlockW : layout.align === "end" ? halfBlockW : 0;
+		inner.push({
+			type: "text",
+			x: round(layout.rect.x + xOffset),
+			y: round(layout.rect.y),
+			lines: layout.lines,
+			fontSize: layout.fontSize,
+			fontFamily: layout.fontFamily,
+			fontWeight: layout.fontWeight,
+			fontStyle: layout.fontStyle,
+			align: layout.align,
+			baseline: "middle",
+			lineHeight: round(layout.lineHeight),
+			fill: layout.textColor ?? "currentColor",
+			opacity: layout.opacity,
+			measuredWidth: round(layout.textWidth),
+			measuredHeight: round(layout.textHeight)
+		});
+	}
 	if (layout.rotateDeg === 0) return inner;
 	return [{
 		type: "group",
@@ -96,5 +312,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"}