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

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,8 @@
+export * from './compile';
+export * from './node';
+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,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,51 @@
+import { Rect } from '../geometry/rect';
+import { IRNode } 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） */
+    rect: Rect;
+    /** IR 中原始的旋转角（度数），保留供 emit 阶段写 SVG transform */
+    rotateDeg: number;
+    /** 外边距（user units，≥ 0）；path 附着到 rect 外扩 margin 的虚拟 attachRect 上 */
+    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;
+};
+/**
+ * 取节点的"附着 rect"——用于 path 端点贴边的几何盒。
+ * 在视觉 rect 基础上每边外扩 margin，保持中心与旋转不变。
+ * margin = 0 时直接返回视觉 rect 自身（避免无意义复制）。
+ */
+export declare const attachRectOf: (layout: NodeLayout) => Rect;
+/**
+ * 把 IR Node 解析为内部 NodeLayout：
+ * - 算出文本度量与 padding 推导出的视觉 rect 尺寸
+ * - 解析 position（笛卡尔或极坐标）为几何中心
+ * - IR 的 rotate（度数）转弧度存进 Rect.rotate
+ * - 透传 margin / 样式属性
+ */
+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 自身保持轴对齐
+ */
+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":"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"}

package/dist/es/compile/node.js

@@ -0,0 +1,100 @@
+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;
+/**
+* 取节点的"附着 rect"——用于 path 端点贴边的几何盒。
+* 在视觉 rect 基础上每边外扩 margin，保持中心与旋转不变。
+* margin = 0 时直接返回视觉 rect 自身（避免无意义复制）。
+*/
+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
+	};
+};
+/**
+* 把 IR Node 解析为内部 NodeLayout：
+* - 算出文本度量与 padding 推导出的视觉 rect 尺寸
+* - 解析 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 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,
+		rect: {
+			x: center[0],
+			y: center[1],
+			width,
+			height,
+			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
+	};
+};
+/**
+* 把 NodeLayout 翻译为 Scene primitives：
+* - rect（背景边框；x/y 转为 SVG 风格的左上角）
+* - text（如有内容）
+* - 若有旋转，外面套一层 GroupPrim 用 SVG `rotate(deg cx cy)` 实现，
+*   内层 RectPrim/TextPrim 自身保持轴对齐
+*/
+var emitNodePrimitives = (layout, round) => {
+	const halfW = layout.rect.width / 2;
+	const halfH = layout.rect.height / 2;
+	const inner = [{
+		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
+	}];
+	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
+	}];
+};
+//#endregion
+export { attachRectOf, emitNodePrimitives, layoutNode };

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

@@ -0,0 +1,19 @@
+import { IRPath, IRPosition } from '../ir';
+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 整体跳过）。
+ */
+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":"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"}

package/dist/es/compile/path.js

@@ -0,0 +1,55 @@
+import { rect } from "../geometry/rect.js";
+import { resolvePosition } from "./position.js";
+import { attachRectOf } from "./node.js";
+//#region src/compile/path.ts
+/**
+* 求一个 step.to 的"参考点"——给邻居 step 算节点边界方向用：
+* - string（节点 ref） → 节点中心
+* - Position / PolarPosition → 解析后的笛卡尔
+* 解析失败返回 null（与 resolvePosition 一致）。
+*/
+var refPointOfTarget = (target, nodeIndex) => resolvePosition(target, nodeIndex);
+/**
+* 把 IR Path 翻译为单个 PathPrim。
+* 算法：
+* 1. 第一遍：把每个 step.to 解析为"参考点"（节点中心 / 直接坐标 / 极坐标解算后），
+*    用于给邻居 step 算节点边界点的方向；
+* 2. 第二遍：算每个 step 的实际终点——节点引用调用 boundaryPoint 贴 attachRect；
+*    其他形态直接用解析后的笛卡尔。
+* 3. 把点序列写成 SVG path d 字符串。
+*
+* 引用未定义节点时返回 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 points = [];
+	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(rect.boundaryPoint(attachRectOf(node), neighbor));
+		} else {
+			const resolved = resolvePosition(target, nodeIndex);
+			if (!resolved) return null;
+			points.push(resolved);
+		}
+	}
+	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
+		},
+		points
+	};
+};
+//#endregion
+export { emitPathPrimitive };

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

@@ -0,0 +1,9 @@
+import { IRPosition, PolarPosition } from '../ir';
+import { NodeLayout } from './node';
+/**
+ * 把 IR 里出现的位置形态（笛卡尔 / 极坐标 / 节点 id）解析为笛卡尔位置。
+ * 极坐标的 origin 可递归 / 可引用节点 id；按节点定义顺序处理（前向引用要求节点先定义）。
+ * 解析失败返回 null（如引用了未定义节点）。
+ */
+export declare const resolvePosition: (pos: IRPosition | PolarPosition | string, nodeMap: Map<string, NodeLayout>) => IRPosition | null;
+//# sourceMappingURL=position.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/compile/position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,UAAU,GAAG,aAAa,GAAG,MAAM,EACxC,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KAC/B,UAAU,GAAG,IAoBf,CAAC"}

package/dist/es/compile/position.js

@@ -0,0 +1,24 @@
+//#region src/compile/position.ts
+/**
+* 把 IR 里出现的位置形态（笛卡尔 / 极坐标 / 节点 id）解析为笛卡尔位置。
+* 极坐标的 origin 可递归 / 可引用节点 id；按节点定义顺序处理（前向引用要求节点先定义）。
+* 解析失败返回 null（如引用了未定义节点）。
+*/
+var resolvePosition = (pos, nodeMap) => {
+	if (typeof pos === "string") {
+		const node = nodeMap.get(pos);
+		return node ? [node.rect.x, node.rect.y] : null;
+	}
+	if (Array.isArray(pos)) return pos;
+	let origin;
+	if (!pos.origin) origin = [0, 0];
+	else {
+		const resolved = resolvePosition(pos.origin, nodeMap);
+		if (!resolved) return null;
+		origin = resolved;
+	}
+	const rad = pos.angle * Math.PI / 180;
+	return [origin[0] + Math.cos(rad) * pos.radius, origin[1] + Math.sin(rad) * pos.radius];
+};
+//#endregion
+export { resolvePosition };

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

@@ -0,0 +1,5 @@
+/** 默认输出精度：保留 2 位小数 */
+export declare const DEFAULT_PRECISION = 2;
+/** 按指定小数位精度四舍五入；precision = 0 表示取整 */
+export declare const makeRound: (precision: number) => (n: number) => number;
+//# sourceMappingURL=precision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"precision.d.ts","sourceRoot":"","sources":["../../../src/compile/precision.ts"],"names":[],"mappings":"AAAA,sBAAsB;AACtB,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,sCAAsC;AACtC,eAAO,MAAM,SAAS,GAAI,WAAW,MAAM,MAEjC,GAAG,MAAM,WAClB,CAAC"}

package/dist/es/compile/precision.js

@@ -0,0 +1,8 @@
+//#region src/compile/precision.ts
+/** 按指定小数位精度四舍五入；precision = 0 表示取整 */
+var makeRound = (precision) => {
+	const factor = 10 ** precision;
+	return (n) => Math.round(n * factor) / factor;
+};
+//#endregion
+export { makeRound };

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

@@ -0,0 +1,32 @@
+/** 字体规格：传给 TextMeasurer 的最小信息 */
+export type FontSpec = {
+    /** 字体族；不填走 fallback "sans-serif" */
+    family?: string;
+    /** 字号（user units） */
+    size: number;
+    /** 字重；可以是 'normal' / 'bold' / 100~900 数字等 */
+    weight?: string | number;
+    /** 字形：normal 或 italic */
+    style?: 'normal' | 'italic';
+};
+/** 文字度量结果：宽高 + 可选的基线 ascent/descent */
+export type TextMetrics = {
+    /** 文本宽度（user units） */
+    width: number;
+    /** 文本高度（user units），通常 ≈ ascent + descent */
+    height: number;
+    /** 基线以上的高度；不一定所有 measurer 都返回 */
+    ascent?: number;
+    /** 基线以下的深度；不一定所有 measurer 都返回 */
+    descent?: number;
+};
+/**
+ * 文字度量函数接口（编译期由 adapter 注入）。
+ * - @retikz/react：用 canvas measureText
+ * - @retikz/ssr：用 opentype.js / fontkit
+ * - @retikz/canvas：用 ctx.measureText
+ */
+export type TextMeasurer = (text: string, font: FontSpec) => TextMetrics;
+/** 默认 fallback 度量：基于平均字宽估算，不准但保证可运行 */
+export declare const fallbackMeasurer: TextMeasurer;
+//# sourceMappingURL=text-metrics.d.ts.map

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

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

package/dist/es/compile/text-metrics.js

@@ -0,0 +1,8 @@
+//#region src/compile/text-metrics.ts
+/** 默认 fallback 度量：基于平均字宽估算，不准但保证可运行 */
+var fallbackMeasurer = (text, font) => ({
+	width: text.length * font.size * .55,
+	height: font.size * 1.2
+});
+//#endregion
+export { fallbackMeasurer };

package/dist/es/compile/view-box.d.ts

@@ -0,0 +1,8 @@
+import { IRPosition } from '../ir';
+import { ViewBox } from '../primitive';
+/**
+ * 由所有"贡献给 bbox"的点算出 viewBox（含四周 padding）。
+ * points 为空时返回固定的 100×100 兜底框。
+ */
+export declare const computeViewBox: (points: Array<IRPosition>, padding: number, round: (n: number) => number) => ViewBox;
+//# sourceMappingURL=view-box.d.ts.map

package/dist/es/compile/view-box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-box.d.ts","sourceRoot":"","sources":["../../../src/compile/view-box.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,KAAK,CAAC,UAAU,CAAC,EACzB,SAAS,MAAM,EACf,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,OAkBF,CAAC"}

package/dist/es/compile/view-box.js

@@ -0,0 +1,31 @@
+//#region src/compile/view-box.ts
+/**
+* 由所有"贡献给 bbox"的点算出 viewBox（含四周 padding）。
+* points 为空时返回固定的 100×100 兜底框。
+*/
+var computeViewBox = (points, padding, round) => {
+	if (points.length === 0) return {
+		x: 0,
+		y: 0,
+		width: 100,
+		height: 100
+	};
+	let minX = Infinity;
+	let minY = Infinity;
+	let maxX = -Infinity;
+	let maxY = -Infinity;
+	for (const [x, y] of points) {
+		if (x < minX) minX = x;
+		if (y < minY) minY = y;
+		if (x > maxX) maxX = x;
+		if (y > maxY) maxY = y;
+	}
+	return {
+		x: round(minX - padding),
+		y: round(minY - padding),
+		width: round(maxX - minX + padding * 2),
+		height: round(maxY - minY + padding * 2)
+	};
+};
+//#endregion
+export { computeViewBox };

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

@@ -0,0 +1,4 @@
+export * from './point';
+export * from './rect';
+export * from './polar';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geometry/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/es/geometry/point.d.ts

@@ -0,0 +1,25 @@
+import { PolarPosition } from './polar';
+/** 笛卡尔坐标点 [x, y] */
+export type Position = [number, number];
+/** 二维向量 / 坐标的基础运算工具集 */
+export declare const point: {
+    /** 两点相加（向量加法）：a + b */
+    add: (a: Position, b: Position) => Position;
+    /** 两点相减（向量减法）：a - b */
+    sub: (a: Position, b: Position) => Position;
+    /** 等比缩放：a * k */
+    scale: (a: Position, k: number) => Position;
+    /** 判断两点坐标是否完全相等（精确比较，不带容差） */
+    equal: (a: Position, b: Position) => boolean;
+    /** 笛卡尔点 → 极坐标（angle 落在 (-180, 180]，origin 取默认 [0, 0]） */
+    toPolar: (p: Position) => PolarPosition;
+    /**
+     * 判断两个点是否相同（跨坐标系）。每个参数可以是笛卡尔 [x, y] 或 PolarPosition；
+     * 极坐标先转为笛卡尔，再按 precision 指定的小数位数四舍五入比较。
+     * `polar.equal` 委托到本方法。
+     * @param precision 小数点后位数；默认 2
+     * @throws 当 PolarPosition 的 origin 是节点 id 字符串时——字符串解析需 Scene 上下文
+     */
+    equalPolar: (a: Position | PolarPosition, b: Position | PolarPosition, precision?: number) => boolean;
+};
+//# sourceMappingURL=point.d.ts.map

package/dist/es/geometry/point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"point.d.ts","sourceRoot":"","sources":["../../../src/geometry/point.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAS,MAAM,SAAS,CAAC;AAEpD,oBAAoB;AACpB,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAIxC,wBAAwB;AACxB,eAAO,MAAM,KAAK;IAChB,uBAAuB;aACd,QAAQ,KAAK,QAAQ,KAAG,QAAQ;IACzC,uBAAuB;aACd,QAAQ,KAAK,QAAQ,KAAG,QAAQ;IACzC,iBAAiB;eACN,QAAQ,KAAK,MAAM,KAAG,QAAQ;IACzC,8BAA8B;eACnB,QAAQ,KAAK,QAAQ,KAAG,OAAO;IAC1C,yDAAyD;iBAC5C,QAAQ,KAAG,aAAa;IAIrC;;;;;;OAMG;oBAEE,QAAQ,GAAG,aAAa,KACxB,QAAQ,GAAG,aAAa,yBAE1B,OAAO;CASX,CAAC"}

package/dist/es/geometry/point.js

@@ -0,0 +1,34 @@
+import { polar } from "./polar.js";
+//#region src/geometry/point.ts
+var RAD_TO_DEG = 180 / Math.PI;
+/** 二维向量 / 坐标的基础运算工具集 */
+var point = {
+	/** 两点相加（向量加法）：a + b */
+	add: (a, b) => [a[0] + b[0], a[1] + b[1]],
+	/** 两点相减（向量减法）：a - b */
+	sub: (a, b) => [a[0] - b[0], a[1] - b[1]],
+	/** 等比缩放：a * k */
+	scale: (a, k) => [a[0] * k, a[1] * k],
+	/** 判断两点坐标是否完全相等（精确比较，不带容差） */
+	equal: (a, b) => a[0] === b[0] && a[1] === b[1],
+	/** 笛卡尔点 → 极坐标（angle 落在 (-180, 180]，origin 取默认 [0, 0]） */
+	toPolar: (p) => ({
+		angle: Math.atan2(p[1], p[0]) * RAD_TO_DEG,
+		radius: Math.hypot(p[0], p[1])
+	}),
+	/**
+	* 判断两个点是否相同（跨坐标系）。每个参数可以是笛卡尔 [x, y] 或 PolarPosition；
+	* 极坐标先转为笛卡尔，再按 precision 指定的小数位数四舍五入比较。
+	* `polar.equal` 委托到本方法。
+	* @param precision 小数点后位数；默认 2
+	* @throws 当 PolarPosition 的 origin 是节点 id 字符串时——字符串解析需 Scene 上下文
+	*/
+	equalPolar: (a, b, precision = 2) => {
+		const aCart = Array.isArray(a) ? a : polar.toPosition(a);
+		const bCart = Array.isArray(b) ? b : polar.toPosition(b);
+		const factor = 10 ** precision;
+		return Math.round(aCart[0] * factor) === Math.round(bCart[0] * factor) && Math.round(aCart[1] * factor) === Math.round(bCart[1] * factor);
+	}
+};
+//#endregion
+export { point };

package/dist/es/geometry/polar.d.ts

@@ -0,0 +1,44 @@
+import { Position } from './point';
+/**
+ * 极坐标点：相对 origin 的角度 + 半径偏移。
+ * - 可进 IR；Scene 编译时统一解析为笛卡尔
+ * - 不直接参与几何计算，参与时先转为 Position（见本文件顶部说明）
+ * - origin 可嵌套（PolarPosition），可引用节点 id（string），可直接给坐标（Position），省略表示原点 [0, 0]
+ */
+export type PolarPosition = {
+    /** 极坐标原点：节点 id / 笛卡尔位置 / 嵌套极坐标；省略表示 [0, 0] */
+    origin?: string | Position | PolarPosition;
+    /** 角度（度数，逆时针为正，与 TikZ / 数学习惯一致） */
+    angle: number;
+    /** 半径（user units，应为非负） */
+    radius: number;
+};
+/**
+ * 极坐标 ↔ 笛卡尔坐标 转换工具集。
+ *
+ * 注意 polar 不参与几何计算——参与计算时一律先用 `polar.toPosition` 转成 Position。
+ * 详见本文件顶部的整体说明。
+ */
+export declare const polar: {
+    /**
+     * 极坐标 → 笛卡尔位置（递归处理 origin）。
+     * **限制**：origin 为字符串（节点 id）时本方法无法解析，会抛错——
+     * 字符串解析依赖 Scene 编译器的 nodeIndex 上下文。
+     */
+    toPosition: (p: PolarPosition) => Position;
+    /** 笛卡尔位置 → 极坐标（angle 落在 (-180, 180]，origin 取默认 [0, 0]） */
+    fromPosition: (p: Position) => PolarPosition;
+    /** 在某个原点附近按极坐标偏移；返回结果点的世界笛卡尔坐标 */
+    offsetFrom: (origin: Position, offset: {
+        angle: number;
+        radius: number;
+    }) => Position;
+    /**
+     * 判断两个点是否相同（跨坐标系）。每个参数可以是笛卡尔 [x, y] 或 PolarPosition；
+     * 极坐标先转为笛卡尔，再按 precision 指定的小数位数四舍五入比较。
+     * 实际是 `point.equalPolar` 的别名（同一份实现，两处可发现）。
+     * @param precision 小数点后位数；默认 2
+     */
+    equal: (a: Position | PolarPosition, b: Position | PolarPosition, precision?: number) => boolean;
+};
+//# sourceMappingURL=polar.d.ts.map

package/dist/es/geometry/polar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polar.d.ts","sourceRoot":"","sources":["../../../src/geometry/polar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAS,MAAM,SAAS,CAAC;AAkB/C;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC3C,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB;;;;OAIG;oBACa,aAAa,KAAG,QAAQ;IAmBxC,0DAA0D;sBACxC,QAAQ,KAAG,aAAa;IAI1C,kCAAkC;yBAExB,QAAQ,UACR;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KACxC,QAAQ;IAOX;;;;;OAKG;eAEE,QAAQ,GAAG,aAAa,KACxB,QAAQ,GAAG,aAAa,yBAE1B,OAAO;CACX,CAAC"}