@retikz/core 0.2.0-alpha.7 → 0.2.0-alpha.8

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

@@ -1,4 +1,7 @@
+const require_json = require("../../ir/json.cjs");
 const require_rect = require("../../geometry/rect.cjs");
+const require_index = require("../../arrows/index.cjs");
+const require_scope = require("../scope.cjs");
 const require_arc = require("../../geometry/arc.cjs");
 const require_bend = require("../../geometry/bend.cjs");
 const require_segment = require("../../geometry/segment.cjs");
@@ -11,6 +14,46 @@ const require_split = require("./split.cjs");
 //#region src/compile/path/index.ts
 /** 目标若是对象 NodeTarget（`{ id, ... }`）返回其 id，否则 undefined——给 UNRESOLVED_NODE_REFERENCE 诊断用 */
 var nodeRefId = (t) => typeof t === "object" && !Array.isArray(t) && "id" in t ? t.id : void 0;
+/** 有限数 */
+var isFiniteNum = (n) => typeof n === "number" && Number.isFinite(n);
+/** 有限坐标点 `[number, number]` */
+var isFinitePoint = (pt) => Array.isArray(pt) && pt.length >= 2 && isFiniteNum(pt[0]) && isFiniteNum(pt[1]);
+/**
+* 校验 path generator 产出的单条命令合法（kind 已知 + 引用坐标 / 数值有限）
+* @description 第三方 / LLM 写的 generate 误产坏命令（NaN/Infinity 坐标、未知 kind、缺字段、字符串当命令）时
+*   抛含 generator 名的清晰错——守 Scene 100% finite / JSON 可序列化，不放任非 finite 静默入 Scene
+*   （JSON.stringify(NaN/Infinity)=null 会让 round-trip 失真）。
+*/
+var assertValidGeneratedCommand = (name, cmd) => {
+	const bad = (detail) => {
+		throw new Error(`path generator '${name}' produced a ${detail}.`);
+	};
+	if (cmd === null || typeof cmd !== "object") {
+		bad(`non-object command (expected an object with a 'kind')`);
+		return;
+	}
+	const c = cmd;
+	switch (c.kind) {
+		case "move":
+		case "line":
+			if (!isFinitePoint(c.to)) bad(`non-finite coordinate in a '${String(c.kind)}' command`);
+			break;
+		case "quad":
+			if (!isFinitePoint(c.control) || !isFinitePoint(c.to)) bad(`non-finite coordinate in a 'quad' command`);
+			break;
+		case "cubic":
+			if (!isFinitePoint(c.control1) || !isFinitePoint(c.control2) || !isFinitePoint(c.to)) bad(`non-finite coordinate in a 'cubic' command`);
+			break;
+		case "arc":
+			if (!isFinitePoint(c.center) || !isFiniteNum(c.radius) || !isFiniteNum(c.startAngle) || !isFiniteNum(c.endAngle)) bad(`non-finite value in an 'arc' command`);
+			break;
+		case "ellipseArc":
+			if (!isFinitePoint(c.center) || !isFiniteNum(c.radiusX) || !isFiniteNum(c.radiusY) || !isFiniteNum(c.startAngle) || !isFiniteNum(c.endAngle)) bad(`non-finite value in an 'ellipseArc' command`);
+			break;
+		case "close": break;
+		default: bad(`command with unknown kind '${String(c.kind)}'`);
+	}
+};
 /**
 * 语义 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。
@@ -25,6 +68,93 @@ var THICKNESS_TO_WIDTH = {
 	veryThick: 3,
 	ultraThick: 4
 };
+/** 一组点的 axis-aligned 包围盒中心 */
+var bboxCenter = (pts) => {
+	let minX = Infinity;
+	let minY = Infinity;
+	let maxX = -Infinity;
+	let maxY = -Infinity;
+	for (const [x, y] of pts) {
+		if (x < minX) minX = x;
+		if (y < minY) minY = y;
+		if (x > maxX) maxX = x;
+		if (y > maxY) maxY = y;
+	}
+	return [(minX + maxX) / 2, (minY + maxY) / 2];
+};
+/**
+* path 整体 rotate / scale → 绕包围盒中心的 GroupPrim transforms
+* @description rotate 写成 `{ kind:'rotate', degrees, cx, cy }`（cx/cy = bbox center），等价包一个绕同中心旋转的 Scope；
+*   scale number → `{ kind:'scale', x }`（等比，y 省略），`{x,y}` → `{ kind:'scale', x, y }`。
+*   缩放支点同为 bbox center：用 translate(center) ∘ scale ∘ translate(-center) 三段表达。两者都缺时返回空数组。
+*   数组顺序与 GroupPrim 渲染一致（array[0] 最外层、最后 apply）：先 rotate 段再 scale 段（rotate 在外）。
+*/
+var buildPathTransforms = (rotate, scale, center, round) => {
+	const out = [];
+	if (rotate !== void 0) out.push({
+		kind: "rotate",
+		degrees: rotate,
+		cx: round(center[0]),
+		cy: round(center[1])
+	});
+	if (scale !== void 0) {
+		const sx = typeof scale === "number" ? scale : scale.x;
+		const sy = typeof scale === "number" ? void 0 : scale.y;
+		const scaleT = {
+			kind: "scale",
+			x: sx
+		};
+		if (sy !== void 0) scaleT.y = sy;
+		out.push({
+			kind: "translate",
+			x: round(center[0]),
+			y: round(center[1])
+		}, scaleT, {
+			kind: "translate",
+			x: round(-center[0]),
+			y: round(-center[1])
+		});
+	}
+	return out;
+};
+/**
+* 把已物化的 arrow marker（局部 baseSize 坐标系，尖端 +x）按路径切线定向放到采样点
+* @description marker 局部系：viewBox `0 0 baseSize baseSize`，参考点 (refX, baseSize/2)，尖端朝 +x。
+*   GroupPrim transforms 数组语义 array[0] 最外层（最后 apply），故链 = translate(point) ∘ rotate(tangentDeg)
+*   ∘ scale(markerWidth/baseSize, markerHeight/baseSize) ∘ translate(-refX, -baseSize/2)：先把参考点移到原点、
+*   缩放到目标尺寸、绕切线角旋转、平移到采样点。marker 几何（`MarkerPrimitive[]`）是 ScenePrimitive 的结构子集，直接作 children。
+*/
+var buildMarkMarkerGroup = (spec, sample, round) => {
+	const angleDeg = Math.atan2(sample.tangent[1], sample.tangent[0]) * 180 / Math.PI;
+	const sx = spec.markerWidth / spec.baseSize;
+	const sy = spec.markerHeight / spec.baseSize;
+	const refY = spec.baseSize / 2;
+	return {
+		type: "group",
+		transforms: [
+			{
+				kind: "translate",
+				x: round(sample.point[0]),
+				y: round(sample.point[1])
+			},
+			{
+				kind: "rotate",
+				degrees: round(angleDeg)
+			},
+			{
+				kind: "scale",
+				x: round(sx),
+				y: round(sy)
+			},
+			{
+				kind: "translate",
+				x: round(-spec.refX),
+				y: round(-refY)
+			}
+		],
+		children: [...spec.marker]
+	};
+};
 /**
 * 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
@@ -47,15 +177,22 @@ var emitPathPrimitive = (path, nameStack, round, measureText = require_text_metr
 	}
 	/** 每段 step.label 翻译出的 TextPrim（或 sloped 旋转的 group），与 path 主体同级返回 */
 	const labelPrims = [];
-	/** 算 sample 后 emitLabelPrimitive，结果累积到 labelPrims/points */
+	/**
+	* 每个绘制段的几何采样器（按声明序）；中段 marking 用——把整条 path 的 pos∈[0,1] 分摊到 N 段
+	* @description 与 step label 同款便宜模型：N 段等分 pos 区间，pos 落在第 ⌊pos·N⌋ 段、段内参数 = 余数；
+	*   段内 t 的几何含义随段类型（line/step 弧长、curve/cubic/bend Bezier 参数、arc 角度），由各 `*SegmentSample` 决定。
+	*/
+	const segmentSamplers = [];
+	/** 算 sample 后 emitLabelPrimitive，结果累积到 labelPrims/points；同时登记本段采样器供 marks 用 */
 	const collectLabel = (step, sampleAt) => {
+		segmentSamplers.push(sampleAt);
 		if (step.kind === "move" || step.kind === "cycle" || !("label" in step) || !step.label) return;
 		const sample = sampleAt(require_label.tForLabelPosition(step.label.position));
 		const r = require_label.emitLabelPrimitive(step.label, sample, measureText, round, path.opacity);
 		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" && s.kind !== "rectangle";
+	const hasTo = (s) => s.kind !== "cycle" && s.kind !== "arc" && s.kind !== "circlePath" && s.kind !== "ellipsePath" && s.kind !== "rectangle" && s.kind !== "generator";
 	const anchors = steps.map((s, idx) => {
 		if (!hasTo(s)) return null;
 		const ref = require_anchor.refPointOfTarget(s.to, nameStack, scopeChain);
@@ -91,6 +228,12 @@ var emitPathPrimitive = (path, nameStack, round, measureText = require_text_metr
 	* @description 设置 penOverride 让下个绘制段直接用此点当 fromClip 后清空。arc=弧终点；circlePath/ellipsePath=center（"画完留在圆心"）
 	*/
 	let penOverride = null;
+	/**
+	* 读当前游标（生成器分支用）
+	* @description 经函数边界读 `lastEnd`，让 TS 用其声明类型（`IRPosition | null`）而非按分支位置 narrow
+	*   成字面 `null`——generator 分支在源码上位于 lastEnd 各赋值点之前，直接读会被误判恒 null
+	*/
+	const readCursor = () => lastEnd;
 	const roundPoint = (p) => [round(p[0]), round(p[1])];
 	const emitMove = (p) => {
 		const rp = roundPoint(p);
@@ -187,6 +330,72 @@ var emitPathPrimitive = (path, nameStack, round, measureText = require_text_metr
 		}
 		const step = steps[i];
 		if (step.kind === "move") continue;
+		if (step.kind === "generator") {
+			const generators = warnHook.effectivePathGenerators ?? {};
+			const def = Object.prototype.hasOwnProperty.call(generators, step.name) ? generators[step.name] : void 0;
+			if (!def) {
+				const available = Object.keys(generators).sort().join(", ") || "(none registered)";
+				throw new Error(`Unknown path generator '${step.name}'; available: ${available}`);
+			}
+			const parsed = def.paramsSchema.parse(step.params);
+			require_json.JsonObjectSchema.parse(parsed);
+			const paramsObj = parsed;
+			const resolvedTargets = {};
+			for (const key of def.targetParams ?? []) {
+				if (key.includes(".")) continue;
+				const raw = paramsObj[key];
+				if (raw === void 0) continue;
+				if (raw === null || typeof raw !== "string" && typeof raw !== "object") throw new Error(`path generator '${step.name}' targetParams key '${key}' must be a target (node id, coordinate, or target object); got ${raw === null ? "null" : typeof raw}.`);
+				const resolved = require_anchor.refPointOfTarget(raw, nameStack, scopeChain);
+				if (resolved) resolvedTargets[key] = resolved;
+			}
+			const prevGen = findPrev();
+			const fromGen = readCursor() ?? (prevGen ? prevGen.anchor : [0, 0]);
+			const toGen = (step.to !== void 0 ? require_anchor.refPointOfTarget(step.to, nameStack, scopeChain) : null) ?? void 0;
+			let produced;
+			try {
+				produced = def.generate({
+					from: fromGen,
+					...toGen !== void 0 ? { to: toGen } : {},
+					params: paramsObj,
+					resolvedTargets,
+					round
+				});
+			} catch (e) {
+				throw new Error(`path generator '${step.name}' threw: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+			}
+			if (!Array.isArray(produced)) throw new Error(`path generator '${step.name}' must return an array of path commands; got ${produced === null ? "null" : typeof produced}.`);
+			for (const cmd of produced) assertValidGeneratedCommand(step.name, cmd);
+			const generated = produced;
+			startSegment(fromGen);
+			for (const cmd of generated) switch (cmd.kind) {
+				case "move":
+					startSegment(cmd.to);
+					break;
+				case "line":
+					emitLine(cmd.to);
+					break;
+				case "quad":
+					emitQuad(cmd.control, cmd.to);
+					break;
+				case "cubic":
+					emitCubic(cmd.control1, cmd.control2, cmd.to);
+					break;
+				case "arc":
+					emitArc(cmd.center, cmd.radius, cmd.startAngle, cmd.endAngle);
+					break;
+				case "ellipseArc":
+					emitEllipseArc(cmd.center, cmd.radiusX, cmd.radiusY, cmd.startAngle, cmd.endAngle);
+					break;
+				case "close":
+					emitClose();
+					break;
+			}
+			const genEnd = readCursor() ?? fromGen;
+			collectLabel(step, (t) => require_segment.lineSegmentSample(fromGen, genEnd, t));
+			penOverride = readCursor();
+			continue;
+		}
 		if (step.kind === "cycle") {
 			const moveTo = lastMoveTo;
 			const prev = findPrev();
@@ -351,8 +560,8 @@ var emitPathPrimitive = (path, nameStack, round, measureText = require_text_metr
 			continue;
 		}
 		if (step.kind === "bend") {
-			const angle = step.bendAngle ?? 30;
-			const [c1, c2] = require_bend.bendControlPoints(prev.anchor, currAnchor, step.bendDirection, angle);
+			const [c1, c2] = step.outAngle !== void 0 || step.inAngle !== void 0 ? require_bend.outInControlPoints(prev.anchor, currAnchor, step.outAngle ?? 0, step.inAngle ?? 180, step.looseness) : require_bend.bendControlPoints(prev.anchor, currAnchor, step.bendDirection ?? "left", step.bendAngle ?? 30);
+			if (!isFinitePoint(c1) || !isFinitePoint(c2)) throw new Error("Bend produced a non-finite control point (looseness / angle too large); use smaller values.");
 			const fromClip = usedOverride ?? require_anchor.clipForTarget(prev.step.to, c1, nameStack, scopeChain);
 			const toClip = require_anchor.clipForTarget(step.to, c2, nameStack, scopeChain);
 			if (!fromClip || !toClip) return null;
@@ -383,11 +592,50 @@ var emitPathPrimitive = (path, nameStack, round, measureText = require_text_metr
 		fillOpacity: path.fillOpacity,
 		strokeOpacity: path.drawOpacity
 	};
-	const arrows = require_shrink.endpointArrows(path.arrow, path.arrowDetail);
-	require_shrink.applyArrowShrinks(commands, arrows.arrowStart ? require_shrink.computeShrink(arrows.arrowStart) : 0, arrows.arrowEnd ? require_shrink.computeShrink(arrows.arrowEnd) : 0, strokeWidth, round);
-	const { primitive } = require_split.splitSubPathsForEndpointArrows(commands, baseProps, arrows);
+	const effectiveArrows = warnHook.effectiveArrows ?? require_index.BUILTIN_ARROWS;
+	const arrows = require_shrink.endpointArrows(path.arrow, path.arrowDetail, effectiveArrows, round);
+	const markPrims = [];
+	if (path.marks && path.marks.length > 0 && segmentSamplers.length > 0) {
+		const segCount = segmentSamplers.length;
+		for (const { pos, mark } of path.marks) {
+			const scaled = pos * segCount;
+			const segIdx = Math.min(Math.floor(scaled), segCount - 1);
+			const localT = scaled - segIdx;
+			const sample = segmentSamplers[segIdx](pos === 1 ? 1 : localT);
+			const spec = require_shrink.resolveMarkArrowSpec(mark, effectiveArrows, round);
+			markPrims.push(buildMarkMarkerGroup(spec, sample, round));
+			points.push(sample.point);
+		}
+	}
+	require_shrink.applyArrowShrinks(commands, arrows.shrinkStart, arrows.shrinkEnd, strokeWidth, round);
+	const endpointSpecs = {};
+	if (arrows.arrowStart) endpointSpecs.arrowStart = arrows.arrowStart;
+	if (arrows.arrowEnd) endpointSpecs.arrowEnd = arrows.arrowEnd;
+	const { primitive } = require_split.splitSubPathsForEndpointArrows(commands, baseProps, endpointSpecs);
+	const bodyPrims = [
+		primitive,
+		...labelPrims,
+		...markPrims
+	];
+	if ((path.rotate !== void 0 || path.scale !== void 0) && points.length > 0) {
+		const center = bboxCenter(points);
+		const transforms = buildPathTransforms(path.rotate, path.scale, center, round);
+		if (transforms.length > 0) {
+			const group = {
+				type: "group",
+				transforms,
+				children: bodyPrims
+			};
+			const transformedPoints = points.map((p) => require_scope.applyTransformChain(p, transforms));
+			if (!transformedPoints.every(isFinitePoint)) throw new Error("Path rotate / scale produced a non-finite coordinate (scale too large); use a smaller scale.");
+			return {
+				primitives: [group],
+				points: transformedPoints
+			};
+		}
+	}
 	return {
-		primitives: [primitive, ...labelPrims],
+		primitives: bodyPrims,
 		points
 	};
 };

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

@@ -1,8 +1,10 @@
 import { PaintResolver } from '../paint';
 import { IRPath, IRPosition } from '../../ir';
 import { ScenePrimitive, Transform } from '../../primitive';
+import { PathGeneratorDefinition } from '../../pathGenerators';
 import { NameStack } from '../name-stack';
 import { TextMeasurer } from '../text-metrics';
+import { EffectiveArrows } from './shrink';
 /** emitPathPrimitive 可选 warn 钩子 */
 export type EmitPathWarnHook = {
     /** 警告收集器（由 compileToScene 传入） */
@@ -21,6 +23,19 @@ export type EmitPathWarnHook = {
     scopeChain?: ReadonlyArray<Transform>;
     /** fill 解析器（PaintSpec → resourceRef + 登记资源）；缺省时纯色透传、PaintSpec 退化为无填充 */
     resolveFill?: PaintResolver;
+    /**
+     * 有效 arrow 表（内置 7 + 注入）；缺省 = 仅内置 7
+     * @description compileToScene 合并 `{ ...BUILTIN_ARROWS, ...options.arrows }` 传入；
+     *   endpointArrows 据此查表算 shrink / 调 def.emit；未注册名编译期 throw
+     */
+    effectiveArrows?: EffectiveArrows;
+    /**
+     * 有效 path generator 表（注入即全部，core 无内置）；缺省 = 空表
+     * @description compileToScene 传 `options.pathGenerators ?? {}`；generator step 据此查表（未注册名
+     *   编译期 throw，错误列出可用名）→ 双 parse 护栏 → targetParams resolve → 调 generate splice 命令。
+     *   解析逻辑由后续实现落地（此处仅声明 hook 入口）。
+     */
+    effectivePathGenerators?: Record<string, PathGeneratorDefinition>;
 };
 /**
  * IR Path → PathPrim

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAY9C,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EAGX,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAEV,cAAc,EACd,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AAkCtE,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;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC,wEAAwE;IACxE,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,SAAS,EACpB,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,IAqhBrE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAY9C,OAAO,KAAK,EACV,MAAM,EAEN,UAAU,EAGX,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAIV,cAAc,EACd,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AAKtE,OAAO,EAAE,KAAK,eAAe,EAA2D,MAAM,UAAU,CAAC;AAsFzG,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;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC,wEAAwE;IACxE,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CACnE,CAAC;AA0EF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,SAAS,EACpB,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,IA0tBrE,CAAC"}

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

@@ -32,6 +32,14 @@ var normalizeRelativeTargets = (steps, nameStack, scopeChain = []) => {
 			out.push(step);
 			continue;
 		}
+		if (step.kind === "generator") {
+			out.push(step);
+			if (step.to !== void 0) {
+				const pos = require_anchor.refPointOfTarget(step.to, nameStack, scopeChain);
+				if (pos) prevEnd = pos;
+			}
+			continue;
+		}
 		const original = step.to;
 		let resolvedTo = original;
 		let updatePrevEnd = true;

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

@@ -1 +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,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,KAAK,CAAC,MAAM,CA6Ed,CAAC"}
+{"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,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,KAAK,CAAC,MAAM,CAuFd,CAAC"}

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

@@ -1,12 +1,21 @@
 const require_arrow = require("../../ir/path/arrow.cjs");
+const require_marker_prim = require("../marker-prim.cjs");
 const require_anchor = require("./anchor.cjs");
-const require_arrow_geometry = require("./arrow-geometry.cjs");
 //#region src/compile/path/shrink.ts
+/** 默认 baseSize（marker 局部基准边长，viewBox `0 0 baseSize baseSize`） */
+var ARROW_GEOMETRY_BASE_SIZE = 10;
+/** 查 effective 表取 def；未注册名编译期 throw（消息含字母序可用名列表） */
+var lookupArrowDef = (shape, effective) => {
+	if (Object.prototype.hasOwnProperty.call(effective, shape)) return effective[shape];
+	const available = Object.keys(effective).sort().join(", ");
+	throw new Error(`Unknown arrow shape '${shape}'; available: ${available}`);
+};
 /**
-* 端点级 spec：顶层默认 ⊕ end-side override（逐字段 merge）
-* @description 缺省字段继承顶层（不是"完全替换"）；空心 shape 上 fill 字段被丢（silent no-op）
+* 端点级视觉输入：顶层默认 ⊕ end-side override（逐字段 merge）
+* @description 缺省字段继承顶层（不是"完全替换"）；空心 def 上 fill 字段被丢（silent no-op）。
+*   产 compile-internal 中间体，供 shrink + emit 消费。
 */
-var resolveArrowEndSpec = (topLevel, endSide) => {
+var resolveArrowVisual = (topLevel, endSide, effective) => {
 	const baseShape = endSide?.shape ?? topLevel.shape ?? require_arrow.DEFAULT_ARROW_SHAPE;
 	const out = { shape: baseShape };
 	const scale = endSide?.scale ?? topLevel.scale;
@@ -21,35 +30,148 @@ var resolveArrowEndSpec = (topLevel, endSide) => {
 	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)) {
+	if (!lookupArrowDef(baseShape, effective).hollow) {
 		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
-		};
+/**
+* 校验 def 几何字段有限（baseSize 还须 > 0）
+* @description 第三方 / LLM 写出的 def 可能漏字段或塞 NaN / Infinity / 0 baseSize；这些数会经 shrink 公式
+*   污染 path 本体坐标（非仅 marker），故在此抛清晰错（含 shape 名，便于自修），不放任 NaN 静默流出。
+*/
+var assertFiniteGeometry = (shape, def) => {
+	if (!Number.isFinite(def.lineContactX)) throw new Error(`Arrow '${shape}' has a non-finite lineContactX (${String(def.lineContactX)}); it must be a finite number.`);
+	if (def.baseSize !== void 0 && (!Number.isFinite(def.baseSize) || def.baseSize <= 0)) throw new Error(`Arrow '${shape}' has an invalid baseSize (${String(def.baseSize)}); it must be a finite number greater than 0.`);
+	if (def.tipX !== void 0 && !Number.isFinite(def.tipX)) throw new Error(`Arrow '${shape}' has a non-finite tipX (${String(def.tipX)}); it must be a finite number.`);
+};
+/**
+* 调 def.emit 收集 marker 并跑窄子集 + JSON-safe 校验
+* @description emit 缺失 / 非函数 / 抛错 / 返回非 iterable 都包成含 shape 名的清晰错（便于第三方 / LLM 自修），
+*   不泄漏内部变量名；产物逐个过共享 `validateMarkerPrimitives`（窄子集 + 深度无函数检查，与 pattern motif 同套）。
+*/
+var callEmit = (shape, def, ctx) => {
+	if (typeof def.emit !== "function") throw new Error(`Arrow '${shape}' is missing an emit function (ArrowDefinition.emit is required).`);
+	let marker;
+	try {
+		marker = [...def.emit(ctx)];
+	} catch (e) {
+		throw new Error(`Arrow '${shape}' emit failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
 	}
+	require_marker_prim.validateMarkerPrimitives(`Arrow '${shape}'`, marker);
+	return marker;
+};
+/** 据 def + 视觉输入解析端点几何（baseSize / tipX / contactX / resolved length·width） */
+var resolveGeometry = (visual, effective) => {
+	const def = lookupArrowDef(visual.shape, effective);
+	assertFiniteGeometry(visual.shape, def);
+	const baseSize = def.baseSize ?? ARROW_GEOMETRY_BASE_SIZE;
+	const tipX = def.tipX ?? baseSize;
+	const lineWidth = visual.lineWidth ?? 1.5;
+	const contactX = def.hollow ? def.lineContactX - lineWidth / 2 : def.lineContactX;
+	const scale = visual.scale ?? 1;
+	const resolvedLength = (visual.length ?? def.defaultLength ?? 6) * scale;
+	const resolvedWidth = (visual.width ?? def.defaultWidth ?? 6) * scale;
+	if (!Number.isFinite(resolvedLength) || !Number.isFinite(resolvedWidth)) throw new Error(`Arrow '${visual.shape}' resolved length/width is non-finite (length × scale overflowed); use smaller length / scale values.`);
+	return {
+		def,
+		baseSize,
+		tipX,
+		contactX,
+		lineWidth,
+		resolvedLength,
+		resolvedWidth
+	};
 };
 /**
 * 端点级 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;
+var computeShrink = (geometry) => (geometry.tipX - geometry.contactX) * geometry.resolvedLength / geometry.baseSize;
+/**
+* 据 def + 解析后视觉输入构 `ArrowEmitContext`
+* @description hollow def：fill 丢（neutral）、stroke = color override ?? contextStroke、lineWidth 启用；
+*   solid def：fill = fill ?? color ?? contextStroke、stroke = color ?? contextStroke。
+*/
+var buildEmitContext = (visual, geometry, round) => {
+	const contextStroke = { kind: "contextStroke" };
+	return {
+		stroke: visual.color ?? contextStroke,
+		fill: geometry.def.hollow ? contextStroke : visual.fill ?? visual.color ?? contextStroke,
+		lineWidth: geometry.lineWidth,
+		round
+	};
+};
+/**
+* 把视觉中间体物化成最终 `ArrowEndSpec`（已解析 marker 描述）
+* @description 构 `ArrowEmitContext` → 调 `def.emit` 收集 `MarkerPrimitive[]`，并算 baseSize /
+*   refX（hollow 减 lineWidth/2）/ markerWidth = 解析 length / markerHeight = 解析 width / opacity 透传。
+*/
+var materializeArrowEndSpec = (visual, geometry, round) => {
+	const ctx = buildEmitContext(visual, geometry, round);
+	const marker = callEmit(visual.shape, geometry.def, ctx);
+	const out = {
+		shape: visual.shape,
+		baseSize: geometry.baseSize,
+		refX: geometry.contactX,
+		markerWidth: geometry.resolvedLength,
+		markerHeight: geometry.resolvedWidth,
+		marker
+	};
+	if (visual.opacity !== void 0) out.opacity = visual.opacity;
+	return out;
+};
+/**
+* IR path-level `arrow` + `arrowDetail` → PathPrim 起末端点已解析 marker 描述
+* @description merge 视觉输入 → 查 effective 表 + 解析几何 → 算 shrink → 调 def.emit 物化最终 `ArrowEndSpec`。
+*   返回同时带 compile-internal 的 shrink 量（端点收缩在 compile 落，与 emit 落点无关）。
+*   未注册 shape 名在此 throw（lookupArrowDef）。
+*/
+var endpointArrows = (arrow, detail, effective, round) => {
+	if (!arrow || arrow === "none") return {
+		shrinkStart: 0,
+		shrinkEnd: 0
+	};
+	const top = detail ?? {};
+	const wantStart = arrow === "<-" || arrow === "<->";
+	const wantEnd = arrow === "->" || arrow === "<->";
+	const result = {
+		shrinkStart: 0,
+		shrinkEnd: 0
+	};
+	if (wantStart) {
+		const visual = resolveArrowVisual(top, top.start, effective);
+		const geometry = resolveGeometry(visual, effective);
+		result.arrowStart = materializeArrowEndSpec(visual, geometry, round);
+		result.shrinkStart = computeShrink(geometry);
+	}
+	if (wantEnd) {
+		const visual = resolveArrowVisual(top, top.end, effective);
+		const geometry = resolveGeometry(visual, effective);
+		result.arrowEnd = materializeArrowEndSpec(visual, geometry, round);
+		result.shrinkEnd = computeShrink(geometry);
+	}
+	return result;
+};
+/**
+* 解析一个中段标记 `IRArrowMark` 为已物化的 marker 描述（`ArrowEndSpec`）
+* @description 复用端点箭头同一管线：mark 自身视觉子集字段（shape / scale / length / width / color /
+*   fill / opacity / lineWidth）即 `ResolvedArrowVisual`（空心 def 上 fill 字段被丢）→ 查 effective 表
+*   解析几何 → 调 def.emit 物化局部 baseSize 几何 + wrapper 参数。方向由调用方按路径切线决定，本函数不含定向。
+*   未注册 shape 名在此 throw（lookupArrowDef）。
+*/
+var resolveMarkArrowSpec = (mark, effective, round) => {
+	const baseShape = mark.shape ?? require_arrow.DEFAULT_ARROW_SHAPE;
+	const visual = { shape: baseShape };
+	if (mark.scale !== void 0) visual.scale = mark.scale;
+	if (mark.length !== void 0) visual.length = mark.length;
+	if (mark.width !== void 0) visual.width = mark.width;
+	if (mark.color !== void 0) visual.color = mark.color;
+	if (mark.opacity !== void 0) visual.opacity = mark.opacity;
+	if (mark.lineWidth !== void 0) visual.lineWidth = mark.lineWidth;
+	if (!lookupArrowDef(baseShape, effective).hollow && mark.fill !== void 0) visual.fill = mark.fill;
+	return materializeArrowEndSpec(visual, resolveGeometry(visual, effective), round);
 };
 /** 取一个 PathCommand 末端 endpoint（move/line/quad/cubic → to；arc/ellipseArc → polar(end)；close 无端点） */
 var endpointOf = (cmd) => {
@@ -92,7 +214,7 @@ var setEndpoint = (commands, idx, newPt, round) => {
 * @description 让 line 端点接在 hollow arrow 尾部外缘、不贯穿 back outline；shrink=0 的实心 shape 跳过。in-place 改写 commands 数组
 */
 var applyArrowShrinks = (commands, shrinkStart, shrinkEnd, strokeWidth, round) => {
-	if (shrinkStart > 0) {
+	if (shrinkStart !== 0) {
 		const firstIdx = commands.findIndex((o) => o.kind === "move");
 		if (firstIdx >= 0) {
 			const cur = commands[firstIdx];
@@ -103,7 +225,7 @@ var applyArrowShrinks = (commands, shrinkStart, shrinkEnd, strokeWidth, round) =
 			}
 		}
 	}
-	if (shrinkEnd > 0) {
+	if (shrinkEnd !== 0) {
 		let lastIdx = -1;
 		for (let i = commands.length - 1; i >= 0; i--) if (commands[i].kind !== "close") {
 			lastIdx = i;
@@ -125,5 +247,5 @@ var applyArrowShrinks = (commands, shrinkStart, shrinkEnd, strokeWidth, round) =
 };
 //#endregion
 exports.applyArrowShrinks = applyArrowShrinks;
-exports.computeShrink = computeShrink;
 exports.endpointArrows = endpointArrows;
+exports.resolveMarkArrowSpec = resolveMarkArrowSpec;

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

@@ -1,15 +1,28 @@
-import { IRArrowDetail } from '../../ir';
+import { IRArrowDetail, IRArrowMark } from '../../ir';
+import { ArrowDefinition } from '../../arrows';
 import { ArrowEndSpec, PathCommand } from '../../primitive';
-/** IR path-level `arrow` + `arrowDetail` → PathPrim 起末端点箭头规格 */
-export declare const endpointArrows: (arrow: "none" | "->" | "<-" | "<->" | undefined, detail: IRArrowDetail | undefined) => {
+/** 有效 arrow 表：内置 7 + 注入（同名注入覆盖内置） */
+export type EffectiveArrows = Record<string, ArrowDefinition>;
+/**
+ * IR path-level `arrow` + `arrowDetail` → PathPrim 起末端点已解析 marker 描述
+ * @description merge 视觉输入 → 查 effective 表 + 解析几何 → 算 shrink → 调 def.emit 物化最终 `ArrowEndSpec`。
+ *   返回同时带 compile-internal 的 shrink 量（端点收缩在 compile 落，与 emit 落点无关）。
+ *   未注册 shape 名在此 throw（lookupArrowDef）。
+ */
+export declare const endpointArrows: (arrow: "none" | "->" | "<-" | "<->" | undefined, detail: IRArrowDetail | undefined, effective: EffectiveArrows, round: (n: number) => number) => {
     arrowStart?: ArrowEndSpec;
     arrowEnd?: ArrowEndSpec;
+    shrinkStart: number;
+    shrinkEnd: number;
 };
 /**
- * 端点级 shrink（strokeWidth 倍）：line 末端朝起点缩这么多，让箭头尖端落回原 target
- * @description 不分实心 / 空心：路径端点接在箭头尾部或凹口，箭头尖端仍贴原 target。低 opacity 下不会再透出 line。
+ * 解析一个中段标记 `IRArrowMark` 为已物化的 marker 描述（`ArrowEndSpec`）
+ * @description 复用端点箭头同一管线：mark 自身视觉子集字段（shape / scale / length / width / color /
+ *   fill / opacity / lineWidth）即 `ResolvedArrowVisual`（空心 def 上 fill 字段被丢）→ 查 effective 表
+ *   解析几何 → 调 def.emit 物化局部 baseSize 几何 + wrapper 参数。方向由调用方按路径切线决定，本函数不含定向。
+ *   未注册 shape 名在此 throw（lookupArrowDef）。
  */
-export declare const computeShrink: (spec: ArrowEndSpec) => number;
+export declare const resolveMarkArrowSpec: (mark: IRArrowMark, effective: EffectiveArrows, round: (n: number) => number) => ArrowEndSpec;
 /**
  * 按 shape + spec（length / scale / lineWidth）把首/末段端点向内缩短
  * @description 让 line 端点接在 hollow arrow 尾部外缘、不贯穿 back outline；shrink=0 的实心 shape 跳过。in-place 改写 commands 数组

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

@@ -1 +1 @@
-{"version":3,"file":"shrink.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/shrink.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAA0C,MAAM,UAAU,CAAC;AAC3G,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"}
+{"version":3,"file":"shrink.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/shrink.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAElB,KAAK,WAAW,EAEjB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAA+B,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAI9F,qCAAqC;AACrC,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAwM9D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,SAAS,EAC/C,QAAQ,aAAa,GAAG,SAAS,EACjC,WAAW,eAAe,EAC1B,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B;IACD,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CAyBnB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,WAAW,EACjB,WAAW,eAAe,EAC1B,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,YAaF,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"}