@retikz/core 0.1.0-alpha.5 → 0.1.0-beta.2

package/dist/lib/compile/{path.d.ts → path/index.d.ts}

@@ -1,13 +1,24 @@
-import { IRPath, IRPosition } from '../ir';
-import { ScenePrimitive } from '../primitive';
-import { NodeLayout } from './node';
-import { TextMeasurer } from './text-metrics';
+import { IRPath, IRPosition } from '../../ir';
+import { ScenePrimitive } from '../../primitive';
+import { NodeLayout } from '../node';
+import { TextMeasurer } from '../text-metrics';
+/** emitPathPrimitive 可选 warn 钩子 */
+export type EmitPathWarnHook = {
+    /** 警告收集器（由 compileToScene 传入） */
+    onWarn?: (warning: {
+        code: string;
+        message: string;
+        path: string;
+    }) => void;
+    /** 当前 path 在 IR 中的 locator 前缀（如 `'children[3].path'`） */
+    irPath?: string;
+};
 /**
  * IR Path → PathPrim
- * @description 每个绘制段独立用节点中心算两端 boundary clip——中段节点的入/出 boundary 点通常不同，path 在该节点可见"断开"（与 TikZ `\draw (A)--(B)--(C);` 段独立 clip 一致）。仍产一个 PathPrim：commands 用多组 move/line 表达 sub-path；段起点等于上段终点时复用 cursor 省 move。cycle 段闭回最近 move 起点，起点==lastEnd && 终点==subPathStart 时输出 close，否则显式画段 line。引用未定义节点/解析失败返回 null
+ * @description 每个绘制段独立用节点中心算两端 boundary clip——中段节点的入/出 boundary 点通常不同，path 在该节点可见"断开"（与 TikZ `\draw (A)--(B)--(C);` 段独立 clip 一致）。仍产一个 PathPrim：commands 用多组 move/line 表达 sub-path；段起点等于上段终点时复用 cursor 省 move。cycle 段闭回最近 move 起点，起点==lastEnd && 终点==subPathStart 时输出 close，否则显式画段 line。引用未定义节点/解析失败返回 null，并通过 `warnHook.onWarn` 同步触发 warning
  */
-export declare const emitPathPrimitive: (path: IRPath, nodeIndex: Map<string, NodeLayout>, round: (n: number) => number, measureText?: TextMeasurer) => {
+export declare const emitPathPrimitive: (path: IRPath, nodeIndex: Map<string, NodeLayout>, round: (n: number) => number, measureText?: TextMeasurer, warnHook?: EmitPathWarnHook) => {
     primitives: Array<ScenePrimitive>;
     points: Array<IRPosition>;
 } | null;
-//# sourceMappingURL=path.d.ts.map
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/index.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EAGX,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAEV,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AA8BtE,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iCAAiC;IACjC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,KAAK,IAAI,CAAC;IACX,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAClC,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC5B,cAAa,YAA+B,EAC5C,WAAU,gBAAqB,KAC9B;IAAE,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CAAE,GAAG,IA0XrE,CAAC"}

package/dist/lib/compile/path/label.cjs

@@ -0,0 +1,103 @@
+//#region src/compile/path/label.ts
+/** 边标注默认字号 / 偏移量 */
+var LABEL_FONT_SIZE = 14;
+var LABEL_LINE_HEIGHT_FACTOR = 1.2;
+var LABEL_SIDE_OFFSET = 4;
+var RAD_TO_DEG = 180 / Math.PI;
+/** keyword → t 数值映射；含旧 3 keyword（midway/near-start/near-end）+ 新 4 keyword */
+var KEYWORD_TO_T = {
+	"at-start": 0,
+	"very-near-start": .125,
+	"near-start": .25,
+	midway: .5,
+	"near-end": .75,
+	"very-near-end": .875,
+	"at-end": 1
+};
+/**
+* label.position → 段参数 t∈[0,1]
+* @description 数值原样返回（schema 已 clamp 0..1）；keyword 走 KEYWORD_TO_T 映射；undefined 退默认 midway (0.5)
+*/
+var tForLabelPosition = (pos) => {
+	if (typeof pos === "number") return pos;
+	if (typeof pos === "string" && pos in KEYWORD_TO_T) return KEYWORD_TO_T[pos];
+	return .5;
+};
+/**
+* step.label + 段采样 → TextPrim（sloped 时裹一层 group 旋转）
+* @description 默认 side='above'/position='midway'：above/below 锚点 y±offset、align=middle、baseline=bottom/top；left/right x±offset、align=end/start、baseline=middle；sloped 不偏移裹 group rotate(angle, cx, cy) 由切线 atan2 算（SVG y-down CW 正）。返回 primitive + layout 外接点
+*/
+var emitLabelPrimitive = (label, sample, measureText, round) => {
+	const fontSize = LABEL_FONT_SIZE;
+	const lineHeight = fontSize * LABEL_LINE_HEIGHT_FACTOR;
+	const m = measureText(label.text, { size: fontSize });
+	const measuredWidth = m.width;
+	const measuredHeight = m.height || lineHeight;
+	const side = label.side ?? "above";
+	let x = sample.point[0];
+	let y = sample.point[1];
+	let align = "middle";
+	let baseline = "middle";
+	if (side === "above") {
+		y -= LABEL_SIDE_OFFSET;
+		baseline = "bottom";
+	} else if (side === "below") {
+		y += LABEL_SIDE_OFFSET;
+		baseline = "top";
+	} else if (side === "left") {
+		x -= LABEL_SIDE_OFFSET;
+		align = "end";
+	} else if (side === "right") {
+		x += LABEL_SIDE_OFFSET;
+		align = "start";
+	} else baseline = "bottom";
+	const text = {
+		type: "text",
+		x: round(x),
+		y: round(y),
+		lines: [{ text: label.text }],
+		fontSize,
+		align,
+		baseline,
+		lineHeight: round(lineHeight),
+		measuredWidth: round(measuredWidth),
+		measuredHeight: round(measuredHeight),
+		fill: "currentColor"
+	};
+	if (side === "sloped") {
+		const groupPrim = {
+			type: "group",
+			transforms: [{
+				kind: "rotate",
+				degrees: round(Math.atan2(sample.tangent[1], sample.tangent[0]) * RAD_TO_DEG),
+				cx: round(x),
+				cy: round(y)
+			}],
+			children: [text]
+		};
+		const r = Math.max(measuredWidth / 2, measuredHeight / 2);
+		return {
+			primitive: groupPrim,
+			points: [
+				[x - r, y - r],
+				[x + r, y - r],
+				[x - r, y + r],
+				[x + r, y + r]
+			]
+		};
+	}
+	const halfW = measuredWidth / 2;
+	const halfH = measuredHeight / 2;
+	return {
+		primitive: text,
+		points: [
+			[x - halfW, y - halfH],
+			[x + halfW, y - halfH],
+			[x - halfW, y + halfH],
+			[x + halfW, y + halfH]
+		]
+	};
+};
+//#endregion
+exports.emitLabelPrimitive = emitLabelPrimitive;
+exports.tForLabelPosition = tForLabelPosition;

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

@@ -0,0 +1,18 @@
+import { SegmentSample } from '../../geometry/segment';
+import { IRPosition, IRStepLabel } from '../../ir';
+import { ScenePrimitive } from '../../primitive';
+import { TextMeasurer } from '../text-metrics';
+/**
+ * label.position → 段参数 t∈[0,1]
+ * @description 数值原样返回（schema 已 clamp 0..1）；keyword 走 KEYWORD_TO_T 映射；undefined 退默认 midway (0.5)
+ */
+export declare const tForLabelPosition: (pos: IRStepLabel["position"]) => number;
+/**
+ * step.label + 段采样 → TextPrim（sloped 时裹一层 group 旋转）
+ * @description 默认 side='above'/position='midway'：above/below 锚点 y±offset、align=middle、baseline=bottom/top；left/right x±offset、align=end/start、baseline=middle；sloped 不偏移裹 group rotate(angle, cx, cy) 由切线 atan2 算（SVG y-down CW 正）。返回 primitive + layout 外接点
+ */
+export declare const emitLabelPrimitive: (label: IRStepLabel, sample: SegmentSample, measureText: TextMeasurer, round: (n: number) => number) => {
+    primitive: ScenePrimitive;
+    points: Array<IRPosition>;
+};
+//# sourceMappingURL=label.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/label.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAmBpD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,WAAW,CAAC,UAAU,CAAC,KAAG,MAIhE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,WAAW,EAClB,QAAQ,aAAa,EACrB,aAAa,YAAY,EACzB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CA8ExD,CAAC"}

package/dist/lib/compile/path/relative.cjs

@@ -0,0 +1,48 @@
+const require_arc = require("../../geometry/arc.cjs");
+const require_anchor = require("./anchor.cjs");
+//#region src/compile/path/relative.ts
+/**
+* relative/relativeAccumulate 目标解析为绝对 Position（step kind 不变，to 全为绝对坐标）
+* @description relative 不更新 prevEnd（TikZ `+`），relativeAccumulate 更新（TikZ `++`）。prevEnd 推进：有 to 的 kind 用 refPointOfTarget(to)；arc 用 arcEndPoint；circlePath/ellipsePath/cycle 不变。首步 relative 时 prevEnd 回退 [0,0]；解析失败保持原 step
+*/
+var normalizeRelativeTargets = (steps, nodeIndex) => {
+	let prevEnd = null;
+	const out = [];
+	for (const step of steps) {
+		if (step.kind === "cycle") {
+			out.push(step);
+			continue;
+		}
+		if (step.kind === "circlePath" || step.kind === "ellipsePath") {
+			out.push(step);
+			continue;
+		}
+		if (step.kind === "arc") {
+			out.push(step);
+			if (prevEnd) prevEnd = require_arc.arcEndPoint(prevEnd, step.radius, step.endAngle);
+			continue;
+		}
+		const original = step.to;
+		let resolvedTo = original;
+		let updatePrevEnd = true;
+		if (typeof original === "object" && !Array.isArray(original) && "relative" in original) {
+			const ref = prevEnd ?? [0, 0];
+			resolvedTo = [ref[0] + original.relative[0], ref[1] + original.relative[1]];
+			updatePrevEnd = false;
+		} else if (typeof original === "object" && !Array.isArray(original) && "relativeAccumulate" in original) {
+			const ref = prevEnd ?? [0, 0];
+			resolvedTo = [ref[0] + original.relativeAccumulate[0], ref[1] + original.relativeAccumulate[1]];
+		}
+		out.push({
+			...step,
+			to: resolvedTo
+		});
+		if (updatePrevEnd) {
+			const pos = require_anchor.refPointOfTarget(resolvedTo, nodeIndex);
+			if (pos) prevEnd = pos;
+		}
+	}
+	return out;
+};
+//#endregion
+exports.normalizeRelativeTargets = normalizeRelativeTargets;

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

@@ -0,0 +1,8 @@
+import { IRStep } from '../../ir';
+import { NodeLayout } from '../node';
+/**
+ * relative/relativeAccumulate 目标解析为绝对 Position（step kind 不变，to 全为绝对坐标）
+ * @description relative 不更新 prevEnd（TikZ `+`），relativeAccumulate 更新（TikZ `++`）。prevEnd 推进：有 to 的 kind 用 refPointOfTarget(to)；arc 用 arcEndPoint；circlePath/ellipsePath/cycle 不变。首步 relative 时 prevEnd 回退 [0,0]；解析失败保持原 step
+ */
+export declare const normalizeRelativeTargets: (steps: ReadonlyArray<IRStep>, nodeIndex: Map<string, NodeLayout>) => Array<IRStep>;
+//# sourceMappingURL=relative.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relative.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/relative.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAc,MAAM,EAAY,MAAM,UAAU,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG1C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KACjC,KAAK,CAAC,MAAM,CA0Dd,CAAC"}

package/dist/lib/compile/path/shrink.cjs

@@ -0,0 +1,128 @@
+const require_anchor = require("./anchor.cjs");
+const require_arrow_geometry = require("./arrow-geometry.cjs");
+//#region src/compile/path/shrink.ts
+/**
+* 端点级 spec：顶层默认 ⊕ end-side override（逐字段 merge）
+* @description 缺省字段继承顶层（不是"完全替换"）；空心 shape 上 fill 字段被丢（silent no-op）
+*/
+var resolveArrowEndSpec = (topLevel, endSide) => {
+	const baseShape = endSide?.shape ?? topLevel.shape ?? "normal";
+	const out = { shape: baseShape };
+	const scale = endSide?.scale ?? topLevel.scale;
+	if (scale !== void 0) out.scale = scale;
+	const length = endSide?.length ?? topLevel.length;
+	if (length !== void 0) out.length = length;
+	const width = endSide?.width ?? topLevel.width;
+	if (width !== void 0) out.width = width;
+	const color = endSide?.color ?? topLevel.color;
+	if (color !== void 0) out.color = color;
+	const opacity = endSide?.opacity ?? topLevel.opacity;
+	if (opacity !== void 0) out.opacity = opacity;
+	const lineWidth = endSide?.lineWidth ?? topLevel.lineWidth;
+	if (lineWidth !== void 0) out.lineWidth = lineWidth;
+	if (!require_arrow_geometry.isHollowArrowShape(baseShape)) {
+		const fill = endSide?.fill ?? topLevel.fill;
+		if (fill !== void 0) out.fill = fill;
+	}
+	return out;
+};
+/** IR path-level `arrow` + `arrowDetail` → PathPrim 起末端点箭头规格 */
+var endpointArrows = (arrow, detail) => {
+	if (!arrow || arrow === "none") return {};
+	const top = detail ?? {};
+	const startSpec = resolveArrowEndSpec(top, top.start);
+	const endSpec = resolveArrowEndSpec(top, top.end);
+	switch (arrow) {
+		case "->": return { arrowEnd: endSpec };
+		case "<-": return { arrowStart: startSpec };
+		case "<->": return {
+			arrowStart: startSpec,
+			arrowEnd: endSpec
+		};
+	}
+};
+/**
+* 端点级 shrink（strokeWidth 倍）：line 末端朝起点缩这么多，让箭头尖端落回原 target
+* @description 不分实心 / 空心：路径端点接在箭头尾部或凹口，箭头尖端仍贴原 target。低 opacity 下不会再透出 line。
+*/
+var computeShrink = (spec) => {
+	const geometry = require_arrow_geometry.resolveArrowShapeGeometry(spec);
+	const length = (spec.length ?? geometry.defaultLength) * (spec.scale ?? 1);
+	return (geometry.tipX - geometry.lineContactX) * length / geometry.baseSize;
+};
+/** 取一个 PathCommand 末端 endpoint（move/line/quad/cubic → to；arc/ellipseArc → polar(end)；close 无端点） */
+var endpointOf = (cmd) => {
+	switch (cmd.kind) {
+		case "move":
+		case "line":
+		case "quad":
+		case "cubic": return [cmd.to[0], cmd.to[1]];
+		case "arc": {
+			const rad = cmd.endAngle * Math.PI / 180;
+			return [cmd.center[0] + Math.cos(rad) * cmd.radius, cmd.center[1] + Math.sin(rad) * cmd.radius];
+		}
+		case "ellipseArc": {
+			const rad = cmd.endAngle * Math.PI / 180;
+			return [cmd.center[0] + Math.cos(rad) * cmd.radiusX, cmd.center[1] + Math.sin(rad) * cmd.radiusY];
+		}
+		case "close": return null;
+	}
+};
+/** 改写一个 PathCommand 的 endpoint（用于 shrink） */
+var setEndpoint = (commands, idx, newPt, round) => {
+	const cmd = commands[idx];
+	if (cmd.kind === "close") return;
+	const rp = [round(newPt[0]), round(newPt[1])];
+	if (cmd.kind === "move" || cmd.kind === "line") commands[idx] = {
+		...cmd,
+		to: rp
+	};
+	else if (cmd.kind === "quad") commands[idx] = {
+		...cmd,
+		to: rp
+	};
+	else if (cmd.kind === "cubic") commands[idx] = {
+		...cmd,
+		to: rp
+	};
+};
+/**
+* 按 shape + spec（length / scale / lineWidth）把首/末段端点向内缩短
+* @description 让 line 端点接在 hollow arrow 尾部外缘、不贯穿 back outline；shrink=0 的实心 shape 跳过。in-place 改写 commands 数组
+*/
+var applyArrowShrinks = (commands, shrinkStart, shrinkEnd, strokeWidth, round) => {
+	if (shrinkStart > 0) {
+		const firstIdx = commands.findIndex((o) => o.kind === "move");
+		if (firstIdx >= 0) {
+			const cur = commands[firstIdx];
+			const nextIdx = commands.findIndex((o, idx) => idx > firstIdx && o.kind !== "close");
+			if (cur.kind === "move" && nextIdx >= 0) {
+				const nextPt = endpointOf(commands[nextIdx]);
+				if (nextPt) setEndpoint(commands, firstIdx, require_anchor.shiftToward([cur.to[0], cur.to[1]], nextPt, shrinkStart * strokeWidth), round);
+			}
+		}
+	}
+	if (shrinkEnd > 0) {
+		let lastIdx = -1;
+		for (let i = commands.length - 1; i >= 0; i--) if (commands[i].kind !== "close") {
+			lastIdx = i;
+			break;
+		}
+		if (lastIdx > 0) {
+			let prevIdx = lastIdx - 1;
+			while (prevIdx >= 0 && commands[prevIdx].kind === "close") prevIdx--;
+			if (prevIdx >= 0) {
+				const curPt = endpointOf(commands[lastIdx]);
+				const prevPt = endpointOf(commands[prevIdx]);
+				if (curPt && prevPt) {
+					const shifted = require_anchor.shiftToward(curPt, prevPt, shrinkEnd * strokeWidth);
+					setEndpoint(commands, lastIdx, shifted, round);
+				}
+			}
+		}
+	}
+};
+//#endregion
+exports.applyArrowShrinks = applyArrowShrinks;
+exports.computeShrink = computeShrink;
+exports.endpointArrows = endpointArrows;

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

@@ -0,0 +1,18 @@
+import { IRArrowDetail } from '../../ir';
+import { ArrowEndSpec, PathCommand } from '../../primitive';
+/** IR path-level `arrow` + `arrowDetail` → PathPrim 起末端点箭头规格 */
+export declare const endpointArrows: (arrow: "none" | "->" | "<-" | "<->" | undefined, detail: IRArrowDetail | undefined) => {
+    arrowStart?: ArrowEndSpec;
+    arrowEnd?: ArrowEndSpec;
+};
+/**
+ * 端点级 shrink（strokeWidth 倍）：line 末端朝起点缩这么多，让箭头尖端落回原 target
+ * @description 不分实心 / 空心：路径端点接在箭头尾部或凹口，箭头尖端仍贴原 target。低 opacity 下不会再透出 line。
+ */
+export declare const computeShrink: (spec: ArrowEndSpec) => number;
+/**
+ * 按 shape + spec（length / scale / lineWidth）把首/末段端点向内缩短
+ * @description 让 line 端点接在 hollow arrow 尾部外缘、不贯穿 back outline；shrink=0 的实心 shape 跳过。in-place 改写 commands 数组
+ */
+export declare const applyArrowShrinks: (commands: Array<PathCommand>, shrinkStart: number, shrinkEnd: number, strokeWidth: number, round: (n: number) => number) => void;
+//# sourceMappingURL=shrink.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shrink.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/shrink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAgC,MAAM,UAAU,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAmCjE,gEAAgE;AAChE,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,SAAS,EAC/C,QAAQ,aAAa,GAAG,SAAS,KAChC;IAAE,UAAU,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;CAatD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,YAAY,KAAG,MAIlD,CAAC;AAiDF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,UAAU,KAAK,CAAC,WAAW,CAAC,EAC5B,aAAa,MAAM,EACnB,WAAW,MAAM,EACjB,aAAa,MAAM,EACnB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,IA4CF,CAAC"}

package/dist/lib/compile/path/split.cjs

@@ -0,0 +1,46 @@
+//#region src/compile/path/split.ts
+/**
+* 多 sub-path + 有端点箭头：按 sub-path split 成多个 PathPrim
+* @description 端点箭头只属于整条 path 的首端和末端；单 sub-path 或无箭头时直接产一个 PathPrim。
+*/
+var splitSubPathsForEndpointArrows = (commands, baseProps, endpointArrows) => {
+	const hasArrows = !!endpointArrows.arrowStart || !!endpointArrows.arrowEnd;
+	const subPathStarts = [];
+	commands.forEach((cmd, idx) => {
+		if (cmd.kind === "move") subPathStarts.push(idx);
+	});
+	if (!hasArrows || subPathStarts.length <= 1) return {
+		primitive: {
+			type: "path",
+			commands,
+			...baseProps,
+			...endpointArrows
+		},
+		isGrouped: false
+	};
+	const subPathSlices = [];
+	for (let s = 0; s < subPathStarts.length; s++) {
+		const start = subPathStarts[s];
+		const end = s + 1 < subPathStarts.length ? subPathStarts[s + 1] : commands.length;
+		subPathSlices.push(commands.slice(start, end));
+	}
+	return {
+		primitive: {
+			type: "group",
+			children: subPathSlices.map((sub, i) => {
+				const isFirst = i === 0;
+				const isLast = i === subPathSlices.length - 1;
+				return {
+					type: "path",
+					commands: sub,
+					...baseProps,
+					...isFirst && endpointArrows.arrowStart ? { arrowStart: endpointArrows.arrowStart } : {},
+					...isLast && endpointArrows.arrowEnd ? { arrowEnd: endpointArrows.arrowEnd } : {}
+				};
+			})
+		},
+		isGrouped: true
+	};
+};
+//#endregion
+exports.splitSubPathsForEndpointArrows = splitSubPathsForEndpointArrows;

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

@@ -0,0 +1,15 @@
+import { ArrowEndSpec, PathCommand, PathPrim, ScenePrimitive } from '../../primitive';
+/** baseProps：除 commands / endpoint arrows 外 PathPrim 公共属性集合（多 sub-path 复用） */
+export type PathBaseProps = Omit<PathPrim, 'type' | 'commands' | 'arrowStart' | 'arrowEnd'>;
+/**
+ * 多 sub-path + 有端点箭头：按 sub-path split 成多个 PathPrim
+ * @description 端点箭头只属于整条 path 的首端和末端；单 sub-path 或无箭头时直接产一个 PathPrim。
+ */
+export declare const splitSubPathsForEndpointArrows: (commands: Array<PathCommand>, baseProps: PathBaseProps, endpointArrows: {
+    arrowStart?: ArrowEndSpec;
+    arrowEnd?: ArrowEndSpec;
+}) => {
+    primitive: ScenePrimitive;
+    isGrouped: boolean;
+};
+//# sourceMappingURL=split.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"split.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/split.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3F,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC,CAAC;AAE5F;;;GAGG;AACH,eAAO,MAAM,8BAA8B,GACzC,UAAU,KAAK,CAAC,WAAW,CAAC,EAC5B,WAAW,aAAa,EACxB,gBAAgB;IAAE,UAAU,CAAC,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;CAAE,KACrE;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CA2CjD,CAAC"}

package/dist/lib/compile/text-metrics.cjs

@@ -1,8 +1,14 @@
 //#region src/compile/text-metrics.ts
-/** 默认 fallback 度量：基于平均字宽估算，不准但保证可运行 */
-var fallbackMeasurer = (text, font) => ({
-	width: text.length * font.size * .55,
-	height: font.size * 1.2
-});
+/**
+* 默认 fallback 度量：基于平均字宽估算，不准但保证可运行
+* @description size=0 → 退化返回 (0, 0)（与 text='' 一致）；负 size 或 NaN size → throw（非法输入早 fail，避免 NaN 噪音传播到 Scene）
+*/
+var fallbackMeasurer = (text, font) => {
+	if (Number.isNaN(font.size) || font.size < 0) throw new Error(`fallbackMeasurer: invalid font.size '${font.size}'; must be a non-negative finite number`);
+	return {
+		width: text.length * font.size * .55,
+		height: font.size * 1.2
+	};
+};
 //#endregion
 exports.fallbackMeasurer = fallbackMeasurer;

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

@@ -25,6 +25,9 @@ export type TextMetrics = {
  * @description @retikz/react: canvas measureText；@retikz/ssr: opentype.js/fontkit；@retikz/canvas: ctx.measureText
  */
 export type TextMeasurer = (text: string, font: FontSpec) => TextMetrics;
-/** 默认 fallback 度量：基于平均字宽估算，不准但保证可运行 */
+/**
+ * 默认 fallback 度量：基于平均字宽估算，不准但保证可运行
+ * @description size=0 → 退化返回 (0, 0)（与 text='' 一致）；负 size 或 NaN size → throw（非法输入早 fail，避免 NaN 噪音传播到 Scene）
+ */
 export declare const fallbackMeasurer: TextMeasurer;
 //# sourceMappingURL=text-metrics.d.ts.map

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

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

package/dist/lib/geometry/_transform.cjs

@@ -0,0 +1,28 @@
+//#region src/geometry/_transform.ts
+/**
+* 本地坐标（以中心为原点）→ 世界坐标
+* @description rotate=0 / 缺省时退化为平移；非零时按右手系绕中心旋转后再平移
+*/
+var localToWorld = (s, local) => {
+	const angle = s.rotate ?? 0;
+	if (angle === 0) return [s.x + local[0], s.y + local[1]];
+	const cos = Math.cos(angle);
+	const sin = Math.sin(angle);
+	return [s.x + local[0] * cos - local[1] * sin, s.y + local[0] * sin + local[1] * cos];
+};
+/**
+* 世界坐标 → 本地坐标（`localToWorld` 逆变换）
+* @description 先反平移到中心、再反旋转回本地基；旋转矩阵转置即逆
+*/
+var worldToLocal = (s, world) => {
+	const tx = world[0] - s.x;
+	const ty = world[1] - s.y;
+	const angle = s.rotate ?? 0;
+	if (angle === 0) return [tx, ty];
+	const cos = Math.cos(angle);
+	const sin = Math.sin(angle);
+	return [tx * cos + ty * sin, -tx * sin + ty * cos];
+};
+//#endregion
+exports.localToWorld = localToWorld;
+exports.worldToLocal = worldToLocal;

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

@@ -0,0 +1,21 @@
+import { Position } from './point';
+/** 任何"中心 + 可选旋转"形状的几何契约（rect / circle / ellipse / diamond 共用） */
+export type CenteredShape = {
+    /** 中心横坐标 */
+    x: number;
+    /** 中心纵坐标 */
+    y: number;
+    /** 绕中心旋转弧度（可选，0 / 缺省 = 不旋转） */
+    rotate?: number;
+};
+/**
+ * 本地坐标（以中心为原点）→ 世界坐标
+ * @description rotate=0 / 缺省时退化为平移；非零时按右手系绕中心旋转后再平移
+ */
+export declare const localToWorld: (s: CenteredShape, local: Position) => Position;
+/**
+ * 世界坐标 → 本地坐标（`localToWorld` 逆变换）
+ * @description 先反平移到中心、再反旋转回本地基；旋转矩阵转置即逆
+ */
+export declare const worldToLocal: (s: CenteredShape, world: Position) => Position;
+//# sourceMappingURL=_transform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"_transform.d.ts","sourceRoot":"","sources":["../../../src/geometry/_transform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG;IAC1B,YAAY;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,YAAY;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,aAAa,EAAE,OAAO,QAAQ,KAAG,QAShE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,aAAa,EAAE,OAAO,QAAQ,KAAG,QAQhE,CAAC"}

package/dist/lib/geometry/bend.cjs

@@ -1,7 +1,7 @@
 //#region src/geometry/bend.ts
 /**
 * cubic Bezier 拟合 from→to 的弧形 bend
-* @description apex offset = chord × tan(bendAngle/2)；控制点取 chord 1/3 与 2/3 处沿法向偏移，让 cubic 在 t=0.5 穿过 apex 故 ctlOffset = 4/3 × apexOffset。法向 SVG y-down：visual-left=(dy,-dx)/|chord|，visual-right=(-dy,dx)/|chord|。chord=0 时两控制点都返回 from
+* @description apex offset = chord × tan(bendAngle/2)；控制点取 chord 1/3 与 2/3 处沿法向偏移，让 cubic 在 t=0.5 穿过 apex 故 ctlOffset = 4/3 × apexOffset。法向（screen y-down）：visual-left=(dy,-dx)/|chord|，visual-right=(-dy,dx)/|chord|。chord=0 时两控制点都返回 from
 */
 var bendControlPoints = (from, to, direction, bendAngle) => {
 	const dx = to[0] - from[0];

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

@@ -1,7 +1,7 @@
 import { Position } from './point';
 /**
  * cubic Bezier 拟合 from→to 的弧形 bend
- * @description apex offset = chord × tan(bendAngle/2)；控制点取 chord 1/3 与 2/3 处沿法向偏移，让 cubic 在 t=0.5 穿过 apex 故 ctlOffset = 4/3 × apexOffset。法向 SVG y-down：visual-left=(dy,-dx)/|chord|，visual-right=(-dy,dx)/|chord|。chord=0 时两控制点都返回 from
+ * @description apex offset = chord × tan(bendAngle/2)；控制点取 chord 1/3 与 2/3 处沿法向偏移，让 cubic 在 t=0.5 穿过 apex 故 ctlOffset = 4/3 × apexOffset。法向（screen y-down）：visual-left=(dy,-dx)/|chord|，visual-right=(-dy,dx)/|chord|。chord=0 时两控制点都返回 from
  */
 export declare const bendControlPoints: (from: Position, to: Position, direction: "left" | "right", bendAngle: number) => [Position, Position];
 //# sourceMappingURL=bend.d.ts.map

package/dist/lib/geometry/circle.cjs

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

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

@@ -1,4 +1,5 @@
 import { Position } from './point';
+import { RectAnchor } from './rect';
 /** 圆形：几何中心 + 半径，预留旋转字段保持与 Rect 同形 API */
 export type Circle = {
     x: number;
@@ -8,8 +9,6 @@ export type Circle = {
     /** 绕中心旋转弧度（圆视觉不变，与 Rect 同形保留） */
     rotate?: number;
 };
-/** 圆形 9 个标准 anchor（与 RECT_ANCHORS 同名同义，圆周每 45° 等距分布） */
-export type CircleAnchor = 'center' | 'north' | 'south' | 'east' | 'west' | 'north-east' | 'north-west' | 'south-east' | 'south-west';
 /** 圆形相关基础工具 */
 export declare const circle: {
     /** 圆心 */
@@ -17,7 +16,7 @@ export declare const circle: {
     /** 判断点是否在圆内（含边界） */
     contains: (c: Circle, p: Position) => boolean;
     /** 9 个标准 anchor 之一的世界坐标 */
-    anchor: (c: Circle, name: CircleAnchor) => Position;
+    anchor: (c: Circle, name: RectAnchor) => Position;
     /** 从圆心向 toward 方向射线与圆周交点（Path 端点贴 Node 边界用） */
     boundaryPoint: (c: Circle, toward: Position) => Position;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"circle.d.ts","sourceRoot":"","sources":["../../../src/geometry/circle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,yCAAyC;AACzC,MAAM,MAAM,MAAM,GAAG;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,SAAS;IACT,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAIF,wDAAwD;AACxD,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,YAAY,CAAC;AAoBjB,eAAe;AACf,eAAO,MAAM,MAAM;IACjB,SAAS;gBACG,MAAM,KAAG,QAAQ;IAC7B,oBAAoB;kBACN,MAAM,KAAK,QAAQ,KAAG,OAAO;IAI3C,2BAA2B;gBACf,MAAM,QAAQ,YAAY,KAAG,QAAQ;IAsCjD,+CAA+C;uBAC5B,MAAM,UAAU,QAAQ,KAAG,QAAQ;CAOvD,CAAC"}
+{"version":3,"file":"circle.d.ts","sourceRoot":"","sources":["../../../src/geometry/circle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,yCAAyC;AACzC,MAAM,MAAM,MAAM,GAAG;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,SAAS;IACT,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAIF,eAAe;AACf,eAAO,MAAM,MAAM;IACjB,SAAS;gBACG,MAAM,KAAG,QAAQ;IAC7B,oBAAoB;kBACN,MAAM,KAAK,QAAQ,KAAG,OAAO;IAI3C,2BAA2B;gBACf,MAAM,QAAQ,UAAU,KAAG,QAAQ;IAsC/C,+CAA+C;uBAC5B,MAAM,UAAU,QAAQ,KAAG,QAAQ;CAOvD,CAAC"}