@retikz/core 0.2.0-alpha.2 → 0.2.0-alpha.4

package/dist/es/shapes/circle.js

@@ -0,0 +1,33 @@
+import { circle as circle$1 } from "../geometry/circle.js";
+import { asRectAnchor } from "./_shared.js";
+import { ellipse } from "./ellipse.js";
+//#region src/shapes/circle.ts
+/** 外接框 Rect → Circle（radius = 半宽；circle 外接框宽=高） */
+var toCircle = (r) => ({
+	x: r.x,
+	y: r.y,
+	radius: r.width / 2,
+	rotate: r.rotate
+});
+/**
+* circle 注册项
+* @description circumscribe = 内框对角线/2（两轴相等）；几何走 circle 数学层；
+*   emit 复用 `ellipse.emit`（circle = rx=ry 的 ellipse），与旧 circle→`emitEllipseShape` 等价
+*/
+var circle = {
+	circumscribe: (hw, hh) => {
+		const r = Math.sqrt(hw * hw + hh * hh);
+		return {
+			halfWidth: r,
+			halfHeight: r
+		};
+	},
+	boundaryPoint: (r, toward) => circle$1.boundaryPoint(toCircle(r), toward),
+	anchor: (r, name) => {
+		const a = asRectAnchor(name);
+		return a ? circle$1.anchor(toCircle(r), a) : void 0;
+	},
+	emit: (r, style, round) => ellipse.emit(r, style, round)
+};
+//#endregion
+export { circle };

package/dist/es/shapes/diamond.d.ts

@@ -0,0 +1,8 @@
+import { ShapeDefinition } from './types';
+/**
+ * diamond 注册项
+ * @description circumscribe = 内框 ×2（内框 4 顶点落在菱形 4 边上）；几何由外接框半轴派生；
+ *   emit 在**轴对齐空间**取 4 顶点出 PathPrim（rotate 由外层 group 施加），与旧 `emitDiamondShape(unrotated(...))` 等价
+ */
+export declare const diamond: ShapeDefinition;
+//# sourceMappingURL=diamond.d.ts.map

package/dist/es/shapes/diamond.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diamond.d.ts","sourceRoot":"","sources":["../../../src/shapes/diamond.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAW/C;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,eA+BrB,CAAC"}

package/dist/es/shapes/diamond.js

@@ -0,0 +1,65 @@
+import { asRectAnchor } from "./_shared.js";
+import { diamond as diamond$1 } from "../geometry/diamond.js";
+//#region src/shapes/diamond.ts
+/** 外接框 Rect → Diamond（halfA/halfB = 半宽/半高；顶点在 ±halfA / ±halfB） */
+var toDiamond = (r) => ({
+	x: r.x,
+	y: r.y,
+	halfA: r.width / 2,
+	halfB: r.height / 2,
+	rotate: r.rotate
+});
+/**
+* diamond 注册项
+* @description circumscribe = 内框 ×2（内框 4 顶点落在菱形 4 边上）；几何由外接框半轴派生；
+*   emit 在**轴对齐空间**取 4 顶点出 PathPrim（rotate 由外层 group 施加），与旧 `emitDiamondShape(unrotated(...))` 等价
+*/
+var diamond = {
+	circumscribe: (hw, hh) => ({
+		halfWidth: hw * 2,
+		halfHeight: hh * 2
+	}),
+	boundaryPoint: (r, toward) => diamond$1.boundaryPoint(toDiamond(r), toward),
+	anchor: (r, name) => {
+		const a = asRectAnchor(name);
+		return a ? diamond$1.anchor(toDiamond(r), a) : void 0;
+	},
+	*emit(r, style, round) {
+		const d = toDiamond(r);
+		const e = diamond$1.anchor(d, "east");
+		const n = diamond$1.anchor(d, "north");
+		const w = diamond$1.anchor(d, "west");
+		const s = diamond$1.anchor(d, "south");
+		yield {
+			type: "path",
+			commands: [
+				{
+					kind: "move",
+					to: [round(e[0]), round(e[1])]
+				},
+				{
+					kind: "line",
+					to: [round(n[0]), round(n[1])]
+				},
+				{
+					kind: "line",
+					to: [round(w[0]), round(w[1])]
+				},
+				{
+					kind: "line",
+					to: [round(s[0]), round(s[1])]
+				},
+				{ kind: "close" }
+			],
+			fill: style.fill ?? "transparent",
+			fillOpacity: style.fillOpacity,
+			stroke: style.stroke ?? "currentColor",
+			strokeOpacity: style.strokeOpacity,
+			strokeWidth: style.strokeWidth ?? 1,
+			dashPattern: style.dashPattern,
+			opacity: style.opacity
+		};
+	}
+};
+//#endregion
+export { diamond };

package/dist/es/shapes/ellipse.d.ts

@@ -0,0 +1,8 @@
+import { ShapeDefinition } from './types';
+/**
+ * ellipse 注册项
+ * @description circumscribe = 内框 ×√2（内框 4 顶点落在椭圆周上）；几何由外接框半轴派生；
+ *   emit 出 EllipsePrim，与旧 `emitEllipseShape` 逐字段等价
+ */
+export declare const ellipse: ShapeDefinition;
+//# sourceMappingURL=ellipse.d.ts.map

package/dist/es/shapes/ellipse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipse.d.ts","sourceRoot":"","sources":["../../../src/shapes/ellipse.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAW/C;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,eAuBrB,CAAC"}

package/dist/es/shapes/ellipse.js

@@ -0,0 +1,45 @@
+import { ellipse as ellipse$1 } from "../geometry/ellipse.js";
+import { asRectAnchor } from "./_shared.js";
+//#region src/shapes/ellipse.ts
+/** 外接框 Rect → Ellipse（rx/ry = 半宽/半高） */
+var toEllipse = (r) => ({
+	x: r.x,
+	y: r.y,
+	rx: r.width / 2,
+	ry: r.height / 2,
+	rotate: r.rotate
+});
+/**
+* ellipse 注册项
+* @description circumscribe = 内框 ×√2（内框 4 顶点落在椭圆周上）；几何由外接框半轴派生；
+*   emit 出 EllipsePrim，与旧 `emitEllipseShape` 逐字段等价
+*/
+var ellipse = {
+	circumscribe: (hw, hh) => ({
+		halfWidth: hw * Math.SQRT2,
+		halfHeight: hh * Math.SQRT2
+	}),
+	boundaryPoint: (r, toward) => ellipse$1.boundaryPoint(toEllipse(r), toward),
+	anchor: (r, name) => {
+		const a = asRectAnchor(name);
+		return a ? ellipse$1.anchor(toEllipse(r), a) : void 0;
+	},
+	*emit(r, style, round) {
+		yield {
+			type: "ellipse",
+			cx: round(r.x),
+			cy: round(r.y),
+			rx: round(r.width / 2),
+			ry: round(r.height / 2),
+			fill: style.fill ?? "transparent",
+			fillOpacity: style.fillOpacity,
+			stroke: style.stroke ?? "currentColor",
+			strokeOpacity: style.strokeOpacity,
+			strokeWidth: style.strokeWidth ?? 1,
+			dashPattern: style.dashPattern,
+			opacity: style.opacity
+		};
+	}
+};
+//#endregion
+export { ellipse };

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

@@ -0,0 +1,14 @@
+import { BuiltinShapeName } from '../ir/node';
+import { circle } from './circle';
+import { diamond } from './diamond';
+import { ellipse } from './ellipse';
+import { rectangle } from './rectangle';
+import { ShapeDefinition } from './types';
+/** 内置 4 shape 注册项；与 `CompileOptions.shapes` 合并时被同名注入覆盖 */
+export declare const BUILTIN_SHAPES: Record<BuiltinShapeName, ShapeDefinition>;
+export { rectangle, circle, ellipse, diamond };
+export type { ShapeDefinition, ShapeStyle } from './types';
+export type { Rect } from '../geometry/rect';
+export type { Position } from '../geometry/point';
+export { worldToLocal, localToWorld } from '../geometry/_transform';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shapes/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,0DAA0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,gBAAgB,EAAE,eAAe,CAKpE,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3D,YAAY,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/es/shapes/index.js

@@ -0,0 +1,15 @@
+import "../geometry/_transform.js";
+import { ellipse } from "./ellipse.js";
+import { circle } from "./circle.js";
+import { diamond } from "./diamond.js";
+import { rectangle } from "./rectangle.js";
+//#region src/shapes/index.ts
+/** 内置 4 shape 注册项；与 `CompileOptions.shapes` 合并时被同名注入覆盖 */
+var BUILTIN_SHAPES = {
+	rectangle,
+	circle,
+	ellipse,
+	diamond
+};
+//#endregion
+export { BUILTIN_SHAPES };

package/dist/es/shapes/rectangle.d.ts

@@ -0,0 +1,8 @@
+import { ShapeDefinition } from './types';
+/**
+ * rectangle 注册项
+ * @description circumscribe = identity（视觉边界 = 内框）；boundaryPoint / anchor 直接走 rect 数学层；
+ *   emit 出 RectPrim（圆角走 cornerRadius），与旧 `emitRectShape` 逐字段等价
+ */
+export declare const rectangle: ShapeDefinition;
+//# sourceMappingURL=rectangle.d.ts.map

package/dist/es/shapes/rectangle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rectangle.d.ts","sourceRoot":"","sources":["../../../src/shapes/rectangle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,eA0BvB,CAAC"}

package/dist/es/shapes/rectangle.js

@@ -0,0 +1,40 @@
+import { rect } from "../geometry/rect.js";
+import { asRectAnchor } from "./_shared.js";
+//#region src/shapes/rectangle.ts
+/**
+* rectangle 注册项
+* @description circumscribe = identity（视觉边界 = 内框）；boundaryPoint / anchor 直接走 rect 数学层；
+*   emit 出 RectPrim（圆角走 cornerRadius），与旧 `emitRectShape` 逐字段等价
+*/
+var rectangle = {
+	circumscribe: (hw, hh) => ({
+		halfWidth: hw,
+		halfHeight: hh
+	}),
+	boundaryPoint: (r, toward) => rect.boundaryPoint(r, toward),
+	anchor: (r, name) => {
+		const a = asRectAnchor(name);
+		return a ? rect.anchor(r, a) : void 0;
+	},
+	*emit(r, style, round) {
+		const halfW = r.width / 2;
+		const halfH = r.height / 2;
+		yield {
+			type: "rect",
+			x: round(r.x - halfW),
+			y: round(r.y - halfH),
+			width: round(r.width),
+			height: round(r.height),
+			fill: style.fill ?? "transparent",
+			fillOpacity: style.fillOpacity,
+			stroke: style.stroke ?? "currentColor",
+			strokeOpacity: style.strokeOpacity,
+			strokeWidth: style.strokeWidth ?? 1,
+			dashPattern: style.dashPattern,
+			cornerRadius: style.roundedCorners,
+			opacity: style.opacity
+		};
+	}
+};
+//#endregion
+export { rectangle };

package/dist/es/shapes/types.d.ts

@@ -0,0 +1,44 @@
+import { Position } from '../geometry/point';
+import { Rect } from '../geometry/rect';
+import { ScenePrimitive } from '../primitive';
+/**
+ * emit 需要的视觉样式子集
+ * @description 从 NodeLayout 的样式字段收敛（不含几何 / 文本）；独立 type，不耦合内部 NodeLayout。
+ *   字段名与 NodeLayout 样式字段一致（单一词汇表）。
+ */
+export type ShapeStyle = {
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeOpacity?: number;
+    strokeWidth?: number;
+    dashPattern?: Array<number>;
+    roundedCorners?: number;
+    opacity?: number;
+};
+/**
+ * 一个 shape 的可注册定义：外接 / 边界 / anchor / emit 四件事
+ * @description plain object（factory 友好：`createPolygonShape(6)` 这类普通函数返回它即可）；含函数、
+ *   **不进 IR**，走 `CompileOptions.shapes` 运行时注入。内置 4 shape 也是注册项（无内置特权）。
+ *
+ *   坐标语义两套，第三方最易写错：
+ *   - `boundaryPoint` / `anchor` 收**带 `rotate` 的 Rect**——用 re-export 的 `worldToLocal` / `localToWorld` 写局部系几何。
+ *   - `emit` 收**轴对齐 Rect（rotate=0）**——旋转由编译器在外层 `GroupPrim` 统一施加。
+ */
+export type ShapeDefinition = {
+    /**
+     * 外接：内容半轴（text + padding）→ 外接框半轴。
+     * @description rectangle: identity；circle: √(hw²+hh²) 两轴相等；ellipse: ×√2；diamond: ×2。
+     */
+    circumscribe: (innerHalfWidth: number, innerHalfHeight: number) => {
+        halfWidth: number;
+        halfHeight: number;
+    };
+    /** 中心 → toward 射线 ∩ 边界（rect 带 rotate）。 */
+    boundaryPoint: (rect: Rect, toward: Position) => Position;
+    /** 命名 anchor 世界坐标；shape 不认识的名字返回 `undefined`（调用方据此抛清晰错误）。 */
+    anchor: (rect: Rect, name: string) => Position | undefined;
+    /** 视觉 primitive，**轴对齐空间**（rotate 由编译器外层 GroupPrim 统一施加）。 */
+    emit: (rect: Rect, style: ShapeStyle, round: (n: number) => number) => Iterable<ScenePrimitive>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/es/shapes/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shapes/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,YAAY,EAAE,CACZ,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,KACpB;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,0CAA0C;IAC1C,aAAa,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,KAAK,QAAQ,CAAC;IAC1D,6DAA6D;IAC7D,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IAC3D,4DAA4D;IAC5D,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAAK,QAAQ,CAAC,cAAc,CAAC,CAAC;CACjG,CAAC"}

package/dist/lib/compile/compile.cjs

@@ -1,10 +1,11 @@
 const require_rect = require("../geometry/rect.cjs");
+const require_index = require("../shapes/index.cjs");
 const require_name_stack = require("./name-stack.cjs");
 const require_scope = require("./scope.cjs");
 const require_position = require("./position.cjs");
 const require_node = require("./node.cjs");
 const require_text_metrics = require("./text-metrics.cjs");
-const require_index = require("./path/index.cjs");
+const require_index$1 = require("./path/index.cjs");
 const require_precision = require("./precision.cjs");
 const require_style = require("./style.cjs");
 const require_layout = require("./layout.cjs");
@@ -16,7 +17,8 @@ const require_layout = require("./layout.cjs");
 */
 var zeroSizeRectAt = (id, [cx, cy]) => ({
 	id,
-	shape: "rectangle",
+	shapeName: "rectangle",
+	shapeDef: require_index.BUILTIN_SHAPES.rectangle,
 	rect: {
 		x: cx,
 		y: cy,
@@ -54,6 +56,18 @@ var defaultWarnDispatcher = (warning) => {
 	if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
 	console.warn(`[retikz] ${warning.code} at ${warning.path}: ${warning.message}`);
 };
+var makePathPlaceholder = () => ({ type: "path-placeholder" });
+/** 把内部 sink 收窄回公开 ScenePrimitive[]：占位已全部回填（compileToScene 末端 placeholderBalance 无条件校验兜底） */
+var sealSink = (sink) => sink;
+/** dev 诊断：递归找出残留占位的 index 路径，供末端无条件校验报错时定位 */
+var collectPlaceholderLocators = (prims, prefix = "primitives") => {
+	const locators = [];
+	prims.forEach((prim, idx) => {
+		if (prim.type === "path-placeholder") locators.push(`${prefix}[${idx}]`);
+		else if (prim.type === "group") locators.push(...collectPlaceholderLocators(prim.children, `${prefix}[${idx}].children`));
+	});
+	return locators;
+};
 /** scope.transforms 解析失败时根据失败成因映射的 warn code */
 var scopeTransformWarnCode = (scope) => {
 	for (const t of scope.transforms ?? []) {
@@ -84,12 +98,44 @@ var compileToScene = (ir, options = {}) => {
 	const round = require_precision.makeRound(options.precision ?? 2);
 	const nodeDistance = options.nodeDistance;
 	const onWarn = options.onWarn ?? defaultWarnDispatcher;
+	const effectiveShapes = options.shapes ? {
+		...require_index.BUILTIN_SHAPES,
+		...options.shapes
+	} : require_index.BUILTIN_SHAPES;
+	if (options.shapes) {
+		for (const name of Object.keys(options.shapes)) if (Object.prototype.hasOwnProperty.call(require_index.BUILTIN_SHAPES, name)) onWarn({
+			code: "SHAPE_OVERRIDES_BUILTIN",
+			message: `Injected shape '${name}' overrides the built-in shape of the same name.`,
+			path: `options.shapes.${name}`
+		});
+	}
 	const primitives = [];
+	/** 已 push 但未回填的占位计数；compileToScene 返回前必须归零（无条件守 Scene 公开契约） */
+	let placeholderBalance = 0;
+	/**
+	* primitive → 显式 zIndex 旁路记录（缺省视为 0）；sealSink 后按它稳定排序，不写进 primitive 本体（保 Scene 输出纯净）。
+	* key 只会是 real ScenePrimitive——占位 PathPlaceholder 永不进此 Map（占位即将被回填替换）。
+	*/
+	const zIndexOf = /* @__PURE__ */ new Map();
+	/**
+	* 按 zIndex 升序原地稳定排序：同 zIndex 保持原 IR 顺序（decorate-sort 带原始下标）。全 0 键 = 恒等。
+	* 仅在 sealSink（占位已回填、类型已收窄回 ScenePrimitive）之后调用。
+	*/
+	const stableSortByZIndex = (arr) => {
+		const decorated = arr.map((prim, index) => ({
+			prim,
+			index,
+			z: zIndexOf.get(prim) ?? 0
+		}));
+		decorated.sort((a, b) => a.z - b.z || a.index - b.index);
+		for (let i = 0; i < arr.length; i++) arr[i] = decorated[i].prim;
+		return arr;
+	};
 	const nameStack = new require_name_stack.NameStack({ onDuplicate: (info) => onWarn(formatDuplicateWarning(info)) });
 	const allPoints = [];
 	/**
 	* 解析一批本层收集的 pending paths（lookup-only 阶段）
-	* @description path primitive 一律 push 到顶层 `primitives` —— 端点已是全局坐标，不能进 GroupPrim 否则被 scope.transform 二次 apply。NameStack 切到 pass2 守门：path 解析中误调 register 抛 internal error；解析完切回 pass1 让上层 scope 子树继续 register 子节点。
+	* @description 两种落点：有 `slot`（scopeChain 为空）→ 原位 splice 回填该 path 在本层 sink 占的位（按引用定位免索引漂移），保住与同层 node 的 IR 声明序；无 `slot`（scopeChain 非空）→ hoist 到顶层 `primitives`，因端点已是全局坐标、进 transformed GroupPrim 会被 scope.transform 二次 apply。NameStack 切到 pass2 守门：path 解析中误调 register 抛 internal error；解析完切回 pass1 让上层 scope 子树继续 register 子节点。
 	*   `item.scopeChain` 记录该 path 所属 scope 累积 transform 链——传给 emitPathPrimitive，
 	*   让 step.to 内的 polar/at/offset 字面量按"当前 scope 局部度量 + 末端 apply chain"投影回全局。
 	*/
@@ -98,15 +144,23 @@ var compileToScene = (ir, options = {}) => {
 		nameStack.enterLookupPhase();
 		try {
 			for (const item of pending) {
-				const result = require_index.emitPathPrimitive(item.path, nameStack, round, measureText, {
+				const result = require_index$1.emitPathPrimitive(item.path, nameStack, round, measureText, {
 					onWarn,
 					irPath: item.irPath,
 					scopeChain: item.scopeChain
 				});
-				if (result) {
-					for (const prim of result.primitives) primitives.push(prim);
-					for (const p of result.points) allPoints.push(p);
+				if (item.slot) {
+					const idx = item.slot.sink.indexOf(item.slot.placeholder);
+					if (idx === -1) throw new Error("internal: path placeholder missing from its sink");
+					const real = result?.primitives ?? [];
+					item.slot.sink.splice(idx, 1, ...real);
+					if (item.zIndex !== void 0) for (const prim of real) zIndexOf.set(prim, item.zIndex);
+					placeholderBalance--;
+				} else if (result) for (const prim of result.primitives) {
+					primitives.push(prim);
+					if (item.zIndex !== void 0) zIndexOf.set(prim, item.zIndex);
 				}
+				if (result) for (const p of result.points) allPoints.push(p);
 			}
 		} finally {
 			nameStack.exitLookupPhase();
@@ -127,10 +181,13 @@ var compileToScene = (ir, options = {}) => {
 		for (let i = 0; i < children.length; i++) {
 			const child = children[i];
 			if (child.type === "node") {
-				const layout = require_node.layoutNode(require_style.resolveNodeStyle(child, styleStack), measureText, nameStack, nodeDistance, chain, require_style.resolveLabelDefault(styleStack));
+				const layout = require_node.layoutNode(require_style.resolveNodeStyle(child, styleStack), measureText, nameStack, nodeDistance, chain, require_style.resolveLabelDefault(styleStack), effectiveShapes);
 				const globalLayout = chain.length === 0 ? layout : require_scope.projectLayoutToGlobal(layout, chain);
 				if (child.id) nameStack.register(child.id, globalLayout, `${locatorPrefix}children[${i}].node.id`);
-				for (const prim of require_node.emitNodePrimitives(layout, round)) sink.push(prim);
+				for (const prim of require_node.emitNodePrimitives(layout, round)) {
+					sink.push(prim);
+					if (child.zIndex !== void 0) zIndexOf.set(prim, child.zIndex);
+				}
 				allPoints.push(require_rect.rect.anchor(globalLayout.rect, "north-west"), require_rect.rect.anchor(globalLayout.rect, "north-east"), require_rect.rect.anchor(globalLayout.rect, "south-west"), require_rect.rect.anchor(globalLayout.rect, "south-east"));
 				layoutsAccumulator.push(globalLayout);
 			} else if (child.type === "coordinate") {
@@ -183,22 +240,40 @@ var compileToScene = (ir, options = {}) => {
 				if (innerSink.length === 0 && !hasOwnTransforms && child.id === void 0) continue;
 				const group = {
 					type: "group",
-					children: innerSink
+					children: stableSortByZIndex(sealSink(innerSink))
 				};
 				if (hasOwnTransforms) group.transforms = [...ownTransforms];
 				sink.push(group);
-			} else pathsAccumulator.push({
-				path: require_style.resolveEffectivePath(child, styleStack),
-				irPath: `${locatorPrefix}children[${i}].path`,
-				scopeChain: chain
-			});
+				if (child.zIndex !== void 0) zIndexOf.set(group, child.zIndex);
+			} else {
+				const pending = {
+					path: require_style.resolveEffectivePath(child, styleStack),
+					irPath: `${locatorPrefix}children[${i}].path`,
+					scopeChain: chain,
+					zIndex: child.zIndex
+				};
+				if (chain.length === 0) {
+					const placeholder = makePathPlaceholder();
+					sink.push(placeholder);
+					pending.slot = {
+						sink,
+						placeholder
+					};
+					placeholderBalance++;
+				}
+				pathsAccumulator.push(pending);
+			}
 		}
 	};
 	const rootPaths = [];
 	processChildren(ir.children, [], primitives, "", [], rootPaths, []);
 	resolvePendingPaths(rootPaths);
+	if (placeholderBalance !== 0) {
+		const detail = typeof process !== "undefined" && process.env.NODE_ENV !== "production" ? ` at ${collectPlaceholderLocators(primitives).join(", ")}` : "";
+		throw new Error(`internal: ${placeholderBalance} unresolved path placeholder(s) leaked into Scene output${detail}`);
+	}
 	return {
-		primitives,
+		primitives: stableSortByZIndex(sealSink(primitives)),
 		layout: require_layout.computeLayout(allPoints, layoutPadding, round)
 	};
 };

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

@@ -1,5 +1,6 @@
 import { IR } from '../ir';
 import { Scene } from '../primitive';
+import { ShapeDefinition } from '../shapes';
 import { TextMeasurer } from './text-metrics';
 /** 编译期警告：path / position 解析失败时通过 `CompileOptions.onWarn` 发出，不影响编译产物 */
 export type CompileWarning = {
@@ -7,7 +8,7 @@ export type CompileWarning = {
      * 警告类型代码（机器可读）
      * @description 用户可按 code 分支处理；未来 alpha 加新 code 不破坏调用方
      */
-    code: 'UNRESOLVED_NODE_REFERENCE' | 'PATH_TOO_SHORT' | 'ANCHOR_RESOLUTION_FAILED' | 'OFFSET_BASE_UNRESOLVED' | 'POLAR_ORIGIN_UNRESOLVED' | 'AT_TARGET_UNRESOLVED' | 'RELATIVE_INITIAL_NO_PREV_END' | 'BBOX_EXTREME_INPUT' | 'DUPLICATE_NODE_ID' | (string & {});
+    code: 'UNRESOLVED_NODE_REFERENCE' | 'PATH_TOO_SHORT' | 'ANCHOR_RESOLUTION_FAILED' | 'OFFSET_BASE_UNRESOLVED' | 'POLAR_ORIGIN_UNRESOLVED' | 'AT_TARGET_UNRESOLVED' | 'RELATIVE_INITIAL_NO_PREV_END' | 'BBOX_EXTREME_INPUT' | 'DUPLICATE_NODE_ID' | 'SHAPE_OVERRIDES_BUILTIN' | (string & {});
     /** 人类可读消息（英文） */
     message: string;
     /** IR locator 路径（jq-like，如 `'children[3].path.children[1].to'`） */
@@ -34,6 +35,12 @@ export type CompileOptions = {
      * @description path / position 解析失败时按 IR locator + code + message 同步触发；不传时 dev 模式（`process.env.NODE_ENV !== 'production'`）默认 `console.warn`、生产静默
      */
     onWarn?: (warning: CompileWarning) => void;
+    /**
+     * 运行时注入的第三方 shape（不进 IR）
+     * @description 有效 shape 表 = `{ ...BUILTIN_SHAPES, ...shapes }`——同名 key 覆盖内置，经 `onWarn` 发
+     *   `SHAPE_OVERRIDES_BUILTIN`。IR 的 `node.shape` 仍是字符串；未注册名在编译期 throw。
+     */
+    shapes?: Record<string, ShapeDefinition>;
 };
 /**
  * IR → Scene 纯函数转换，所有 adapter 共享

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

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAwC,MAAM,OAAO,CAAC;AACtE,OAAO,KAAK,EAAa,KAAK,EAA6B,MAAM,cAAc,CAAC;AAoBhF,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AA2CrE,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,IAAI,EACA,2BAA2B,GAC3B,gBAAgB,GAChB,0BAA0B,GAC1B,wBAAwB,GACxB,yBAAyB,GACzB,sBAAsB,GACtB,8BAA8B,GAC9B,oBAAoB,GACpB,mBAAmB,GACnB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAClB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;CAC5C,CAAC;AAsDF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KA+MrE,CAAC"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAwC,MAAM,OAAO,CAAC;AACtE,OAAO,KAAK,EAAa,KAAK,EAA6B,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAoBjD,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AA4CrE,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,IAAI,EACA,2BAA2B,GAC3B,gBAAgB,GAChB,0BAA0B,GAC1B,wBAAwB,GACxB,yBAAyB,GACzB,sBAAsB,GACtB,8BAA8B,GAC9B,oBAAoB,GACpB,mBAAmB,GACnB,yBAAyB,GACzB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAClB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAC3C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC1C,CAAC;AA6FF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KA4RrE,CAAC"}