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

package/dist/es/compile/path/index.js

@@ -0,0 +1,308 @@
+import { arcBoundingPoints, arcEndPoint } from "../../geometry/arc.js";
+import { bendControlPoints } from "../../geometry/bend.js";
+import { arcSegmentSample, circleSegmentSample, cubicSegmentSample, ellipseSegmentSample, foldSegmentSample, lineSegmentSample, quadSegmentSample } from "../../geometry/segment.js";
+import { fallbackMeasurer } from "../text-metrics.js";
+import { clipForTarget, cornerOf, refPointOfTarget, samePoint } from "./anchor.js";
+import { emitLabelPrimitive, tForLabelPosition } from "./label.js";
+import { normalizeRelativeTargets } from "./relative.js";
+import { applyArrowShrinks, computeShrink, endpointArrows } from "./shrink.js";
+import { splitSubPathsForEndpointArrows } from "./split.js";
+//#region src/compile/path/index.ts
+/**
+* 语义 stroke 档位 → 数值（user units）
+* @description 对齐 TikZ 比例（thin=0.4pt→1=默认 strokeWidth）：ultraThin 0.25、veryThin 0.5、thin 1、semithick 1.5、thick 2、veryThick 3、ultraThick 4。显式 strokeWidth 覆盖 thickness。
+* `as const satisfies` + `AssertEqual` 双约束：加 IRPath['thickness'] 档位时漏写 TS 报错（字段表互锁，同 ADR-06 主题）
+*/
+var THICKNESS_TO_WIDTH = {
+	ultraThin: .25,
+	veryThin: .5,
+	thin: 1,
+	semithick: 1.5,
+	thick: 2,
+	veryThick: 3,
+	ultraThick: 4
+};
+/**
+* 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，并通过 `warnHook.onWarn` 同步触发 warning
+*/
+var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer, warnHook = {}) => {
+	const irPath = warnHook.irPath ?? "path";
+	const warn = (code, message, subPath = "") => {
+		warnHook.onWarn?.({
+			code,
+			message,
+			path: subPath ? `${irPath}.${subPath}` : irPath
+		});
+	};
+	const steps = normalizeRelativeTargets(path.children, nodeIndex);
+	if (steps.length < 2) {
+		warn("PATH_TOO_SHORT", `Path requires at least 2 steps (got ${steps.length}); the entire path is skipped`, "children");
+		return null;
+	}
+	/** 每段 step.label 翻译出的 TextPrim（或 sloped 旋转的 group），与 path 主体同级返回 */
+	const labelPrims = [];
+	/** 算 sample 后 emitLabelPrimitive，结果累积到 labelPrims/points */
+	const collectLabel = (step, sampleAt) => {
+		if (step.kind === "move" || step.kind === "cycle" || !("label" in step) || !step.label) return;
+		const sample = sampleAt(tForLabelPosition(step.label.position));
+		const r = emitLabelPrimitive(step.label, sample, measureText, round);
+		labelPrims.push(r.primitive);
+		for (const p of r.points) points.push(p);
+	};
+	const hasTo = (s) => s.kind !== "cycle" && s.kind !== "arc" && s.kind !== "circlePath" && s.kind !== "ellipsePath";
+	const anchors = steps.map((s, idx) => {
+		if (!hasTo(s)) return null;
+		const ref = refPointOfTarget(s.to, nodeIndex);
+		if (!ref && typeof s.to === "string") warn("UNRESOLVED_NODE_REFERENCE", `Step.to references undefined node id '${s.to}'; the entire path is skipped`, `children[${idx}].to`);
+		return ref;
+	});
+	/**
+	* 单调指针：最近一个 hasTo step 的索引；主循环开头根据上一 step 推进；O(1) 读
+	* @description 旧实现 findPrev(i) 反向扫 anchors 数组每步 O(i)、整 path O(n²)；改为只在 step `i-1` 是 hasTo 时推进。anchor 失效"中毒"判断保留：lastHasToIdx 指向的 anchor 为 null 时 findPrev 返回 null，与旧"扫到第一个 hasTo 步若 anchor=null 返回 null"语义等价
+	*/
+	let lastHasToIdx = -1;
+	/** 同步维护：最近一个 move 步的 `to`，给 cycle 闭合用；旧 findRecentMoveTo 反向扫 → O(1) */
+	let lastMoveTo = null;
+	/** 找最近一个"有 to 字段的 step" 及其 anchor；O(1) 读 lastHasToIdx */
+	const findPrev = () => {
+		if (lastHasToIdx === -1) return null;
+		const s = steps[lastHasToIdx];
+		if (!hasTo(s)) return null;
+		const a = anchors[lastHasToIdx];
+		if (!a) return null;
+		return {
+			step: s,
+			anchor: a
+		};
+	};
+	const commands = [];
+	const points = [];
+	let lastEnd = null;
+	let subPathStart = null;
+	/**
+	* 笔位覆盖：arc/circlePath/ellipsePath 无 `to` 字段不能用 prev.step.to 重算起点
+	* @description 设置 penOverride 让下个绘制段直接用此点当 fromClip 后清空。arc=弧终点；circlePath/ellipsePath=center（"画完留在圆心"）
+	*/
+	let penOverride = null;
+	const roundPoint = (p) => [round(p[0]), round(p[1])];
+	const emitMove = (p) => {
+		const rp = roundPoint(p);
+		commands.push({
+			kind: "move",
+			to: [rp[0], rp[1]]
+		});
+		points.push(p);
+		subPathStart = p;
+		lastEnd = p;
+	};
+	const emitLine = (p) => {
+		const rp = roundPoint(p);
+		commands.push({
+			kind: "line",
+			to: [rp[0], rp[1]]
+		});
+		points.push(p);
+		lastEnd = p;
+	};
+	const emitClose = () => {
+		commands.push({ kind: "close" });
+		lastEnd = subPathStart;
+	};
+	const emitQuad = (control, p) => {
+		const rc = roundPoint(control);
+		const rp = roundPoint(p);
+		commands.push({
+			kind: "quad",
+			control: [rc[0], rc[1]],
+			to: [rp[0], rp[1]]
+		});
+		points.push(control);
+		points.push(p);
+		lastEnd = p;
+	};
+	const emitCubic = (c1, c2, p) => {
+		const rc1 = roundPoint(c1);
+		const rc2 = roundPoint(c2);
+		const rp = roundPoint(p);
+		commands.push({
+			kind: "cubic",
+			control1: [rc1[0], rc1[1]],
+			control2: [rc2[0], rc2[1]],
+			to: [rp[0], rp[1]]
+		});
+		points.push(c1);
+		points.push(c2);
+		points.push(p);
+		lastEnd = p;
+	};
+	const emitArc = (center, radius, startAngle, endAngle) => {
+		const rc = roundPoint(center);
+		commands.push({
+			kind: "arc",
+			center: [rc[0], rc[1]],
+			radius: round(radius),
+			startAngle,
+			endAngle
+		});
+		points.push(arcEndPoint(center, radius, endAngle));
+		lastEnd = arcEndPoint(center, radius, endAngle);
+	};
+	const emitEllipseArc = (center, radiusX, radiusY, startAngle, endAngle) => {
+		const rc = roundPoint(center);
+		commands.push({
+			kind: "ellipseArc",
+			center: [rc[0], rc[1]],
+			radiusX: round(radiusX),
+			radiusY: round(radiusY),
+			startAngle,
+			endAngle
+		});
+		const endPt = [center[0] + Math.cos(endAngle * Math.PI / 180) * radiusX, center[1] + Math.sin(endAngle * Math.PI / 180) * radiusY];
+		points.push(endPt);
+		lastEnd = endPt;
+	};
+	/** 段起点：与 lastEnd 相同则复用 cursor（省 move），否则发 move */
+	const startSegment = (p) => {
+		if (samePoint(p, lastEnd)) return;
+		emitMove(p);
+	};
+	for (let i = 0; i < steps.length; i++) {
+		if (i > 0) {
+			const prevStep = steps[i - 1];
+			if (hasTo(prevStep)) lastHasToIdx = i - 1;
+			if (prevStep.kind === "move") lastMoveTo = prevStep.to;
+		}
+		const step = steps[i];
+		if (step.kind === "move") continue;
+		if (step.kind === "cycle") {
+			const moveTo = lastMoveTo;
+			const prev = findPrev();
+			if (!moveTo || !prev) continue;
+			const moveAnchor = refPointOfTarget(moveTo, nodeIndex);
+			if (!moveAnchor) return null;
+			const fromClip = clipForTarget(prev.step.to, moveAnchor, nodeIndex);
+			const toClip = clipForTarget(moveTo, prev.anchor, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			if (samePoint(fromClip, lastEnd) && samePoint(toClip, subPathStart)) {
+				emitClose();
+				continue;
+			}
+			startSegment(fromClip);
+			emitLine(toClip);
+			continue;
+		}
+		const prev = findPrev();
+		if (!prev) return null;
+		if (step.kind === "arc") {
+			const center = prev.anchor;
+			const startPt = arcEndPoint(center, step.radius, step.startAngle);
+			const endPt = arcEndPoint(center, step.radius, step.endAngle);
+			startSegment(startPt);
+			emitArc(center, step.radius, step.startAngle, step.endAngle);
+			for (const p of arcBoundingPoints(center, step.radius, step.startAngle, step.endAngle)) points.push(p);
+			collectLabel(step, (t) => arcSegmentSample(center, step.radius, step.startAngle, step.endAngle, t));
+			penOverride = endPt;
+			continue;
+		}
+		if (step.kind === "circlePath") {
+			const center = prev.anchor;
+			const r = step.radius;
+			startSegment([center[0] + r, center[1]]);
+			emitEllipseArc(center, r, r, 0, 360);
+			points.push([center[0] + r, center[1]]);
+			points.push([center[0] - r, center[1]]);
+			points.push([center[0], center[1] + r]);
+			points.push([center[0], center[1] - r]);
+			collectLabel(step, (t) => circleSegmentSample(center, r, t));
+			penOverride = center;
+			continue;
+		}
+		if (step.kind === "ellipsePath") {
+			const center = prev.anchor;
+			const rx = step.radiusX;
+			const ry = step.radiusY;
+			startSegment([center[0] + rx, center[1]]);
+			emitEllipseArc(center, rx, ry, 0, 360);
+			points.push([center[0] + rx, center[1]]);
+			points.push([center[0] - rx, center[1]]);
+			points.push([center[0], center[1] + ry]);
+			points.push([center[0], center[1] - ry]);
+			collectLabel(step, (t) => ellipseSegmentSample(center, rx, ry, t));
+			penOverride = center;
+			continue;
+		}
+		const currAnchor = anchors[i];
+		if (!currAnchor) return null;
+		const usedOverride = penOverride;
+		penOverride = null;
+		if (step.kind === "line") {
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, currAnchor, nodeIndex);
+			const toClip = clipForTarget(step.to, prev.anchor, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitLine(toClip);
+			collectLabel(step, (t) => lineSegmentSample(fromClip, toClip, t));
+			continue;
+		}
+		if (step.kind === "curve") {
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control, nodeIndex);
+			const toClip = clipForTarget(step.to, step.control, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitQuad(step.control, toClip);
+			collectLabel(step, (t) => quadSegmentSample(fromClip, step.control, toClip, t));
+			continue;
+		}
+		if (step.kind === "cubic") {
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control1, nodeIndex);
+			const toClip = clipForTarget(step.to, step.control2, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitCubic(step.control1, step.control2, toClip);
+			collectLabel(step, (t) => cubicSegmentSample(fromClip, step.control1, step.control2, toClip, t));
+			continue;
+		}
+		if (step.kind === "bend") {
+			const angle = step.bendAngle ?? 30;
+			const [c1, c2] = bendControlPoints(prev.anchor, currAnchor, step.bendDirection, angle);
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, c1, nodeIndex);
+			const toClip = clipForTarget(step.to, c2, nodeIndex);
+			if (!fromClip || !toClip) return null;
+			startSegment(fromClip);
+			emitCubic(c1, c2, toClip);
+			collectLabel(step, (t) => cubicSegmentSample(fromClip, c1, c2, toClip, t));
+			continue;
+		}
+		const corner = cornerOf(prev.anchor, currAnchor, step.via);
+		const fromClip = usedOverride ?? clipForTarget(prev.step.to, corner, nodeIndex);
+		const toClip = clipForTarget(step.to, corner, nodeIndex);
+		if (!fromClip || !toClip) return null;
+		startSegment(fromClip);
+		emitLine(corner);
+		emitLine(toClip);
+		collectLabel(step, (t) => foldSegmentSample(fromClip, corner, toClip, t));
+	}
+	const strokeWidth = path.strokeWidth ?? (path.thickness ? THICKNESS_TO_WIDTH[path.thickness] : 1);
+	const baseProps = {
+		stroke: path.stroke ?? "currentColor",
+		strokeWidth,
+		fill: path.fill ?? "none",
+		fillRule: path.fillRule,
+		dashPattern: path.dashPattern,
+		strokeLinecap: path.lineCap,
+		strokeLinejoin: path.lineJoin,
+		opacity: path.opacity,
+		fillOpacity: path.fillOpacity,
+		strokeOpacity: path.drawOpacity
+	};
+	const arrows = endpointArrows(path.arrow, path.arrowDetail);
+	applyArrowShrinks(commands, arrows.arrowStart ? computeShrink(arrows.arrowStart) : 0, arrows.arrowEnd ? computeShrink(arrows.arrowEnd) : 0, strokeWidth, round);
+	const { primitive } = splitSubPathsForEndpointArrows(commands, baseProps, arrows);
+	return {
+		primitives: [primitive, ...labelPrims],
+		points
+	};
+};
+//#endregion
+export { emitPathPrimitive };

package/dist/es/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/es/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/es/compile/path/label.js

@@ -0,0 +1,102 @@
+//#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
+export { emitLabelPrimitive, tForLabelPosition };

package/dist/es/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/es/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/es/compile/path/relative.js

@@ -0,0 +1,48 @@
+import { arcEndPoint } from "../../geometry/arc.js";
+import { refPointOfTarget } from "./anchor.js";
+//#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 = 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 = refPointOfTarget(resolvedTo, nodeIndex);
+			if (pos) prevEnd = pos;
+		}
+	}
+	return out;
+};
+//#endregion
+export { normalizeRelativeTargets };

package/dist/es/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/es/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/es/compile/path/shrink.js

@@ -0,0 +1,126 @@
+import { shiftToward } from "./anchor.js";
+import { isHollowArrowShape, resolveArrowShapeGeometry } from "./arrow-geometry.js";
+//#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 (!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 = 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, 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 = shiftToward(curPt, prevPt, shrinkEnd * strokeWidth);
+					setEndpoint(commands, lastIdx, shifted, round);
+				}
+			}
+		}
+	}
+};
+//#endregion
+export { applyArrowShrinks, computeShrink, endpointArrows };

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