@retikz/core 0.3.0-alpha.4 → 0.3.0-beta.1

package/dist/lib/compile/compile.cjs

@@ -2,7 +2,8 @@ const require_rect = require("../geometry/rect.cjs");
 const require_index = require("../shapes/index.cjs");
 const require_index$1 = require("../arrows/index.cjs");
 const require_index$2 = require("../patterns/index.cjs");
-const require_lowerComposites = require("./lowerComposites.cjs");
+const require_constant = require("./constant.cjs");
+const require_composite = require("./composite.cjs");
 const require_name_stack = require("./name-stack.cjs");
 const require_scope = require("./scope.cjs");
 const require_position = require("./position.cjs");
@@ -21,10 +22,10 @@ const require_layout = require("./layout.cjs");
 * @description coordinate / scope.id 入场临时占位等"无形状只有位置"句柄共享此结构，
 *   让后续 path target / `at.of` / `offset.of` / `polar.origin` 引用时 boundaryPoint 命中中心。
 */
-var zeroSizeRectAt = (id, [cx, cy]) => ({
+var zeroSizeRectAt = (id, [cx, cy], shapes) => ({
 	id,
 	shapeName: "rectangle",
-	shapeDef: require_index.BUILTIN_SHAPES.rectangle,
+	shapeDef: shapes.rectangle,
 	rect: {
 		x: cx,
 		y: cy,
@@ -39,21 +40,21 @@ var zeroSizeRectAt = (id, [cx, cy]) => ({
 	align: "middle",
 	lineHeight: 0,
 	fontSize: 0,
-	shapes: require_index.BUILTIN_SHAPES
+	shapes
 });
 /**
 * 把 coordinate 注册成 0×0 NodeLayout
 * @description 让后续 path target / `at.of` 引用时 boundaryPoint 命中中心，符合"占位无形状边界"语义
 */
-var coordinateAsLayout = (id, center) => zeroSizeRectAt(id, center);
+var coordinateAsLayout = (id, center, shapes) => zeroSizeRectAt(id, center, shapes);
 /**
 * scope.id 入场时的临时占位 NodeLayout
 * @description scope 子树尚未处理时先放 0×0 占位（落在 scope 局部原点经累积 chain 投到全局的位置），
 *   让 scope 子树内任何 lookup 不返回 undefined（占位语义自洽）。
 *   子树 Pass 1 处理完毕后由 `registerScopeAsLayout` 算出真 bbox layout 覆盖此占位（NameStack.replaceLayout 不发 duplicate warn）
 */
-var scopePlaceholderLayout = (id, chain) => {
-	return zeroSizeRectAt(id, chain.length === 0 ? [0, 0] : require_scope.applyTransformChain([0, 0], chain));
+var scopePlaceholderLayout = (id, chain, shapes) => {
+	return zeroSizeRectAt(id, chain.length === 0 ? [0, 0] : require_scope.applyTransformChain([0, 0], chain), shapes);
 };
 /**
 * 显式 viewBox → Scene.layout（finite 守卫 + round）
@@ -93,7 +94,27 @@ var assertFiniteLayout = (layout) => {
 */
 var defaultWarnDispatcher = (warning) => {
 	if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
-	console.warn(`[retikz] ${warning.code} at ${warning.path}: ${warning.message}`);
+	console.warn(require_constant.formatCompileWarning(warning));
+};
+/**
+* 校验 animation tracks 的 viewBox⇔根 约束（schema 上下文无关、分不清元素 vs 根，故在此 compile 层做）
+* @description `viewBox`（镜头）只在 scene 根合法、元素级非法；scene 根只接受 `viewBox`。违例 track → `warn(ANIMATION_INVALID_PROPERTY)` + drop（不丢图、不影响其余 track）。全空返回 undefined（不 stamp 空数组）。
+*/
+var filterAnimations = (tracks, context, onWarn, irPath) => {
+	if (tracks === void 0) return void 0;
+	const kept = tracks.filter((track, index) => {
+		const isViewBox = track.property === "viewBox";
+		if (!(context === "root" ? isViewBox : !isViewBox)) {
+			onWarn({
+				code: require_constant.CompileWarningCode.AnimationInvalidProperty,
+				message: context === "root" ? `Scene-root animation must use the "viewBox" property (camera); got "${track.property}". Track dropped.` : `Animation property "viewBox" is camera-only (scene root), not valid on an element. Track dropped.`,
+				path: `${irPath}.animations[${index}]`
+			});
+			return false;
+		}
+		return true;
+	});
+	return kept.length > 0 ? kept : void 0;
 };
 var makePathPlaceholder = () => ({ type: "path-placeholder" });
 /** 把内部 sink 收窄回公开 ScenePrimitive[]：占位已全部回填（compileToScene 末端 placeholderBalance 无条件校验兜底） */
@@ -110,11 +131,12 @@ var collectPlaceholderLocators = (prims, prefix = "primitives") => {
 /** scope.transforms 解析失败时根据失败成因映射的 warn code */
 var scopeTransformWarnCode = (scope) => {
 	for (const t of scope.transforms ?? []) {
-		if (t.kind === "offset-translate") return "OFFSET_BASE_UNRESOLVED";
-		if (t.kind === "at-translate") return "AT_TARGET_UNRESOLVED";
-		if (t.kind === "polar-translate") return "POLAR_ORIGIN_UNRESOLVED";
+		if (t.kind === "offset-translate") return require_constant.CompileWarningCode.OffsetBaseUnresolved;
+		if (t.kind === "at-translate") return require_constant.CompileWarningCode.AtTargetUnresolved;
+		if (t.kind === "polar-translate") return require_constant.CompileWarningCode.PolarOriginUnresolved;
+		if (t.kind === "between-translate") return require_constant.CompileWarningCode.UnresolvedNodeReference;
 	}
-	return "UNRESOLVED_NODE_REFERENCE";
+	return require_constant.CompileWarningCode.UnresolvedNodeReference;
 };
 /** 把 DuplicateRegisterInfo 翻成 CompileWarning（含可读 message + 双 IR locator） */
 var formatDuplicateWarning = (info) => {
@@ -122,22 +144,22 @@ var formatDuplicateWarning = (info) => {
 	const firstLoc = info.firstIrPath ?? "(unknown earlier location)";
 	const secondLoc = info.secondIrPath ?? "(unknown current location)";
 	return {
-		code: "DUPLICATE_NODE_ID",
+		code: require_constant.CompileWarningCode.DuplicateNodeId,
 		message: `Duplicate id '${info.id}' registered in the same namespace frame (${frameNote}); first defined at ${firstLoc}, redefined at ${secondLoc}. The later definition overrides the earlier one (last-wins).`,
 		path: secondLoc
 	};
 };
 /**
 * IR → Scene 纯函数转换，所有 adapter 共享
-* @description Pass 1 递归处理 node / coordinate / scope，把 scope 树下沉为嵌套 GroupPrim；scope.transforms 中的 4 种 translate 变体按 lowerScopeTransforms 展平为 Cartesian transform；node 在 Scene primitive 树里是局部坐标 + GroupPrim transform 链、在 NameStack 中存全局坐标供其他节点 / path 引用。NameStack 用栈式 frame 管理命名空间：默认全局扁平、`<Scope localNamespace>` 推入子 frame；scope.id 始终在父 frame 注册（外部句柄）；id lookup 从栈顶向栈底 inside-out 搜索；同 frame 重复 id 触发 DUPLICATE_NODE_ID warn + 后定义覆盖前定义。Pass 2 解析 path 端点写 d 字符串，path primitive 发到 Pass 1 记录的对应容器；末端按 precision 折算 layout
+* @description Pass 1 递归处理 node / coordinate / scope，把 scope 树下沉为嵌套 GroupPrim；scope.transforms 中的 5 种 translate 变体按 lowerScopeTransforms 展平为 Cartesian transform；node 在 Scene primitive 树里是局部坐标 + GroupPrim transform 链、在 NameStack 中存全局坐标供其他节点 / path 引用。NameStack 用栈式 frame 管理命名空间：默认全局扁平、`<Scope localNamespace>` 推入子 frame；scope.id 始终在父 frame 注册（外部句柄）；id lookup 从栈顶向栈底 inside-out 搜索；同 frame 重复 id 触发 DUPLICATE_NODE_ID warn + 后定义覆盖前定义。Pass 2 解析 path 端点写 d 字符串，path primitive 发到 Pass 1 记录的对应容器；末端按 precision 折算 layout
 */
 var compileToScene = (ir, options = {}) => {
 	const measureText = options.measureText ?? require_text_metrics.fallbackMeasurer;
 	const layoutPadding = options.padding ?? 10;
-	const round = require_precision.makeRound(options.precision ?? 2);
+	const round = require_precision.createRound(options.precision ?? 2);
 	const nodeDistance = options.nodeDistance;
 	const onWarn = options.onWarn ?? defaultWarnDispatcher;
-	const loweredIr = require_lowerComposites.lowerComposites(ir, options.composites ?? [], {
+	const loweredIr = require_composite.lowerComposites(ir, options.composites ?? [], {
 		onWarn,
 		maxDepth: options.maxCompositeDepth
 	});
@@ -147,7 +169,7 @@ var compileToScene = (ir, options = {}) => {
 	} : 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",
+			code: require_constant.CompileWarningCode.ShapeOverridesBuiltin,
 			message: `Injected shape '${name}' overrides the built-in shape of the same name.`,
 			path: `options.shapes.${name}`
 		});
@@ -159,7 +181,7 @@ var compileToScene = (ir, options = {}) => {
 	} : require_index$1.BUILTIN_ARROWS;
 	if (options.arrows) {
 		for (const name of Object.keys(options.arrows)) if (Object.prototype.hasOwnProperty.call(require_index$1.BUILTIN_ARROWS, name)) onWarn({
-			code: "ARROW_OVERRIDES_BUILTIN",
+			code: require_constant.CompileWarningCode.ArrowOverridesBuiltin,
 			message: `Injected arrow '${name}' overrides the built-in arrow of the same name.`,
 			path: `options.arrows.${name}`
 		});
@@ -170,7 +192,7 @@ var compileToScene = (ir, options = {}) => {
 	} : require_index$2.BUILTIN_PATTERNS;
 	if (options.patterns) {
 		for (const name of Object.keys(options.patterns)) if (Object.prototype.hasOwnProperty.call(require_index$2.BUILTIN_PATTERNS, name)) onWarn({
-			code: "PATTERN_OVERRIDES_BUILTIN",
+			code: require_constant.CompileWarningCode.PatternOverridesBuiltin,
 			message: `Injected pattern '${name}' overrides the built-in pattern of the same name.`,
 			path: `options.patterns.${name}`
 		});
@@ -239,7 +261,7 @@ var compileToScene = (ir, options = {}) => {
 	};
 	/**
 	* 递归处理一组 IR child，把 node / coordinate 发到 sink、把本层 path 收集到 pathsAccumulator、scope 下沉为 GroupPrim
-	* @description **不**在内部 resolve pathsAccumulator——调用方负责在合适时机（scope 入口：bbox replaceLayout 之后 / popFrame 之前；顶层：所有处理结束后）调用 resolvePendingPaths。这样 scope.id 的 placeholder→real bbox 替换在本层 path 端点 lookup 之前完成，避免 "scope 内 path 自引用本 scope.id 拿到 placeholder" 的 latent bug，同时保留 ADR-02 的 "本层 path 在本层 frame 还在栈顶时 resolve" inside-out lookup 语义。
+	* @description **不**在内部 resolve pathsAccumulator——调用方负责在合适时机（scope 入口：bbox replaceLayout 之后 / popFrame 之前；顶层：所有处理结束后）调用 resolvePendingPaths。这样 scope.id 的 placeholder→real bbox 替换在本层 path 端点 lookup 之前完成，避免 "scope 内 path 自引用本 scope.id 拿到 placeholder" 的 latent bug，同时保留"本层 path 在本层 frame 还在栈顶时 resolve"的 inside-out lookup 语义。
 	* @param children 当前层级的 IR child 数组
 	* @param chain 从根到当前层级累积的 Cartesian-only transform 链
 	* @param sink 当前层级 Scene primitive 落点（顶层 = primitives，scope 内 = GroupPrim.children）
@@ -253,41 +275,43 @@ var compileToScene = (ir, options = {}) => {
 			const child = children[i];
 			if ("namespace" in child) throw new Error(`Unexpected composite node '${child.namespace}.${child.type}' reached compile; composites must be lowered via lowerComposites first.`);
 			if (child.type === "node") {
-				const layout = require_node.layoutNode(require_style.resolveNodeStyle(child, styleStack), measureText, nameStack, nodeDistance, chain, require_style.resolveLabelDefault(styleStack), effectiveShapes, require_anchor.refPointOfTarget);
+				const effectiveNode = require_style.resolveNodeStyle(child, styleStack);
+				const layout = require_node.layoutNode({
+					...effectiveNode,
+					animations: filterAnimations(effectiveNode.animations, "element", onWarn, `${locatorPrefix}children[${i}].node`)
+				}, measureText, nameStack, nodeDistance, chain, require_style.resolveLabelDefault(styleStack), effectiveShapes, require_anchor.refPointOfTarget);
 				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, paint.resolve)) {
 					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"));
+				const outerRect = require_node.outerRectOf(globalLayout);
+				allPoints.push(require_rect.rect.anchor(outerRect, "north-west"), require_rect.rect.anchor(outerRect, "north-east"), require_rect.rect.anchor(outerRect, "south-west"), require_rect.rect.anchor(outerRect, "south-east"));
 				for (const p of require_node.labelExtentPoints(globalLayout)) allPoints.push(p);
 				layoutsAccumulator.push(globalLayout);
 			} else if (child.type === "coordinate") {
 				const localCenter = require_position.resolvePosition(child.position, nameStack, nodeDistance, chain, require_anchor.refPointOfTarget);
-				if (!localCenter) {
-					onWarn({
-						code: "POLAR_ORIGIN_UNRESOLVED",
-						message: `Cannot resolve position for coordinate '${child.id}'; polar.origin or at.of may reference an undefined node`,
-						path: `${locatorPrefix}children[${i}].coordinate.position`
-					});
-					throw new Error(`Cannot resolve position for coordinate ${child.id}; polar.origin or at.of may reference an undefined node`);
-				}
+				if (!localCenter) throw new Error(`Cannot resolve position for coordinate ${child.id}; polar.origin or at.of may reference an undefined node`);
 				const globalCenter = chain.length === 0 ? localCenter : require_scope.applyTransformChain(localCenter, chain);
-				const coordLayout = coordinateAsLayout(child.id, globalCenter);
+				const coordLayout = coordinateAsLayout(child.id, globalCenter, effectiveShapes);
 				nameStack.register(child.id, coordLayout, `${locatorPrefix}children[${i}].coordinate.id`);
 				layoutsAccumulator.push(coordLayout);
 			} else if (child.type === "scope") {
-				const loweredOwn = require_scope.lowerScopeTransforms(child.transforms ?? [], nameStack, nodeDistance);
+				const loweredOwn = require_scope.lowerScopeTransforms(child.transforms ?? [], nameStack, nodeDistance, require_anchor.refPointOfTarget);
 				if (loweredOwn === null) onWarn({
 					code: scopeTransformWarnCode(child),
-					message: `Cannot resolve one of scope.transforms; referent (at.of / offset.of / polar.origin) is undefined or defined later in the IR`,
+					message: `Cannot resolve one of scope.transforms; referent (at.of / offset.of / polar.origin / between endpoints) is undefined or defined later in the IR`,
 					path: `${locatorPrefix}children[${i}].scope.transforms`
 				});
 				const ownTransforms = loweredOwn ?? [];
 				const innerChain = [...chain, ...ownTransforms];
 				const parentFrameDepth = nameStack.depth - 1;
-				if (child.id) nameStack.register(child.id, scopePlaceholderLayout(child.id, innerChain), `${locatorPrefix}children[${i}].scope.id`);
+				let placeholderLayout;
+				if (child.id) {
+					placeholderLayout = scopePlaceholderLayout(child.id, innerChain, effectiveShapes);
+					nameStack.register(child.id, placeholderLayout, `${locatorPrefix}children[${i}].scope.id`);
+				}
 				const pushedFrame = child.localNamespace === true;
 				if (pushedFrame) nameStack.pushFrame();
 				const innerSink = [];
@@ -297,12 +321,12 @@ var compileToScene = (ir, options = {}) => {
 				*  让 scope 内 path 自引用本 scope.id 端点取真 bbox 而非 placeholder */
 				const innerPaths = [];
 				try {
-					processChildren(child.children, innerChain, innerSink, `${locatorPrefix}children[${i}].scope.`, innerLayouts, innerPaths, [...styleStack, require_style.buildStyleFrame(child)]);
+					processChildren(child.children, innerChain, innerSink, `${locatorPrefix}children[${i}].scope.`, innerLayouts, innerPaths, [...styleStack, require_style.createStyleFrame(child)]);
 					if (child.id) {
 						const bbox = require_scope.computeScopeBoundingBox(innerLayouts);
 						const fallbackOrigin = innerChain.length === 0 ? [0, 0] : require_scope.applyTransformChain([0, 0], innerChain);
-						const bboxLayout = require_scope.registerScopeAsLayout(child.id, bbox, fallbackOrigin);
-						nameStack.replaceLayout(child.id, bboxLayout, parentFrameDepth);
+						const bboxLayout = require_scope.registerScopeAsLayout(child.id, bbox, fallbackOrigin, effectiveShapes);
+						nameStack.replaceLayout(child.id, bboxLayout, parentFrameDepth, placeholderLayout);
 						layoutsAccumulator.push(bboxLayout);
 					} else for (const innerLayout of innerLayouts) layoutsAccumulator.push(innerLayout);
 					resolvePendingPaths(innerPaths);
@@ -317,13 +341,19 @@ var compileToScene = (ir, options = {}) => {
 				};
 				if (child.id !== void 0) group.id = child.id;
 				if (child.meta !== void 0) group.meta = child.meta;
+				const scopeAnimations = filterAnimations(child.animations, "element", onWarn, `${locatorPrefix}children[${i}].scope`);
+				if (scopeAnimations !== void 0) group.animations = scopeAnimations;
 				if (hasOwnTransforms) group.transforms = [...ownTransforms];
 				if (child.clip !== void 0) group.clipRef = clip.resolve(child.clip);
 				sink.push(group);
 				if (child.zIndex !== void 0) zIndexOf.set(group, child.zIndex);
 			} else {
+				const effectivePath = require_style.resolveEffectivePath(child, styleStack);
 				const pending = {
-					path: require_style.resolveEffectivePath(child, styleStack),
+					path: {
+						...effectivePath,
+						animations: filterAnimations(effectivePath.animations, "element", onWarn, `${locatorPrefix}children[${i}].path`)
+					},
 					irPath: `${locatorPrefix}children[${i}].path`,
 					scopeChain: chain,
 					zIndex: child.zIndex
@@ -349,10 +379,12 @@ var compileToScene = (ir, options = {}) => {
 		throw new Error(`internal: ${placeholderBalance} unresolved path placeholder(s) leaked into Scene output${detail}`);
 	}
 	const resources = [...paint.resources(), ...clip.resources()];
+	const rootAnimations = filterAnimations(loweredIr.animations, "root", onWarn, "scene");
 	return {
 		primitives: stableSortByZIndex(sealSink(primitives)),
 		layout: loweredIr.viewBox !== void 0 ? viewBoxToLayout(loweredIr.viewBox, round) : assertFiniteLayout(require_layout.computeLayout(allPoints, layoutPadding, round)),
-		...resources.length > 0 ? { resources } : {}
+		...resources.length > 0 ? { resources } : {},
+		...rootAnimations !== void 0 ? { animations: rootAnimations } : {}
 	};
 };
 //#endregion

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

@@ -3,21 +3,12 @@ import { Scene } from '../primitive';
 import { ShapeDefinition } from '../shapes';
 import { ArrowDefinition } from '../arrows';
 import { PatternDefinition } from '../patterns';
-import { PathGeneratorDefinition } from '../pathGenerators';
+import { PathGeneratorDefinition } from '../path-generators';
 import { CompositeDefinition } from '../composites';
+import { CompileWarning } from './constant';
 import { TextMeasurer } from './text-metrics';
-/** 编译期警告：path / position 解析失败时通过 `CompileOptions.onWarn` 发出，不影响编译产物 */
-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' | 'SHAPE_OVERRIDES_BUILTIN' | 'ARROW_OVERRIDES_BUILTIN' | 'PATTERN_OVERRIDES_BUILTIN' | 'COMPOSITE_NOT_REGISTERED' | (string & {});
-    /** 人类可读消息（英文） */
-    message: string;
-    /** IR locator 路径（jq-like，如 `'children[3].path.children[1].to'`） */
-    path: string;
-};
+export type { CompileWarning } from './constant';
+export { CompileWarningCode } from './constant';
 /** compileToScene 的可选参数 */
 export type CompileOptions = {
     /** 注入文字度量函数；不传则用 fallback（不准但可跑） */
@@ -81,7 +72,7 @@ export type CompileOptions = {
 };
 /**
  * IR → Scene 纯函数转换，所有 adapter 共享
- * @description Pass 1 递归处理 node / coordinate / scope，把 scope 树下沉为嵌套 GroupPrim；scope.transforms 中的 4 种 translate 变体按 lowerScopeTransforms 展平为 Cartesian transform；node 在 Scene primitive 树里是局部坐标 + GroupPrim transform 链、在 NameStack 中存全局坐标供其他节点 / path 引用。NameStack 用栈式 frame 管理命名空间：默认全局扁平、`<Scope localNamespace>` 推入子 frame；scope.id 始终在父 frame 注册（外部句柄）；id lookup 从栈顶向栈底 inside-out 搜索；同 frame 重复 id 触发 DUPLICATE_NODE_ID warn + 后定义覆盖前定义。Pass 2 解析 path 端点写 d 字符串，path primitive 发到 Pass 1 记录的对应容器；末端按 precision 折算 layout
+ * @description Pass 1 递归处理 node / coordinate / scope，把 scope 树下沉为嵌套 GroupPrim；scope.transforms 中的 5 种 translate 变体按 lowerScopeTransforms 展平为 Cartesian transform；node 在 Scene primitive 树里是局部坐标 + GroupPrim transform 链、在 NameStack 中存全局坐标供其他节点 / path 引用。NameStack 用栈式 frame 管理命名空间：默认全局扁平、`<Scope localNamespace>` 推入子 frame；scope.id 始终在父 frame 注册（外部句柄）；id lookup 从栈顶向栈底 inside-out 搜索；同 frame 重复 id 触发 DUPLICATE_NODE_ID warn + 后定义覆盖前定义。Pass 2 解析 path 端点写 d 字符串，path primitive 发到 Pass 1 记录的对应容器；末端按 precision 折算 layout
  */
 export declare const compileToScene: (ir: IR, options?: CompileOptions) => Scene;
 //# sourceMappingURL=compile.d.ts.map

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;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAwBzD,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AA6CrE,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,yBAAyB,GACzB,2BAA2B,GAC3B,0BAA0B,GAC1B,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;IACzC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IACzD;;;;OAIG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACxC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAwJF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAqWrE,CAAC"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAA0D,MAAM,OAAO,CAAC;AACxF,OAAO,KAAK,EAAa,KAAK,EAA6B,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AAuBpB,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAGrE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAoDhD,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;IACzC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IACzD;;;;OAIG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACxC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAuLF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAkXrE,CAAC"}

package/dist/lib/compile/{lowerComposites.cjs → composite.cjs}

@@ -1,3 +1,4 @@
+const require_constant = require("./constant.cjs");
 let zod = require("zod");
 /**
 * 从注册项的 schema 提取 `namespace` / `type` 的 literal 值（建表 key）
@@ -21,6 +22,13 @@ var extractKey = (schema) => {
 *   查表 → `schema.parse(node)` 精确校验 + 强类型 → `expand` → 递归展开产物 fixpoint），否则 tier1（scope 递归
 *   children）。未注册 → `onWarn(COMPOSITE_NOT_REGISTERED)` + 跳过该节点（不进 Scene），继续编译其余；
 *   环 / 超 `maxDepth` → throw（死循环防护）。无 tier2 节点时等价于原样返回。
+*
+*   **注册表策略差异（有意，非疏漏）**：composite 以 `Array<CompositeDefinition>` 注入，可能重复，故重名
+*   **throw**（结构上无法天然去重，撞名是调用方错误）；未注册走 **warn + skip**——composite 是高层节点，
+*   缺对应包时跳过它仍能渲染其余图元，优雅降级优于整图崩。相对地，shape / arrow / pattern 以 `Record` 注入
+*   （key 天然去重，无重名可言），同名覆盖内置走 **warn + last-wins**（覆盖是合法定制）；未注册名走 **throw**
+*   ——这些是"定位 / 布局类"基元，节点引用了不存在的 shape 根本无法布局，必须 fail-fast。两类策略按"数据结构
+*   + 语义分层"区分，不强行统一。
 */
 var lowerComposites = (ir, composites, options) => {
 	const { onWarn, maxDepth = 32 } = options;
@@ -38,7 +46,7 @@ var lowerComposites = (ir, composites, options) => {
 			const definition = registry.get(key);
 			if (!definition) {
 				onWarn({
-					code: "COMPOSITE_NOT_REGISTERED",
+					code: require_constant.CompileWarningCode.CompositeNotRegistered,
 					message: `No composite registered for '${key}'; the node is skipped.`,
 					path
 				});

package/dist/lib/compile/{lowerComposites.d.ts → composite.d.ts}

@@ -1,6 +1,6 @@
 import { CompositeDefinition } from '../composites';
 import { IR } from '../ir';
-import { CompileWarning } from './compile';
+import { CompileWarning } from './constant';
 /** composite 嵌套展开的默认最大深度（防环 / 防失控递归）；可经 CompileOptions.maxCompositeDepth 覆盖 */
 export declare const DEFAULT_MAX_COMPOSITE_DEPTH = 32;
 type LowerOptions = {
@@ -13,7 +13,14 @@ type LowerOptions = {
  *   查表 → `schema.parse(node)` 精确校验 + 强类型 → `expand` → 递归展开产物 fixpoint），否则 tier1（scope 递归
  *   children）。未注册 → `onWarn(COMPOSITE_NOT_REGISTERED)` + 跳过该节点（不进 Scene），继续编译其余；
  *   环 / 超 `maxDepth` → throw（死循环防护）。无 tier2 节点时等价于原样返回。
+ *
+ *   **注册表策略差异（有意，非疏漏）**：composite 以 `Array<CompositeDefinition>` 注入，可能重复，故重名
+ *   **throw**（结构上无法天然去重，撞名是调用方错误）；未注册走 **warn + skip**——composite 是高层节点，
+ *   缺对应包时跳过它仍能渲染其余图元，优雅降级优于整图崩。相对地，shape / arrow / pattern 以 `Record` 注入
+ *   （key 天然去重，无重名可言），同名覆盖内置走 **warn + last-wins**（覆盖是合法定制）；未注册名走 **throw**
+ *   ——这些是"定位 / 布局类"基元，节点引用了不存在的 shape 根本无法布局，必须 fail-fast。两类策略按"数据结构
+ *   + 语义分层"区分，不强行统一。
  */
 export declare const lowerComposites: (ir: IR, composites: Array<CompositeDefinition>, options: LowerOptions) => IR;
 export {};
-//# sourceMappingURL=lowerComposites.d.ts.map
+//# sourceMappingURL=composite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/compile/composite.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,EAAE,EAAW,MAAM,OAAO,CAAC;AAEzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,KAAK,YAAY,GAAG;IAClB,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAoBF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,EAAE,EACN,YAAY,KAAK,CAAC,mBAAmB,CAAC,EACtC,SAAS,YAAY,KACpB,EA8CF,CAAC"}

package/dist/lib/compile/constant.cjs

@@ -0,0 +1,24 @@
+//#region src/compile/constant.ts
+/** 编译期 warning code（机器可读）。 */
+var CompileWarningCode = {
+	UnresolvedNodeReference: "UNRESOLVED_NODE_REFERENCE",
+	PathTooShort: "PATH_TOO_SHORT",
+	AnchorResolutionFailed: "ANCHOR_RESOLUTION_FAILED",
+	OffsetBaseUnresolved: "OFFSET_BASE_UNRESOLVED",
+	PolarOriginUnresolved: "POLAR_ORIGIN_UNRESOLVED",
+	AtTargetUnresolved: "AT_TARGET_UNRESOLVED",
+	RelativeInitialNoPrevEnd: "RELATIVE_INITIAL_NO_PREV_END",
+	BboxExtremeInput: "BBOX_EXTREME_INPUT",
+	DuplicateNodeId: "DUPLICATE_NODE_ID",
+	ShapeOverridesBuiltin: "SHAPE_OVERRIDES_BUILTIN",
+	ArrowOverridesBuiltin: "ARROW_OVERRIDES_BUILTIN",
+	PatternOverridesBuiltin: "PATTERN_OVERRIDES_BUILTIN",
+	CompositeNotRegistered: "COMPOSITE_NOT_REGISTERED",
+	AnimationInvalidProperty: "ANIMATION_INVALID_PROPERTY",
+	ArcMissingRadius: "ARC_MISSING_RADIUS",
+	PartialArcNeedsBothAngles: "PARTIAL_ARC_NEEDS_BOTH_ANGLES"
+};
+var formatCompileWarning = (warning) => `[retikz] ${warning.code} at ${warning.path}: ${warning.message}`;
+//#endregion
+exports.CompileWarningCode = CompileWarningCode;
+exports.formatCompileWarning = formatCompileWarning;

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

@@ -0,0 +1,32 @@
+import { ValueOf } from '../types';
+/** 编译期 warning code（机器可读）。 */
+export declare const CompileWarningCode: {
+    readonly UnresolvedNodeReference: "UNRESOLVED_NODE_REFERENCE";
+    readonly PathTooShort: "PATH_TOO_SHORT";
+    readonly AnchorResolutionFailed: "ANCHOR_RESOLUTION_FAILED";
+    readonly OffsetBaseUnresolved: "OFFSET_BASE_UNRESOLVED";
+    readonly PolarOriginUnresolved: "POLAR_ORIGIN_UNRESOLVED";
+    readonly AtTargetUnresolved: "AT_TARGET_UNRESOLVED";
+    readonly RelativeInitialNoPrevEnd: "RELATIVE_INITIAL_NO_PREV_END";
+    readonly BboxExtremeInput: "BBOX_EXTREME_INPUT";
+    readonly DuplicateNodeId: "DUPLICATE_NODE_ID";
+    readonly ShapeOverridesBuiltin: "SHAPE_OVERRIDES_BUILTIN";
+    readonly ArrowOverridesBuiltin: "ARROW_OVERRIDES_BUILTIN";
+    readonly PatternOverridesBuiltin: "PATTERN_OVERRIDES_BUILTIN";
+    readonly CompositeNotRegistered: "COMPOSITE_NOT_REGISTERED";
+    readonly AnimationInvalidProperty: "ANIMATION_INVALID_PROPERTY";
+    readonly ArcMissingRadius: "ARC_MISSING_RADIUS";
+    readonly PartialArcNeedsBothAngles: "PARTIAL_ARC_NEEDS_BOTH_ANGLES";
+};
+export type CompileWarningCodeValue = ValueOf<typeof CompileWarningCode> | (string & {});
+/** 编译期 warning：不影响 Scene 产物，交给调用方收集或展示。 */
+export type CompileWarning = {
+    /** 机器可读 warning code。 */
+    code: CompileWarningCodeValue;
+    /** 人类可读消息（英文）。 */
+    message: string;
+    /** IR locator 路径（jq-like），如 `children[3].path.children[1].to`。 */
+    path: string;
+};
+export declare const formatCompileWarning: (warning: CompileWarning) => string;
+//# sourceMappingURL=constant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constant.d.ts","sourceRoot":"","sources":["../../../src/compile/constant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;CAiBrB,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAC/B,OAAO,CAAC,OAAO,kBAAkB,CAAC,GAClC,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG;IAC3B,yBAAyB;IACzB,IAAI,EAAE,uBAAuB,CAAC;IAC9B,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,SAAS,cAAc,KAAG,MACI,CAAC"}

package/dist/lib/compile/direction.cjs

@@ -0,0 +1,31 @@
+const require_at_position = require("../ir/position/at-position.cjs");
+const require_anchor = require("../geometry/anchor.cjs");
+//#region src/compile/direction.ts
+/**
+* 8 方向在屏幕坐标系（y 向下）里的单位向量。
+* @description above=视觉上方（y 减小）；对角分量用 1/√2，保证斜向 distance 与水平 / 垂直 distance 等长。
+*/
+var DirectionVectorByAtDirection = {
+	[require_at_position.AtDirection.Above]: [0, -1],
+	[require_at_position.AtDirection.Below]: [0, 1],
+	[require_at_position.AtDirection.Left]: [-1, 0],
+	[require_at_position.AtDirection.Right]: [1, 0],
+	[require_at_position.AtDirection.AboveLeft]: [-Math.SQRT1_2, -Math.SQRT1_2],
+	[require_at_position.AtDirection.AboveRight]: [Math.SQRT1_2, -Math.SQRT1_2],
+	[require_at_position.AtDirection.BelowLeft]: [-Math.SQRT1_2, Math.SQRT1_2],
+	[require_at_position.AtDirection.BelowRight]: [Math.SQRT1_2, Math.SQRT1_2]
+};
+/** 8 方向 label position 对应的节点边界 anchor。 */
+var LabelAnchorByAtDirection = {
+	[require_at_position.AtDirection.Above]: require_anchor.CompassAnchor.North,
+	[require_at_position.AtDirection.Below]: require_anchor.CompassAnchor.South,
+	[require_at_position.AtDirection.Left]: require_anchor.CompassAnchor.West,
+	[require_at_position.AtDirection.Right]: require_anchor.CompassAnchor.East,
+	[require_at_position.AtDirection.AboveLeft]: require_anchor.CompassAnchor.NorthWest,
+	[require_at_position.AtDirection.AboveRight]: require_anchor.CompassAnchor.NorthEast,
+	[require_at_position.AtDirection.BelowLeft]: require_anchor.CompassAnchor.SouthWest,
+	[require_at_position.AtDirection.BelowRight]: require_anchor.CompassAnchor.SouthEast
+};
+//#endregion
+exports.DirectionVectorByAtDirection = DirectionVectorByAtDirection;
+exports.LabelAnchorByAtDirection = LabelAnchorByAtDirection;

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

@@ -0,0 +1,27 @@
+export type DirectionVector = readonly [number, number];
+/**
+ * 8 方向在屏幕坐标系（y 向下）里的单位向量。
+ * @description above=视觉上方（y 减小）；对角分量用 1/√2，保证斜向 distance 与水平 / 垂直 distance 等长。
+ */
+export declare const DirectionVectorByAtDirection: {
+    readonly above: readonly [0, -1];
+    readonly below: readonly [0, 1];
+    readonly left: readonly [-1, 0];
+    readonly right: readonly [1, 0];
+    readonly "above-left": readonly [number, number];
+    readonly "above-right": readonly [number, number];
+    readonly "below-left": readonly [number, number];
+    readonly "below-right": readonly [number, number];
+};
+/** 8 方向 label position 对应的节点边界 anchor。 */
+export declare const LabelAnchorByAtDirection: {
+    readonly above: "north";
+    readonly below: "south";
+    readonly left: "west";
+    readonly right: "east";
+    readonly "above-left": "north-west";
+    readonly "above-right": "north-east";
+    readonly "below-left": "south-west";
+    readonly "below-right": "south-east";
+};
+//# sourceMappingURL=direction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"direction.d.ts","sourceRoot":"","sources":["../../../src/compile/direction.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;CASqB,CAAC;AAE/D,0CAA0C;AAC1C,eAAO,MAAM,wBAAwB;;;;;;;;;CAS4B,CAAC"}

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

@@ -1,9 +1,11 @@
 export * from './compile';
+export * from './constant';
 export * from './node';
-export * from './path/index';
+export * from './path';
 export * from './position';
 export * from './precision';
 export * from './scope';
 export * from './text-metrics';
 export * from './layout';
+export * from './composite';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/compile/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/compile/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/dist/lib/compile/name-stack.cjs

@@ -81,13 +81,17 @@ var NameStack = class {
 	* @param id 要替换的 id（必须已在该 frame 注册过）
 	* @param layout 新的 NodeLayout（覆盖旧值）
 	* @param frameDepth 0 = 根 frame；通常传 scope 入场前的栈深 - 1
+	* @param expectedCurrent 可选的当前 layout 引用；传入后仅当 frame 中仍是该引用时才替换
+	* @returns true = 完成替换；false = 当前值已被后续 register 覆盖，未替换
 	*/
-	replaceLayout(id, layout, frameDepth) {
+	replaceLayout(id, layout, frameDepth, expectedCurrent) {
 		if (this.currentPhase !== "pass1") throw new Error(`NameStack.replaceLayout('${id}'): only allowed during pass1; current phase is '${this.currentPhase}'`);
 		if (frameDepth < 0 || frameDepth >= this.frames.length) throw new Error(`NameStack.replaceLayout('${id}'): frameDepth ${frameDepth} out of range (stack depth ${this.frames.length})`);
 		const targetFrame = this.frames[frameDepth];
 		if (!targetFrame.has(id)) throw new Error(`NameStack.replaceLayout('${id}'): id not previously registered in frame at depth ${frameDepth}`);
+		if (expectedCurrent !== void 0 && targetFrame.get(id) !== expectedCurrent) return false;
 		targetFrame.set(id, layout);
+		return true;
 	}
 	/**
 	* inside-out 查找 id 对应的 NodeLayout

package/dist/lib/compile/name-stack.d.ts

@@ -70,8 +70,10 @@ export declare class NameStack {
      * @param id 要替换的 id（必须已在该 frame 注册过）
      * @param layout 新的 NodeLayout（覆盖旧值）
      * @param frameDepth 0 = 根 frame；通常传 scope 入场前的栈深 - 1
+     * @param expectedCurrent 可选的当前 layout 引用；传入后仅当 frame 中仍是该引用时才替换
+     * @returns true = 完成替换；false = 当前值已被后续 register 覆盖，未替换
      */
-    replaceLayout(id: string, layout: NodeLayout, frameDepth: number): void;
+    replaceLayout(id: string, layout: NodeLayout, frameDepth: number, expectedCurrent?: NodeLayout): boolean;
     /**
      * inside-out 查找 id 对应的 NodeLayout
      * @description 从栈顶向栈底依次查找；首个命中的 frame 返回；都没命中返回 undefined。内层可见外层（shadowing），外层不可见内层

package/dist/lib/compile/name-stack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"name-stack.d.ts","sourceRoot":"","sources":["../../../src/compile/name-stack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,qBAAqB;AACrB,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAwC;IACrE,6EAA6E;IAC7E,OAAO,CAAC,YAAY,CAA8B;gBAEtC,OAAO,GAAE,gBAAqB;IAM1C,6BAA6B;IAC7B,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8BAA8B;IAC9B,IAAI,KAAK,IAAI,OAAO,GAAG,OAAO,CAE7B;IAED,iDAAiD;IACjD,SAAS,IAAI,IAAI;IAKjB;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAQhB,kEAAkE;IAClE,gBAAgB,IAAI,IAAI;IAIxB,6EAA6E;IAC7E,eAAe,IAAI,IAAI;IAIvB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO;IAuBlE;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAoBvE;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAO3C"}
+{"version":3,"file":"name-stack.d.ts","sourceRoot":"","sources":["../../../src/compile/name-stack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,qBAAqB;AACrB,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAwC;IACrE,6EAA6E;IAC7E,OAAO,CAAC,YAAY,CAA8B;gBAEtC,OAAO,GAAE,gBAAqB;IAM1C,6BAA6B;IAC7B,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,8BAA8B;IAC9B,IAAI,KAAK,IAAI,OAAO,GAAG,OAAO,CAE7B;IAED,iDAAiD;IACjD,SAAS,IAAI,IAAI;IAKjB;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAQhB,kEAAkE;IAClE,gBAAgB,IAAI,IAAI;IAIxB,6EAA6E;IAC7E,eAAe,IAAI,IAAI;IAIvB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO;IAuBlE;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,UAAU,GAAG,OAAO;IAsBxG;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAO3C"}