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

package/dist/es/arrows/define.d.ts

@@ -0,0 +1,9 @@
+import { ArrowDefinition } from './types';
+/**
+ * 定义一个 arrow 注册项
+ * @description 与 `defineShape` / `definePathGenerator` 对齐的定义点 helper；当前不做额外运行时校验，
+ *   只保留 `ArrowDefinition` 形态并让第三方扩展面写法一致。
+ * @returns 原样返回的 def（便于 `export const bracket = defineArrow({ ... })`）
+ */
+export declare const defineArrow: (def: ArrowDefinition) => ArrowDefinition;
+//# sourceMappingURL=define.d.ts.map

package/dist/es/arrows/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/arrows/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,eAAe,KAAG,eAAsB,CAAC"}

package/dist/es/arrows/define.js

@@ -0,0 +1,10 @@
+//#region src/arrows/define.ts
+/**
+* 定义一个 arrow 注册项
+* @description 与 `defineShape` / `definePathGenerator` 对齐的定义点 helper；当前不做额外运行时校验，
+*   只保留 `ArrowDefinition` 形态并让第三方扩展面写法一致。
+* @returns 原样返回的 def（便于 `export const bracket = defineArrow({ ... })`）
+*/
+var defineArrow = (def) => def;
+//#endregion
+export { defineArrow };

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

@@ -1,13 +1,15 @@
 import { BuiltinArrowName } from '../ir/path/arrow';
 import { ArrowDefinition } from './types';
 /**
- * 内置 7 arrow 注册项；与 `CompileOptions.arrows` 合并时被同名注入覆盖
+ * 内置 8 arrow 注册项；与 `CompileOptions.arrows` 合并时被同名注入覆盖
  * @description 几何字段（lineContactX 静态 base / tipX / hollow）：
  *   实心 normal/diamond/circle lineContactX=0；stealth=3；open/openDiamond base=1 + tipX=9 + hollow；
+ *   openStealth base=3 + tipX=9 + hollow；
  *   openCircle base=0.75 + hollow。baseSize / defaultLength / defaultWidth 走类型缺省（10 / 6 / 6）。
  *   framework 对 hollow def 统一把 lineContactX 减 lineWidth/2 得实际 refX / shrink 接触点。
  *   emit 几何在局部 baseSize=10 坐标系（renderer-agnostic）。
  */
 export declare const BUILTIN_ARROWS: Record<BuiltinArrowName, ArrowDefinition>;
 export type { ArrowDefinition, ArrowEmitContext } from './types';
+export { defineArrow } from './define';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/arrows/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAiCjE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,gBAAgB,EAAE,eAAe,CAqDpE,CAAC;AAEF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/arrows/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAiCjE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,gBAAgB,EAAE,eAAe,CA2DpE,CAAC;AAEF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/es/arrows/index.js

@@ -1,3 +1,4 @@
+import "./define.js";
 //#region src/arrows/index.ts
 /** 实心闭合三角 / 菱形 / V 形的 path 工厂：填充走 ctx.fill（无 override = contextStroke） */
 var filledPath = (ctx, points) => ({
@@ -34,9 +35,10 @@ var hollowPath = (ctx, points, strokeLinejoin) => ({
 	...strokeLinejoin ? { strokeLinejoin } : {}
 });
 /**
-* 内置 7 arrow 注册项；与 `CompileOptions.arrows` 合并时被同名注入覆盖
+* 内置 8 arrow 注册项；与 `CompileOptions.arrows` 合并时被同名注入覆盖
 * @description 几何字段（lineContactX 静态 base / tipX / hollow）：
 *   实心 normal/diamond/circle lineContactX=0；stealth=3；open/openDiamond base=1 + tipX=9 + hollow；
+*   openStealth base=3 + tipX=9 + hollow；
 *   openCircle base=0.75 + hollow。baseSize / defaultLength / defaultWidth 走类型缺省（10 / 6 / 6）。
 *   framework 对 hollow def 统一把 lineContactX 减 lineWidth/2 得实际 refX / shrink 接触点。
 *   emit 几何在局部 baseSize=10 坐标系（renderer-agnostic）。
@@ -69,6 +71,17 @@ var BUILTIN_ARROWS = {
 			[3, 5]
 		])]
 	},
+	openStealth: {
+		hollow: true,
+		lineContactX: 3,
+		tipX: 9,
+		emit: (ctx) => [hollowPath(ctx, [
+			[1, 1],
+			[9, 5],
+			[1, 9],
+			[3, 5]
+		], "miter")]
+	},
 	diamond: {
 		lineContactX: 0,
 		emit: (ctx) => [filledPath(ctx, [

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

@@ -18,10 +18,10 @@ export type ArrowEmitContext = {
 /**
  * 一个 arrow 的可注册定义：几何尺寸 + emit
  * @description plain object（factory 友好），含函数、**不进 IR**，走 `CompileOptions.arrows` 运行时注入。
- *   内置 7 箭头也是注册项（无内置特权，对齐 `ShapeDefinition` / `BUILTIN_SHAPES`）。
+ *   内置 8 箭头也是注册项（无内置特权，对齐 `ShapeDefinition` / `BUILTIN_SHAPES`）。
  *
  *   `lineContactX` 存**静态 base**（不含 lineWidth 调整）：实心 normal/diamond/circle = 0、stealth = 3、
- *   open/openDiamond base = 1、openCircle base = 0.75。framework 对 `hollow: true` 的 def 统一减
+ *   open/openDiamond base = 1、openStealth base = 3、openCircle base = 0.75。framework 对 `hollow: true` 的 def 统一减
  *   `lineWidth/2` 得到实际 refX / shrink 接触点（这条调整由编译器 / adapter 落，def 只声明静态 base）。
  */
 export type ArrowDefinition = {
@@ -31,6 +31,8 @@ export type ArrowDefinition = {
     hollow?: boolean;
     /** 线接触点静态 base（决定 path shrink + marker refX）；空心 def 由 framework 再减 lineWidth/2 */
     lineContactX: number;
+    /** 外轮廓补偿量（marker 局部坐标）；缺省时空心箭头用 lineWidth/2，实心箭头用 0 */
+    outerInset?: number;
     /** 尖端 x（shrink 用）；缺省 = baseSize */
     tipX?: number;
     /** 默认箭头长度（length fallback）；缺省 6 */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/arrows/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sEAAsE;IACtE,MAAM,EAAE,UAAU,CAAC;IACnB,qDAAqD;IACrD,IAAI,EAAE,UAAU,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,IAAI,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,QAAQ,CAAC,eAAe,CAAC,CAAC;CAC5D,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/arrows/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sEAAsE;IACtE,MAAM,EAAE,UAAU,CAAC;IACnB,qDAAqD;IACrD,IAAI,EAAE,UAAU,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,IAAI,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,QAAQ,CAAC,eAAe,CAAC,CAAC;CAC5D,CAAC"}

package/dist/es/compile/anchor-cache.d.ts

@@ -1,9 +1,9 @@
-import { Side } from '../geometry/_edge';
+import { Side } from '../geometry/edge';
 import { IRBoundary, IRPosition } from '../ir';
 import { NodeLayout } from './node';
 /**
  * 取节点 anchor 的全局坐标，带 per-layout 缓存
- * @description name 接受 RectAnchor 关键字（如 `'north'` / `'south-west'`）或数字角度字符串（如 `'30'` / `'-45'`）；
+ * @description name 接受方位 anchor 关键字（如 `'north'` / `'south-west'` / `'top-left'`）或数字角度字符串（如 `'30'` / `'-45'`）；
  *   boundary 指定连接面（默认 `'shape'`，即节点自身视觉轮廓）；不同 boundary 产生独立缓存条目，互不串扰；
  *   同一 (layout, name, boundary) 组合第二次起返回首调用结果的**同一引用**——上游可用 `===` 判定 cache 命中
  * @param layout 已 Pass 1 完成的 NodeLayout（rect 已是全局坐标）
@@ -15,7 +15,7 @@ export declare const resolveAnchor: (layout: NodeLayout, anchorName: string, bou
 /**
  * 取节点边上比例点 `{ side, t }` 的全局坐标，带 per-layout 缓存
  * @description 走 `layout.shapeDef.edgePoint`——shape 未实现（如自定义 shape）抛"does not support side anchors"；
- *   零尺寸 layout（Coordinate）抛错（边上比例点对一个点无意义，报错比退化中心更可诊断，见 alpha.6 ADR-01 决策细节 #10）。
+ *   零尺寸 layout（Coordinate）抛错（边上比例点对一个点无意义，报错比退化中心更可诊断）。
  *   缓存 key = `${side}:${t}`，与命名 anchor（`'north'` / `'30'`）共用 layout 的 Map——key 含 `:` 故命名空间不冲突。
  * @param layout 已 Pass 1 完成的 NodeLayout（rect 已是全局坐标）
  * @returns 全局坐标系下的 IRPosition `[x, y]`

package/dist/es/compile/anchor-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor-cache.d.ts","sourceRoot":"","sources":["../../../src/compile/anchor-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAiCzC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,UAAU,EAClB,YAAY,MAAM,EAClB,WAAU,UAAU,GAAG,SAAmB,KACzC,UAYF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,UAAU,EAClB,MAAM,IAAI,EACV,GAAG,MAAM,KACR,UAuBF,CAAC"}
+{"version":3,"file":"anchor-cache.d.ts","sourceRoot":"","sources":["../../../src/compile/anchor-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AA8CzC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,UAAU,EAClB,YAAY,MAAM,EAClB,WAAU,UAAU,GAAG,SAAmB,KACzC,UAYF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,UAAU,EAClB,MAAM,IAAI,EACV,GAAG,MAAM,KACR,UAuBF,CAAC"}

package/dist/es/compile/anchor-cache.js

@@ -1,5 +1,6 @@
+import { normalizeCompassAnchor } from "../geometry/anchor.js";
 import { boundaryKey } from "./boundary.js";
-import { anchorOf, angleBoundaryOf } from "./node.js";
+import { anchorOf, angleBoundaryOf, outerRectOf } from "./node.js";
 //#region src/compile/anchor-cache.ts
 /**
 * (layout, anchorName) → IRPosition 缓存
@@ -8,19 +9,31 @@ import { anchorOf, angleBoundaryOf } from "./node.js";
 var cache = /* @__PURE__ */ new WeakMap();
 /** 角度字符串识别：可选负号 + 数字 + 可选小数；与 parseTarget.ts 的 ANGLE_RE 同语义 */
 var ANGLE_RE = /^-?\d+(\.\d+)?$/;
+/** 把 layout 的 rect 换成外边界 AABB（外扩 outerSep）——border 类 anchor 在其上解析（ADR-07 §1） */
+var withOuterRect = (layout) => ({
+	...layout,
+	rect: outerRectOf(layout)
+});
 /**
 * 把 anchorName 解析到对应 shape 的 anchor / boundaryPoint 上
-* @description 数字字符串走 angleBoundaryOf；其余按 RectAnchor 走 anchorOf；boundary 透传给两者
+* @description 数字字符串走 angleBoundaryOf；其余按标准方位 / shape-specific anchor 走 anchorOf；boundary 透传给两者。
+*   border 类 anchor（数字角度 + compass 方位名）按 outerSep 外推：在外扩 margin 的 rect（`outerRectOf`）上解析
+*   （ADR-07 §1）。形状专属命名 anchor（tip-N / apex 等）恒走视觉 rect、不外扩（§3）。`center` 在 inflate 下
+*   中心不变，走哪条路结果一致。
 */
 var computeAnchor = (layout, anchorName, boundary) => {
-	if (ANGLE_RE.test(anchorName)) return positionToIR(angleBoundaryOf(layout, Number(anchorName), boundary));
+	if (ANGLE_RE.test(anchorName)) {
+		const angle = Number(anchorName);
+		return positionToIR(angleBoundaryOf(withOuterRect(layout), angle, boundary));
+	}
+	if (normalizeCompassAnchor(anchorName) !== void 0) return positionToIR(anchorOf(withOuterRect(layout), anchorName, boundary));
 	return positionToIR(anchorOf(layout, anchorName, boundary));
 };
 /** geometry Position（含 readonly 形态）转 IRPosition 元组（IRPosition === [number, number]） */
 var positionToIR = (p) => [p[0], p[1]];
 /**
 * 取节点 anchor 的全局坐标，带 per-layout 缓存
-* @description name 接受 RectAnchor 关键字（如 `'north'` / `'south-west'`）或数字角度字符串（如 `'30'` / `'-45'`）；
+* @description name 接受方位 anchor 关键字（如 `'north'` / `'south-west'` / `'top-left'`）或数字角度字符串（如 `'30'` / `'-45'`）；
 *   boundary 指定连接面（默认 `'shape'`，即节点自身视觉轮廓）；不同 boundary 产生独立缓存条目，互不串扰；
 *   同一 (layout, name, boundary) 组合第二次起返回首调用结果的**同一引用**——上游可用 `===` 判定 cache 命中
 * @param layout 已 Pass 1 完成的 NodeLayout（rect 已是全局坐标）
@@ -44,7 +57,7 @@ var resolveAnchor = (layout, anchorName, boundary = "shape") => {
 /**
 * 取节点边上比例点 `{ side, t }` 的全局坐标，带 per-layout 缓存
 * @description 走 `layout.shapeDef.edgePoint`——shape 未实现（如自定义 shape）抛"does not support side anchors"；
-*   零尺寸 layout（Coordinate）抛错（边上比例点对一个点无意义，报错比退化中心更可诊断，见 alpha.6 ADR-01 决策细节 #10）。
+*   零尺寸 layout（Coordinate）抛错（边上比例点对一个点无意义，报错比退化中心更可诊断）。
 *   缓存 key = `${side}:${t}`，与命名 anchor（`'north'` / `'30'`）共用 layout 的 Map——key 含 `:` 故命名空间不冲突。
 * @param layout 已 Pass 1 完成的 NodeLayout（rect 已是全局坐标）
 * @returns 全局坐标系下的 IRPosition `[x, y]`

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

@@ -2,18 +2,19 @@ import { rect } from "../geometry/rect.js";
 import { BUILTIN_SHAPES } from "../shapes/index.js";
 import { BUILTIN_ARROWS } from "../arrows/index.js";
 import { BUILTIN_PATTERNS } from "../patterns/index.js";
-import { lowerComposites } from "./lowerComposites.js";
+import { CompileWarningCode, formatCompileWarning } from "./constant.js";
+import { lowerComposites } from "./composite.js";
 import { NameStack } from "./name-stack.js";
 import { applyTransformChain, computeScopeBoundingBox, lowerScopeTransforms, projectLayoutToGlobal, registerScopeAsLayout } from "./scope.js";
 import { resolvePosition } from "./position.js";
-import { emitNodePrimitives, labelExtentPoints, layoutNode } from "./node.js";
+import { emitNodePrimitives, labelExtentPoints, layoutNode, outerRectOf } from "./node.js";
 import { createPaintRegistry } from "./paint.js";
 import { createClipRegistry } from "./clip.js";
 import { fallbackMeasurer } from "./text-metrics.js";
 import { refPointOfTarget } from "./path/anchor.js";
 import { emitPathPrimitive } from "./path/index.js";
-import { makeRound } from "./precision.js";
-import { buildStyleFrame, resolveEffectivePath, resolveLabelDefault, resolveNodeStyle } from "./style.js";
+import { createRound } from "./precision.js";
+import { createStyleFrame, resolveEffectivePath, resolveLabelDefault, resolveNodeStyle } from "./style.js";
 import { computeLayout } from "./layout.js";
 //#region src/compile/compile.ts
 /**
@@ -21,10 +22,10 @@ import { computeLayout } from "./layout.js";
 * @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: 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: 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] : applyTransformChain([0, 0], chain));
+var scopePlaceholderLayout = (id, chain, shapes) => {
+	return zeroSizeRectAt(id, chain.length === 0 ? [0, 0] : 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(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: 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 CompileWarningCode.OffsetBaseUnresolved;
+		if (t.kind === "at-translate") return CompileWarningCode.AtTargetUnresolved;
+		if (t.kind === "polar-translate") return CompileWarningCode.PolarOriginUnresolved;
+		if (t.kind === "between-translate") return CompileWarningCode.UnresolvedNodeReference;
 	}
-	return "UNRESOLVED_NODE_REFERENCE";
+	return CompileWarningCode.UnresolvedNodeReference;
 };
 /** 把 DuplicateRegisterInfo 翻成 CompileWarning（含可读 message + 双 IR locator） */
 var formatDuplicateWarning = (info) => {
@@ -122,19 +144,19 @@ var formatDuplicateWarning = (info) => {
 	const firstLoc = info.firstIrPath ?? "(unknown earlier location)";
 	const secondLoc = info.secondIrPath ?? "(unknown current location)";
 	return {
-		code: "DUPLICATE_NODE_ID",
+		code: 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 ?? fallbackMeasurer;
 	const layoutPadding = options.padding ?? 10;
-	const round = makeRound(options.precision ?? 2);
+	const round = createRound(options.precision ?? 2);
 	const nodeDistance = options.nodeDistance;
 	const onWarn = options.onWarn ?? defaultWarnDispatcher;
 	const loweredIr = lowerComposites(ir, options.composites ?? [], {
@@ -147,7 +169,7 @@ var compileToScene = (ir, options = {}) => {
 	} : BUILTIN_SHAPES;
 	if (options.shapes) {
 		for (const name of Object.keys(options.shapes)) if (Object.prototype.hasOwnProperty.call(BUILTIN_SHAPES, name)) onWarn({
-			code: "SHAPE_OVERRIDES_BUILTIN",
+			code: 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 = {}) => {
 	} : BUILTIN_ARROWS;
 	if (options.arrows) {
 		for (const name of Object.keys(options.arrows)) if (Object.prototype.hasOwnProperty.call(BUILTIN_ARROWS, name)) onWarn({
-			code: "ARROW_OVERRIDES_BUILTIN",
+			code: 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 = {}) => {
 	} : BUILTIN_PATTERNS;
 	if (options.patterns) {
 		for (const name of Object.keys(options.patterns)) if (Object.prototype.hasOwnProperty.call(BUILTIN_PATTERNS, name)) onWarn({
-			code: "PATTERN_OVERRIDES_BUILTIN",
+			code: 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 = layoutNode(resolveNodeStyle(child, styleStack), measureText, nameStack, nodeDistance, chain, resolveLabelDefault(styleStack), effectiveShapes, refPointOfTarget);
+				const effectiveNode = resolveNodeStyle(child, styleStack);
+				const layout = layoutNode({
+					...effectiveNode,
+					animations: filterAnimations(effectiveNode.animations, "element", onWarn, `${locatorPrefix}children[${i}].node`)
+				}, measureText, nameStack, nodeDistance, chain, resolveLabelDefault(styleStack), effectiveShapes, refPointOfTarget);
 				const globalLayout = chain.length === 0 ? layout : projectLayoutToGlobal(layout, chain);
 				if (child.id) nameStack.register(child.id, globalLayout, `${locatorPrefix}children[${i}].node.id`);
 				for (const prim of emitNodePrimitives(layout, round, paint.resolve)) {
 					sink.push(prim);
 					if (child.zIndex !== void 0) zIndexOf.set(prim, child.zIndex);
 				}
-				allPoints.push(rect.anchor(globalLayout.rect, "north-west"), rect.anchor(globalLayout.rect, "north-east"), rect.anchor(globalLayout.rect, "south-west"), rect.anchor(globalLayout.rect, "south-east"));
+				const outerRect = outerRectOf(globalLayout);
+				allPoints.push(rect.anchor(outerRect, "north-west"), rect.anchor(outerRect, "north-east"), rect.anchor(outerRect, "south-west"), rect.anchor(outerRect, "south-east"));
 				for (const p of labelExtentPoints(globalLayout)) allPoints.push(p);
 				layoutsAccumulator.push(globalLayout);
 			} else if (child.type === "coordinate") {
 				const localCenter = resolvePosition(child.position, nameStack, nodeDistance, chain, 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 : 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 = lowerScopeTransforms(child.transforms ?? [], nameStack, nodeDistance);
+				const loweredOwn = lowerScopeTransforms(child.transforms ?? [], nameStack, nodeDistance, 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, buildStyleFrame(child)]);
+					processChildren(child.children, innerChain, innerSink, `${locatorPrefix}children[${i}].scope.`, innerLayouts, innerPaths, [...styleStack, createStyleFrame(child)]);
 					if (child.id) {
 						const bbox = computeScopeBoundingBox(innerLayouts);
 						const fallbackOrigin = innerChain.length === 0 ? [0, 0] : applyTransformChain([0, 0], innerChain);
-						const bboxLayout = registerScopeAsLayout(child.id, bbox, fallbackOrigin);
-						nameStack.replaceLayout(child.id, bboxLayout, parentFrameDepth);
+						const bboxLayout = 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 = resolveEffectivePath(child, styleStack);
 				const pending = {
-					path: 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(computeLayout(allPoints, layoutPadding, round)),
-		...resources.length > 0 ? { resources } : {}
+		...resources.length > 0 ? { resources } : {},
+		...rootAnimations !== void 0 ? { animations: rootAnimations } : {}
 	};
 };
 //#endregion

package/dist/es/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/es/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/es/compile/{lowerComposites.js → composite.js}

@@ -1,3 +1,4 @@
+import { CompileWarningCode } from "./constant.js";
 import { z } from "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: CompileWarningCode.CompositeNotRegistered,
 					message: `No composite registered for '${key}'; the node is skipped.`,
 					path
 				});

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