@retikz/core 0.0.1-rc.3 → 0.1.0-alpha.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 pionpill
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 pionpill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,27 @@
+import { IR } from '../ir';
+import { Scene } from '../primitive';
+import { TextMeasurer } from './text-metrics';
+/** compileToScene 的可选参数 */
+export type CompileOptions = {
+    /** 注入文字度量函数；不传则用 fallback（不准但可跑） */
+    measureText?: TextMeasurer;
+    /** viewBox 周围的留白（user units），默认 10 */
+    padding?: number;
+    /**
+     * 输出坐标的小数位精度；默认 2（保留 2 位小数四舍五入）。
+     * 仅在写入 Scene primitive / path d 字符串 / viewBox 时生效；
+     * 内部几何计算保持完整 double 精度，避免误差累积。
+     */
+    precision?: number;
+};
+/**
+ * IR → Scene。纯函数。
+ * 这是所有 adapter 共享的最深层共享代码。
+ *
+ * 流程：
+ * 1. Pass 1：按 IR children 源码顺序处理 Node——计算 layout、注册 nodeIndex、发出 RectPrim/TextPrim、累积 bbox 角点
+ * 2. Pass 2：处理 Path——解析每个 step 端点（节点 ref 走 boundaryPoint，其他走 resolvePosition），写 d 字符串
+ * 3. 末端用 computeViewBox 折算最终 viewBox（按 precision 四舍五入）
+ */
+export declare const compileToScene: (ir: IR, options?: CompileOptions) => Scene;
+//# sourceMappingURL=compile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAkB,MAAM,cAAc,CAAC;AAI1D,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAGrE,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KA2CrE,CAAC"}

package/dist/es/compile/compile.js

@@ -0,0 +1,43 @@
+import { rect } from "../geometry/rect.js";
+import { emitNodePrimitives, layoutNode } from "./node.js";
+import { emitPathPrimitive } from "./path.js";
+import { makeRound } from "./precision.js";
+import { fallbackMeasurer } from "./text-metrics.js";
+import { computeViewBox } from "./view-box.js";
+//#region src/compile/compile.ts
+/**
+* IR → Scene。纯函数。
+* 这是所有 adapter 共享的最深层共享代码。
+*
+* 流程：
+* 1. Pass 1：按 IR children 源码顺序处理 Node——计算 layout、注册 nodeIndex、发出 RectPrim/TextPrim、累积 bbox 角点
+* 2. Pass 2：处理 Path——解析每个 step 端点（节点 ref 走 boundaryPoint，其他走 resolvePosition），写 d 字符串
+* 3. 末端用 computeViewBox 折算最终 viewBox（按 precision 四舍五入）
+*/
+var compileToScene = (ir, options = {}) => {
+	const measureText = options.measureText ?? fallbackMeasurer;
+	const viewBoxPadding = options.padding ?? 10;
+	const round = makeRound(options.precision ?? 2);
+	const primitives = [];
+	const nodeIndex = /* @__PURE__ */ new Map();
+	const allPoints = [];
+	for (const child of ir.children) if (child.type === "node") {
+		const layout = layoutNode(child, measureText, nodeIndex);
+		if (child.id) nodeIndex.set(child.id, layout);
+		for (const prim of emitNodePrimitives(layout, round)) primitives.push(prim);
+		allPoints.push(rect.anchor(layout.rect, "north-west"), rect.anchor(layout.rect, "north-east"), rect.anchor(layout.rect, "south-west"), rect.anchor(layout.rect, "south-east"));
+	}
+	for (const child of ir.children) if (child.type === "path") {
+		const result = emitPathPrimitive(child, nodeIndex, round);
+		if (result) {
+			primitives.push(result.primitive);
+			for (const p of result.points) allPoints.push(p);
+		}
+	}
+	return {
+		primitives,
+		viewBox: computeViewBox(allPoints, viewBoxPadding, round)
+	};
+};
+//#endregion
+export { compileToScene };

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

@@ -0,0 +1,9 @@
+export * from './compile';
+export * from './node';
+export * from './parseTarget';
+export * from './path';
+export * from './position';
+export * from './precision';
+export * from './text-metrics';
+export * from './view-box';
+//# sourceMappingURL=index.d.ts.map

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

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

@@ -0,0 +1,76 @@
+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;
+    /** 节点形状——所有几何 / 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 附着到形状外扩 margin 的虚拟边界上 */
+    margin: number;
+    /** 节点文本内容；空字符串视为无文本（undefined） */
+    text?: string;
+    /** 文本宽度（user units），由 TextMeasurer 算出 */
+    textWidth: number;
+    /** 文本高度（user units），由 TextMeasurer 算出 */
+    textHeight: number;
+    /** 文本字号（user units） */
+    fontSize: number;
+    /** 节点背景色，CSS 颜色字符串；emit 时用 'transparent' 兜底 */
+    fill?: string;
+    /** 节点边框色，CSS 颜色字符串；emit 时用 'currentColor' 兜底 */
+    stroke?: string;
+    /** 节点边框宽度（user units）；emit 时用 1 兜底 */
+    strokeWidth?: number;
+};
+/**
+ * 取节点 shape 在 toward 方向上的"附着点"——path 端点贴边用。
+ * 按 shape 多态：rect / circle / ellipse / diamond 各自的 boundaryPoint。
+ * margin > 0 时形状先外扩，让 path 在 border 外停 margin 个 user units。
+ */
+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 推导出"内框"半轴 (innerHalfW/H)
+ * - 按 shape 决定外接边界尺寸（circle 取半对角线、ellipse 各 ×√2、diamond 各 ×2）
+ * - 解析 position（笛卡尔或极坐标）为几何中心
+ * - IR 的 rotate（度数）转弧度存进 Rect.rotate
+ * - 透传 margin / 样式属性
+ */
+export declare const layoutNode: (node: IRNode, measureText: TextMeasurer, nodeIndex: Map<string, NodeLayout>) => NodeLayout;
+/**
+ * 把 NodeLayout 翻译为 Scene primitives：
+ * - 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

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

@@ -0,0 +1,240 @@
+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
+});
+/**
+* 取节点 shape 在 toward 方向上的"附着点"——path 端点贴边用。
+* 按 shape 多态：rect / circle / ellipse / diamond 各自的 boundaryPoint。
+* margin > 0 时形状先外扩，让 path 在 border 外停 margin 个 user units。
+*/
+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 推导出"内框"半轴 (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 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: 2 * boundsHalfW,
+			height: 2 * boundsHalfH,
+			rotate: rotateDeg * DEG_TO_RAD
+		},
+		rotateDeg,
+		margin: node.margin ?? 0,
+		text: node.text,
+		textWidth: metrics.width,
+		textHeight: metrics.height,
+		fontSize,
+		fill: node.fill,
+		stroke: node.stroke,
+		strokeWidth: node.strokeWidth
+	};
+};
+/** rectangle shape 的 RectPrim */
+var emitRectShape = (layout, round) => {
+	const halfW = layout.rect.width / 2;
+	const halfH = layout.rect.height / 2;
+	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",
+		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),
+		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)
+	});
+	if (layout.rotateDeg === 0) return inner;
+	return [{
+		type: "group",
+		transform: `rotate(${round(layout.rotateDeg)} ${round(layout.rect.x)} ${round(layout.rect.y)})`,
+		children: inner
+	}];
+};
+/** 返回 layout 的"未旋转"副本——用于先把 diamond 顶点按未旋转算，再由外层 group 统一旋转 */
+var unrotated = (layout) => ({
+	...layout,
+	rect: {
+		...layout.rect,
+		rotate: 0
+	}
+});
+//#endregion
+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

@@ -0,0 +1,29 @@
+import { IRPath, IRPosition } from '../ir';
+import { ScenePrimitive } from '../primitive';
+import { NodeLayout } from './node';
+/**
+ * 把 IR Path 翻译为单个 PathPrim。
+ *
+ * 关键算法（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;
+    points: Array<IRPosition>;
+} | null;
+//# sourceMappingURL=path.d.ts.map

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

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