@retikz/core 0.3.0-alpha.3 → 0.3.0-alpha.4

package/README.md

@@ -1,41 +1,41 @@
-# @retikz/core
-
-Framework-agnostic core of [retikz](https://pionpill.github.io/retikz/) — a TikZ-inspired diagramming library. Provides the zod-typed **IR**, the **`compileToScene`** compiler, pure **parsers**, geometry helpers, and the shape / arrow / pattern / path-generator registries.
-
-零框架核心：retikz 的中间表示（IR）、`compileToScene` 编译器、纯解析器、几何工具与形状 / 箭头 / 图案 / 路径生成器注册面。**零 React、零 DOM**，运行时依赖只有 `zod`，IR 100% 可 JSON 序列化。
-
-## Install
-
-```bash
-pnpm add @retikz/core
-```
-
-## Usage
-
-`@retikz/core` is renderer-agnostic: it turns an IR into a serializable `Scene`. A backend (`@retikz/render`) or runtime (`@retikz/react` / `@retikz/vanilla`) then renders that Scene.
-
-```ts
-import { compileToScene } from '@retikz/core';
-
-const scene = compileToScene(ir);
-// optional: compileToScene(ir, { measureText, shapes, arrows, padding, ... })
-// hand `scene` to @retikz/render/svg, @retikz/render/canvas, or a runtime
-```
-
-Most users consume core indirectly through [`@retikz/react`](https://www.npmjs.com/package/@retikz/react) or [`@retikz/vanilla`](https://www.npmjs.com/package/@retikz/vanilla). Use core directly when you build IR programmatically, persist/transport scenes, or write a custom renderer.
-
-## Exports
-
-- `compileToScene` / `computeLayout` / `fallbackMeasurer` — IR → `Scene`
-- IR & `Scene` zod schemas + inferred types
-- `parseWay` / `parseNodeTarget` / `parseTargetSugar` — pure parsers
-- `point` / `rect` / `circle` / `ellipse` / `diamond` / `polar` — geometry
-- `BUILTIN_SHAPES` / `BUILTIN_ARROWS` / `BUILTIN_PATTERNS` + `ShapeDefinition` / `ArrowDefinition` / `PatternDefinition` / `definePathGenerator` — registries
-
-## Docs
-
-<https://pionpill.github.io/retikz/>
-
-## License
-
-MIT
+# @retikz/core
+
+Framework-agnostic core of [retikz](https://pionpill.github.io/retikz/) — a TikZ-inspired diagramming library. Provides the zod-typed **IR**, the **`compileToScene`** compiler, pure **parsers**, geometry helpers, and the shape / arrow / pattern / path-generator registries.
+
+零框架核心：retikz 的中间表示（IR）、`compileToScene` 编译器、纯解析器、几何工具与形状 / 箭头 / 图案 / 路径生成器注册面。**零 React、零 DOM**，运行时依赖只有 `zod`，IR 100% 可 JSON 序列化。
+
+## Install
+
+```bash
+pnpm add @retikz/core
+```
+
+## Usage
+
+`@retikz/core` is renderer-agnostic: it turns an IR into a serializable `Scene`. A backend (`@retikz/render`) or runtime (`@retikz/react` / `@retikz/vanilla`) then renders that Scene.
+
+```ts
+import { compileToScene } from '@retikz/core';
+
+const scene = compileToScene(ir);
+// optional: compileToScene(ir, { measureText, shapes, arrows, padding, ... })
+// hand `scene` to @retikz/render/svg, @retikz/render/canvas, or a runtime
+```
+
+Most users consume core indirectly through [`@retikz/react`](https://www.npmjs.com/package/@retikz/react) or [`@retikz/vanilla`](https://www.npmjs.com/package/@retikz/vanilla). Use core directly when you build IR programmatically, persist/transport scenes, or write a custom renderer.
+
+## Exports
+
+- `compileToScene` / `computeLayout` / `fallbackMeasurer` — IR → `Scene`
+- IR & `Scene` zod schemas + inferred types
+- `parseWay` / `parseNodeTarget` / `parseTargetSugar` — pure parsers
+- `point` / `rect` / `circle` / `ellipse` / `diamond` / `polar` — geometry
+- `BUILTIN_SHAPES` / `BUILTIN_ARROWS` / `BUILTIN_PATTERNS` + `ShapeDefinition` / `ArrowDefinition` / `PatternDefinition` / `definePathGenerator` — registries
+
+## Docs
+
+<https://pionpill.github.io/retikz/>
+
+## License
+
+MIT

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

@@ -1,15 +1,17 @@
 import { Side } from '../geometry/_edge';
-import { IRPosition } from '../ir';
+import { IRBoundary, IRPosition } from '../ir';
 import { NodeLayout } from './node';
 /**
  * 取节点 anchor 的全局坐标，带 per-layout 缓存
  * @description name 接受 RectAnchor 关键字（如 `'north'` / `'south-west'`）或数字角度字符串（如 `'30'` / `'-45'`）；
- *   同一 (layout, name) 第二次起返回首调用结果的**同一引用**——上游可用 `===` 判定 cache 命中
+ *   boundary 指定连接面（默认 `'shape'`，即节点自身视觉轮廓）；不同 boundary 产生独立缓存条目，互不串扰；
+ *   同一 (layout, name, boundary) 组合第二次起返回首调用结果的**同一引用**——上游可用 `===` 判定 cache 命中
  * @param layout 已 Pass 1 完成的 NodeLayout（rect 已是全局坐标）
  * @param anchorName 关键字或数字角度字符串
+ * @param boundary 连接面，缺省为 `'shape'`（视觉轮廓）
  * @returns 全局坐标系下的 IRPosition `[x, y]`
  */
-export declare const resolveAnchor: (layout: NodeLayout, anchorName: string) => IRPosition;
+export declare const resolveAnchor: (layout: NodeLayout, anchorName: string, boundary?: IRBoundary | undefined) => IRPosition;
 /**
  * 取节点边上比例点 `{ side, t }` 的全局坐标，带 per-layout 缓存
  * @description 走 `layout.shapeDef.edgePoint`——shape 未实现（如自定义 shape）抛"does not support side anchors"；

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,MAAM,OAAO,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AA4BzC;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,UAAU,EAClB,YAAY,MAAM,KACjB,UAWF,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,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"}

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

@@ -1,3 +1,4 @@
+import { boundaryKey } from "./boundary.js";
 import { anchorOf, angleBoundaryOf } from "./node.js";
 //#region src/compile/anchor-cache.ts
 /**
@@ -9,32 +10,35 @@ var cache = /* @__PURE__ */ new WeakMap();
 var ANGLE_RE = /^-?\d+(\.\d+)?$/;
 /**
 * 把 anchorName 解析到对应 shape 的 anchor / boundaryPoint 上
-* @description 数字字符串走 angleBoundaryOf；其余按 RectAnchor 走 anchorOf
+* @description 数字字符串走 angleBoundaryOf；其余按 RectAnchor 走 anchorOf；boundary 透传给两者
 */
-var computeAnchor = (layout, anchorName) => {
-	if (ANGLE_RE.test(anchorName)) return positionToIR(angleBoundaryOf(layout, Number(anchorName)));
-	return positionToIR(anchorOf(layout, anchorName));
+var computeAnchor = (layout, anchorName, boundary) => {
+	if (ANGLE_RE.test(anchorName)) return positionToIR(angleBoundaryOf(layout, Number(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'`）；
-*   同一 (layout, name) 第二次起返回首调用结果的**同一引用**——上游可用 `===` 判定 cache 命中
+*   boundary 指定连接面（默认 `'shape'`，即节点自身视觉轮廓）；不同 boundary 产生独立缓存条目，互不串扰；
+*   同一 (layout, name, boundary) 组合第二次起返回首调用结果的**同一引用**——上游可用 `===` 判定 cache 命中
 * @param layout 已 Pass 1 完成的 NodeLayout（rect 已是全局坐标）
 * @param anchorName 关键字或数字角度字符串
+* @param boundary 连接面，缺省为 `'shape'`（视觉轮廓）
 * @returns 全局坐标系下的 IRPosition `[x, y]`
 */
-var resolveAnchor = (layout, anchorName) => {
+var resolveAnchor = (layout, anchorName, boundary = "shape") => {
 	let layoutCache = cache.get(layout);
 	if (!layoutCache) {
 		layoutCache = /* @__PURE__ */ new Map();
 		cache.set(layout, layoutCache);
 	}
-	const cached = layoutCache.get(anchorName);
+	const key = `${boundaryKey(boundary)} ${anchorName}`;
+	const cached = layoutCache.get(key);
 	if (cached !== void 0) return cached;
-	const result = computeAnchor(layout, anchorName);
-	layoutCache.set(anchorName, result);
+	const result = computeAnchor(layout, anchorName, boundary);
+	layoutCache.set(key, result);
 	return result;
 };
 /**
@@ -57,7 +61,7 @@ var resolveEdgePoint = (layout, side, t) => {
 	const key = `${side}:${t}`;
 	const cached = layoutCache.get(key);
 	if (cached !== void 0) return cached;
-	const result = positionToIR(edgePoint(layout.rect, side, t));
+	const result = positionToIR(edgePoint(layout.rect, side, t, layout.shapeParams ?? {}));
 	layoutCache.set(key, result);
 	return result;
 };

package/dist/es/compile/boundary.d.ts

@@ -0,0 +1,19 @@
+import { Rect } from '../geometry/rect';
+import { IRBoundary } from '../ir';
+import { IRJsonObject } from '../ir/json';
+import { ShapeDefinition } from '../shapes';
+/**
+ * 把连接面取值解析为「计算 boundaryPoint / anchor 所需的 def + rect + params」
+ * @description layout-neutral：borrowed/builtin 一律喂目标节点的视觉 AABB rect，绝不调其 circumscribe。
+ *   保留字 'shape' → 视觉 def 原样；'circle' → ellipse def + squared-to-max rect；
+ *   保留字 'rectangle' / 'ellipse' → 对应内置 def + 视觉 AABB；其余 → registry 查表。
+ *   保留字优先于 registry 同名 shape。
+ */
+export declare const resolveBoundary: (boundary: IRBoundary | undefined, visualDef: ShapeDefinition, visualRect: Rect, visualParams: IRJsonObject, registry: Record<string, ShapeDefinition>) => {
+    def: ShapeDefinition;
+    rect: Rect;
+    params: IRJsonObject;
+};
+/** 连接面的稳定字符串判别（anchor cache key 用） */
+export declare const boundaryKey: (boundary: IRBoundary | undefined) => string;
+//# sourceMappingURL=boundary.d.ts.map

package/dist/es/compile/boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.d.ts","sourceRoot":"","sources":["../../../src/compile/boundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAcjD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,UAAU,GAAG,SAAS,EAChC,WAAW,eAAe,EAC1B,YAAY,IAAI,EAChB,cAAc,YAAY,EAC1B,UAAU,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,KACxC;IAAE,GAAG,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAuB1D,CAAC;AAEF,sCAAsC;AACtC,eAAO,MAAM,WAAW,GAAI,UAAU,UAAU,GAAG,SAAS,KAAG,MAI9D,CAAC"}

package/dist/es/compile/boundary.js

@@ -0,0 +1,64 @@
+import { ellipse } from "../shapes/ellipse.js";
+import { rectangle } from "../shapes/rectangle.js";
+//#region src/compile/boundary.ts
+/** 保留字：连接面 = 节点自身视觉形状 */
+var SELF = "shape";
+/** 保留字：真圆（半径 = AABB 较长半轴） */
+var CIRCLE = "circle";
+/** 把 rect 收成边长 = max(width, height) 的正方（中心 / rotate 不变）——circle 连接面用 */
+var squareToMax = (rect) => {
+	const side = Math.max(rect.width, rect.height);
+	return {
+		x: rect.x,
+		y: rect.y,
+		width: side,
+		height: side,
+		rotate: rect.rotate
+	};
+};
+/**
+* 把连接面取值解析为「计算 boundaryPoint / anchor 所需的 def + rect + params」
+* @description layout-neutral：borrowed/builtin 一律喂目标节点的视觉 AABB rect，绝不调其 circumscribe。
+*   保留字 'shape' → 视觉 def 原样；'circle' → ellipse def + squared-to-max rect；
+*   保留字 'rectangle' / 'ellipse' → 对应内置 def + 视觉 AABB；其余 → registry 查表。
+*   保留字优先于 registry 同名 shape。
+*/
+var resolveBoundary = (boundary, visualDef, visualRect, visualParams, registry) => {
+	if (boundary === void 0 || boundary === SELF) return {
+		def: visualDef,
+		rect: visualRect,
+		params: visualParams
+	};
+	if (boundary === CIRCLE) return {
+		def: ellipse,
+		rect: squareToMax(visualRect),
+		params: {}
+	};
+	if (boundary === "rectangle") return {
+		def: rectangle,
+		rect: visualRect,
+		params: {}
+	};
+	if (boundary === "ellipse") return {
+		def: ellipse,
+		rect: visualRect,
+		params: {}
+	};
+	const type = typeof boundary === "string" ? boundary : boundary.type;
+	const rawParams = typeof boundary === "string" ? {} : boundary.params ?? {};
+	const def = Object.prototype.hasOwnProperty.call(registry, type) ? registry[type] : void 0;
+	if (!def) throw new Error(`Unknown connection surface '${type}'; reserved: shape/circle, registered: ${Object.keys(registry).sort().join(", ")}`);
+	return {
+		def,
+		rect: visualRect,
+		params: def.paramsSchema.parse(rawParams)
+	};
+};
+/** 连接面的稳定字符串判别（anchor cache key 用） */
+var boundaryKey = (boundary) => {
+	if (boundary === void 0) return SELF;
+	if (typeof boundary === "string") return boundary;
+	return `${boundary.type}:${JSON.stringify(boundary.params ?? {})}`;
+};
+//#endregion
+export { boundaryKey, resolveBoundary };

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;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,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;AA+HF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAmWrE,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;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"}

package/dist/es/compile/compile.js

@@ -38,7 +38,8 @@ var zeroSizeRectAt = (id, [cx, cy]) => ({
 	textHeight: 0,
 	align: "middle",
 	lineHeight: 0,
-	fontSize: 0
+	fontSize: 0,
+	shapes: BUILTIN_SHAPES
 });
 /**
 * 把 coordinate 注册成 0×0 NodeLayout
@@ -77,6 +78,16 @@ var viewBoxToLayout = (vb, round) => {
 	};
 };
 /**
+* 自动算 layout 的 finite 守卫：四值非全 finite 即抛清晰错（LLM 可读），不泄漏进 Scene
+* @description computeLayout 由 `center ± halfWidth` 等运算聚合——极端 shape 几何（如 outerRadius:1e308
+*   半轴 finite 但 center+halfWidth 溢出 Infinity）会让运算结果脏。schema 的 `.finite()` 只守单字段输入，
+*   守不住聚合后的溢出；此处复用 viewBoxToLayout 同款 finite 关口，是自动 layout 进 Scene 前的唯一兜底。
+*/
+var assertFiniteLayout = (layout) => {
+	if (!Number.isFinite(layout.x) || !Number.isFinite(layout.y) || !Number.isFinite(layout.width) || !Number.isFinite(layout.height)) throw new Error(`Node layout produced non-finite bounds (x=${String(layout.x)}, y=${String(layout.y)}, width=${String(layout.width)}, height=${String(layout.height)}); check shape geometry (e.g. extreme radius).`);
+	return layout;
+};
+/**
 * 默认 warn dispatcher：dev 模式 console.warn、生产静默
 * @description 用户传 onWarn 时使用用户的；不传走此 fallback
 */
@@ -305,6 +316,7 @@ var compileToScene = (ir, options = {}) => {
 					children: stableSortByZIndex(sealSink(innerSink))
 				};
 				if (child.id !== void 0) group.id = child.id;
+				if (child.meta !== void 0) group.meta = child.meta;
 				if (hasOwnTransforms) group.transforms = [...ownTransforms];
 				if (child.clip !== void 0) group.clipRef = clip.resolve(child.clip);
 				sink.push(group);
@@ -339,7 +351,7 @@ var compileToScene = (ir, options = {}) => {
 	const resources = [...paint.resources(), ...clip.resources()];
 	return {
 		primitives: stableSortByZIndex(sealSink(primitives)),
-		layout: loweredIr.viewBox !== void 0 ? viewBoxToLayout(loweredIr.viewBox, round) : computeLayout(allPoints, layoutPadding, round),
+		layout: loweredIr.viewBox !== void 0 ? viewBoxToLayout(loweredIr.viewBox, round) : assertFiniteLayout(computeLayout(allPoints, layoutPadding, round)),
 		...resources.length > 0 ? { resources } : {}
 	};
 };

package/dist/es/compile/node.d.ts

@@ -1,6 +1,6 @@
 import { Position } from '../geometry/point';
 import { Rect } from '../geometry/rect';
-import { AtDirection, IRLabelDefault, IRNode, IRPaintSpec } from '../ir';
+import { AtDirection, IRBoundary, IRJsonObject, IRLabelDefault, IRNode, IRPaintSpec } from '../ir';
 import { PaintResolver } from './paint';
 import { ScenePrimitive, TextLine, Transform } from '../primitive';
 import { ShapeDefinition } from '../shapes';
@@ -14,6 +14,12 @@ export type NodeLayout = {
     shapeName: string;
     /** 已解析的 shape 定义；circumscribe / boundaryPoint / anchor / emit 多点复用，取代旧 switch */
     shapeDef: ShapeDefinition;
+    /**
+     * 已校验的 per-instance shape 参数（经 `paramsSchema.parse` + `JsonObjectSchema.parse` 双护栏）
+     * @description 透传给 `shapeDef` 的 circumscribe / boundaryPoint / anchor / edgePoint / emit；
+     *   无参形状（内置 4 个）解析为 `{}`。省略时各调用点以空对象兜底（合成 layout 如 coordinate / scope.id）。
+     */
+    shapeParams?: IRJsonObject;
     /**
      * 节点视觉边界框（所有 shape 共享语义）
      * @description rectangle: rect 本身；circle: width=height=2×radius；ellipse: 2×rx,2×ry；diamond: 2×halfA,2×halfB。x,y 是几何中心，rotate 弧度
@@ -57,7 +63,7 @@ export type NodeLayout = {
     /** 描边 dash pattern，已把 dashed/dotted 预设解析为具体 pattern */
     dashPattern?: Array<number>;
     /** rectangle 圆角半径（非 rect shape 无效） */
-    roundedCorners?: number;
+    cornerRadius?: number;
     /** 文字颜色，emit 时 'currentColor' 兜底 */
     textColor?: string;
     /** 整节点透明度 0~1（同时挂 shape 与 text primitive） */
@@ -67,6 +73,12 @@ export type NodeLayout = {
      * @description IR 层 `Node.label` 标准化：position 默认 'above'、distance 默认 DEFAULT_LABEL_DISTANCE、font 从 Node 继承
      */
     labels?: Array<NodeLabelLayout>;
+    /** 节点默认连接面（来自 IR `node.boundary`；undefined = 'shape'）；path 端点 boundary 可覆盖 */
+    boundary?: IRBoundary;
+    /** provenance 元数据（来自 IR `node.meta`）；emit 时原样 stamp 到 node 的 top-level 图元，renderer 忽略 */
+    meta?: IRJsonObject;
+    /** 构建本 layout 的 shape 注册表引用——借用连接面（borrowed boundary）查表用 */
+    shapes: Record<string, ShapeDefinition>;
 };
 /** 节点附属标签 layout（layoutNode 已合并默认值与样式继承） */
 export type NodeLabelLayout = {
@@ -96,20 +108,24 @@ export type NodeLabelLayout = {
 };
 /**
  * 取节点 shape 在 toward 方向的附着点（path 端点贴边用）
- * @description 走 shapeDef.boundaryPoint；margin > 0 时先膨胀外接 Rect，让 path 在 border 外停 margin
+ * @description 走连接面（boundary）对应的 def.boundaryPoint；margin > 0 时先膨胀外接 Rect，让 path 在 border 外停 margin。
+ *   boundary 缺省 = 'shape'（视觉形状自身），与改前行为一致。
  */
-export declare const boundaryPointOf: (layout: NodeLayout, toward: Position) => Position;
+export declare const boundaryPointOf: (layout: NodeLayout, toward: Position, boundary?: IRBoundary | undefined) => Position;
 /**
  * 取节点 shape 命名 anchor（center / north / east / north-east 等）
  * @description 不应用 margin——TikZ 语义中 explicit anchor 取视觉边界点不涉及 outer sep；用于 `'A.north'` 落点。
- *   shapeDef.anchor 不认识的名字返回 undefined，此处抛 Unknown anchor（列出 shape 名）
+ *   compass（9 个 rect 方位名）走连接面 AABB：'shape' 时归一为 'rectangle'（矩形 AABB），其余按 boundary 解析。
+ *   形状专属命名 anchor（tip-N / apex 等非 compass 名）恒走视觉形状自身，boundary 不影响。
+ *   boundary 缺省 = 'shape'，与改前 compass 走 AABB 行为一致（原 shapeDef.anchor 内部也走 rect AABB）。
  */
-export declare const anchorOf: (layout: NodeLayout, name: string) => Position;
+export declare const anchorOf: (layout: NodeLayout, name: string, boundary?: IRBoundary | undefined) => Position;
 /**
  * 取节点 shape 在指定角度方向的边界点
- * @description 角度是节点**局部坐标系**下的极角（度数：0°=局部 +x，90°=局部 +y）。layout.rect.rotate 把局部基绕中心旋转，得到世界系下的视觉方向；shape boundaryPoint 内部用 rotate-aware 投影，所以这里把局部 (cos, sin) 经 rect.rotate 旋转后加到中心当作世界系 toward 传入。不应用 margin（同 anchorOf）；用于 `'A.30'` 落点
+ * @description 角度是节点**局部坐标系**下的极角（度数：0°=局部 +x，90°=局部 +y）。layout.rect.rotate 把局部基绕中心旋转，得到世界系下的视觉方向；shape boundaryPoint 内部用 rotate-aware 投影，所以这里把局部 (cos, sin) 经 rect.rotate 旋转后加到中心当作世界系 toward 传入。不应用 margin（同 anchorOf）；用于 `'A.30'` 落点。
+ *   boundary 缺省 = 'shape'（视觉形状自身），与改前行为一致。
  */
-export declare const angleBoundaryOf: (layout: NodeLayout, angleDeg: number) => Position;
+export declare const angleBoundaryOf: (layout: NodeLayout, angleDeg: number, boundary?: IRBoundary | undefined) => Position;
 /**
  * IR Node → 内部 NodeLayout
  * @description 文本度量 + padding 推内框半轴；按 shape 算外接边界（circle 取半对角线、ellipse ×√2、diamond ×2）；解析 position 为几何中心；rotate 度数转弧度。

package/dist/es/compile/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/compile/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/compile/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAc,MAAM,EAAe,WAAW,EAAyB,MAAM,OAAO,CAAC;AAExJ,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAa,cAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,WAAW,CAAC;AAE7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,KAAK,oBAAoB,EAAmB,MAAM,YAAY,CAAC;AAExE,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAmI7D,MAAM,MAAM,UAAU,GAAG;IACvB,qBAAqB;IACrB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B;;;OAGG;IACH,IAAI,EAAE,IAAI,CAAC;IACX,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClC,iBAAiB;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS;IACT,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,SAAS;IACT,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,gBAAgB;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,yFAAyF;IACzF,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACzC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,QAAQ,EAAE,WAAW,GAAG,MAAM,CAAC;IAC/B,aAAa;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IAChD,+BAA+B;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,GAAG,CAAC,EAAE,OAAO,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC;CACxF,CAAC;AAQF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,UAAU,EAClB,QAAQ,QAAQ,EAChB,WAAU,UAAU,GAAG,SAAmB,KACzC,QASF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GACnB,QAAQ,UAAU,EAClB,MAAM,MAAM,EACZ,WAAU,UAAU,GAAG,SAAmB,KACzC,QAqBF,CAAC;AA8FF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,UAAU,EAClB,UAAU,MAAM,EAChB,WAAU,UAAU,GAAG,SAAmB,KACzC,QAoBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,aAAa,YAAY,EACzB,WAAW,SAAS,EACpB,eAAe,MAAM,EACrB,aAAY,aAAa,CAAC,SAAS,CAAM,EACzC,eAAe,cAAc,EAC7B,SAAQ,MAAM,CAAC,MAAM,EAAE,eAAe,CAAkB,EACxD,uBAAuB,oBAAoB,KAC1C,UAgNF,CAAC;AAcF;;;;GAIG;AACH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,UAAU,KAAG,KAAK,CAAC,QAAQ,CA6BpE,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,UAAU,EAClB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC5B,aAAa,aAAa,KACzB,KAAK,CAAC,cAAc,CAgItB,CAAC"}

package/dist/es/compile/node.js

@@ -1,9 +1,62 @@
+import { JsonObjectSchema } from "../ir/json.js";
+import { asRectAnchor } from "../shapes/_shared.js";
 import { BUILTIN_SHAPES } from "../shapes/index.js";
 import { resolvePosition } from "./position.js";
 import { toAlphabeticBaselineY } from "./text-baseline.js";
+import { resolveBoundary } from "./boundary.js";
 //#region src/compile/node.ts
 var DEFAULT_FONT_SIZE = 14;
 var DEFAULT_PADDING = 8;
+/** 无参 / 合成 layout 的 shape params 兜底（避免每次调用重建空对象） */
+var EMPTY_SHAPE_PARAMS = {};
+/**
+* 规范化 `Node.shape` 为 `{ type, params }`
+* @description 裸 string → `{ type, params: {} }`；`{ type, params? }` → params 缺省补 `{}`；
+*   缺省（undefined）→ `{ type: 'rectangle', params: {} }`。`'circle'`（裸 string）消解为
+*   `{ type: 'ellipse', params: { circumscribe: 'equal' } }`——circle 无独立几何，是 ellipse 等轴 preset 别名。
+*   `'diamond'`（裸 string）消解为 `{ type: 'polygon', params: { sides: 4, rotate: 45 } }`——diamond 无独立几何，
+*   是 polygon 4 边形（自旋 45°）preset 别名。仅做形态归一，不查表 / 不校验。
+*/
+var normalizeShape = (shape) => {
+	if (shape === void 0) return {
+		type: "rectangle",
+		params: {}
+	};
+	if (shape === "circle") return {
+		type: "ellipse",
+		params: { circumscribe: "equal" }
+	};
+	if (shape === "diamond") return {
+		type: "polygon",
+		params: {
+			sides: 4,
+			rotate: 45
+		}
+	};
+	if (typeof shape === "string") return {
+		type: shape,
+		params: {}
+	};
+	const ref = shape;
+	return {
+		type: ref.type,
+		params: ref.params ?? {}
+	};
+};
+/**
+* 递归把 JSON 值里所有数值叶子乘以 factor（数组 / 对象深入，string / boolean / null 原样）
+* @description 用于 shape params 随 node scale 协同缩放；输入已是 JSON-safe（双护栏过），输出仍 JSON-safe。
+*/
+var scaleJsonNumbers = (value, factor) => {
+	if (typeof value === "number") return value * factor;
+	if (Array.isArray(value)) return value.map((v) => scaleJsonNumbers(v, factor));
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) out[k] = scaleJsonNumbers(v, factor);
+		return out;
+	}
+	return value;
+};
 var DEFAULT_LINE_HEIGHT_FACTOR = 1.2;
 var DEG_TO_RAD = Math.PI / 180;
 /** CJK / fullwidth ranges: break per-character (no whitespace needed) */
@@ -73,16 +126,28 @@ var inflateRect = (r, m) => m === 0 ? r : {
 };
 /**
 * 取节点 shape 在 toward 方向的附着点（path 端点贴边用）
-* @description 走 shapeDef.boundaryPoint；margin > 0 时先膨胀外接 Rect，让 path 在 border 外停 margin
+* @description 走连接面（boundary）对应的 def.boundaryPoint；margin > 0 时先膨胀外接 Rect，让 path 在 border 外停 margin。
+*   boundary 缺省 = 'shape'（视觉形状自身），与改前行为一致。
 */
-var boundaryPointOf = (layout, toward) => layout.shapeDef.boundaryPoint(inflateRect(layout.rect, layout.margin), toward);
+var boundaryPointOf = (layout, toward, boundary = "shape") => {
+	const { def, rect, params } = resolveBoundary(boundary, layout.shapeDef, layout.rect, layout.shapeParams ?? EMPTY_SHAPE_PARAMS, layout.shapes);
+	return def.boundaryPoint(inflateRect(rect, layout.margin), toward, params);
+};
 /**
 * 取节点 shape 命名 anchor（center / north / east / north-east 等）
 * @description 不应用 margin——TikZ 语义中 explicit anchor 取视觉边界点不涉及 outer sep；用于 `'A.north'` 落点。
-*   shapeDef.anchor 不认识的名字返回 undefined，此处抛 Unknown anchor（列出 shape 名）
+*   compass（9 个 rect 方位名）走连接面 AABB：'shape' 时归一为 'rectangle'（矩形 AABB），其余按 boundary 解析。
+*   形状专属命名 anchor（tip-N / apex 等非 compass 名）恒走视觉形状自身，boundary 不影响。
+*   boundary 缺省 = 'shape'，与改前 compass 走 AABB 行为一致（原 shapeDef.anchor 内部也走 rect AABB）。
 */
-var anchorOf = (layout, name) => {
-	const p = layout.shapeDef.anchor(layout.rect, name);
+var anchorOf = (layout, name, boundary = "shape") => {
+	if (asRectAnchor(name) !== void 0) {
+		const { def, rect, params } = resolveBoundary(boundary === "shape" ? "rectangle" : boundary, layout.shapeDef, layout.rect, layout.shapeParams ?? EMPTY_SHAPE_PARAMS, layout.shapes);
+		const p = def.anchor(rect, name, params);
+		if (p === void 0) throw new Error(`Unknown anchor '${name}' for shape '${layout.shapeName}'`);
+		return p;
+	}
+	const p = layout.shapeDef.anchor(layout.rect, name, layout.shapeParams ?? EMPTY_SHAPE_PARAMS);
 	if (p === void 0) throw new Error(`Unknown anchor '${name}' for shape '${layout.shapeName}'`);
 	return p;
 };
@@ -187,9 +252,10 @@ var resolveLabelRotateDeg = (label, lx, ly, cx, cy) => {
 };
 /**
 * 取节点 shape 在指定角度方向的边界点
-* @description 角度是节点**局部坐标系**下的极角（度数：0°=局部 +x，90°=局部 +y）。layout.rect.rotate 把局部基绕中心旋转，得到世界系下的视觉方向；shape boundaryPoint 内部用 rotate-aware 投影，所以这里把局部 (cos, sin) 经 rect.rotate 旋转后加到中心当作世界系 toward 传入。不应用 margin（同 anchorOf）；用于 `'A.30'` 落点
+* @description 角度是节点**局部坐标系**下的极角（度数：0°=局部 +x，90°=局部 +y）。layout.rect.rotate 把局部基绕中心旋转，得到世界系下的视觉方向；shape boundaryPoint 内部用 rotate-aware 投影，所以这里把局部 (cos, sin) 经 rect.rotate 旋转后加到中心当作世界系 toward 传入。不应用 margin（同 anchorOf）；用于 `'A.30'` 落点。
+*   boundary 缺省 = 'shape'（视觉形状自身），与改前行为一致。
 */
-var angleBoundaryOf = (layout, angleDeg) => {
+var angleBoundaryOf = (layout, angleDeg, boundary = "shape") => {
 	const rad = angleDeg * Math.PI / 180;
 	const lx = Math.cos(rad);
 	const ly = Math.sin(rad);
@@ -197,7 +263,8 @@ var angleBoundaryOf = (layout, angleDeg) => {
 	const cosR = Math.cos(rot);
 	const sinR = Math.sin(rot);
 	const toward = [layout.rect.x + lx * cosR - ly * sinR, layout.rect.y + lx * sinR + ly * cosR];
-	return layout.shapeDef.boundaryPoint(layout.rect, toward);
+	const { def, rect, params } = resolveBoundary(boundary, layout.shapeDef, layout.rect, layout.shapeParams ?? EMPTY_SHAPE_PARAMS, layout.shapes);
+	return def.boundaryPoint(rect, toward, params);
 };
 /**
 * IR Node → 内部 NodeLayout
@@ -207,12 +274,20 @@ var angleBoundaryOf = (layout, angleDeg) => {
 *   笛卡尔字面量 `Position` 已在 scope 局部度量，行为延续 v0.1。
 */
 var layoutNode = (node, measureText, nameStack, nodeDistance, scopeChain = [], labelDefault, shapes = BUILTIN_SHAPES, resolveBetweenGlobal) => {
-	const shapeName = node.shape ?? "rectangle";
+	const { type: shapeName, params: rawShapeParams } = normalizeShape(node.shape);
 	const shapeDef = Object.prototype.hasOwnProperty.call(shapes, shapeName) ? shapes[shapeName] : void 0;
 	if (!shapeDef) throw new Error(`Unknown shape '${shapeName}'; registered shapes: ${Object.keys(shapes).sort().join(", ")}`);
+	JsonObjectSchema.parse(rawShapeParams);
+	const parsedShapeParams = shapeDef.paramsSchema.parse(rawShapeParams);
+	const mergedShapeParams = shapeName === "rectangle" && node.cornerRadius !== void 0 && !("cornerRadius" in parsedShapeParams) ? {
+		...parsedShapeParams,
+		cornerRadius: node.cornerRadius
+	} : parsedShapeParams;
 	const sx = node.xScale ?? node.scale ?? 1;
 	const sy = node.yScale ?? node.scale ?? 1;
 	const fontScale = Math.min(sx, sy);
+	const shapeScale = Math.sqrt(sx * sy);
+	const shapeParams = sx === 1 && sy === 1 ? mergedShapeParams : shapeDef.scaleParams ? shapeDef.scaleParams(mergedShapeParams, sx, sy) : scaleJsonNumbers(mergedShapeParams, shapeScale);
 	const baseFontSize = node.font?.size ?? DEFAULT_FONT_SIZE;
 	const fontSize = baseFontSize * fontScale;
 	const fontFamily = node.font?.family;
@@ -262,10 +337,13 @@ var layoutNode = (node, measureText, nameStack, nodeDistance, scopeChain = [], l
 	const minH = node.minimumHeight ?? node.minimumSize ?? 0;
 	const innerHalfW = Math.max(textWidth / 2 + xSep, xSep, minW / 2);
 	const innerHalfH = Math.max(textHeight / 2 + ySep, ySep, minH / 2);
-	const { halfWidth: boundsHalfW, halfHeight: boundsHalfH } = shapeDef.circumscribe(innerHalfW, innerHalfH);
+	const { halfWidth: boundsHalfW, halfHeight: boundsHalfH } = shapeDef.circumscribe(innerHalfW, innerHalfH, shapeParams);
 	const rotateDeg = node.rotate ?? 0;
 	const center = resolvePosition(node.position, nameStack, nodeDistance, scopeChain, resolveBetweenGlobal);
 	if (!center) throw new Error(`Cannot resolve position for node ${node.id ?? "(unnamed)"}; polar.origin / at.of / between endpoint may reference an undefined node`);
+	const aabbOffset = shapeDef.circumscribeOffset?.(shapeParams);
+	const rectCenterX = center[0] + (aabbOffset?.[0] ?? 0);
+	const rectCenterY = center[1] + (aabbOffset?.[1] ?? 0);
 	const labels = (node.label === void 0 ? void 0 : Array.isArray(node.label) ? node.label : [node.label])?.map((lab) => {
 		const labFont = lab.font;
 		const labFontSize = (labFont?.size ?? labelDefault?.font?.size ?? baseFontSize) * fontScale;
@@ -297,9 +375,10 @@ var layoutNode = (node, measureText, nameStack, nodeDistance, scopeChain = [], l
 		id: node.id,
 		shapeName,
 		shapeDef,
+		shapeParams,
 		rect: {
-			x: center[0],
-			y: center[1],
+			x: rectCenterX,
+			y: rectCenterY,
 			width: 2 * boundsHalfW,
 			height: 2 * boundsHalfH,
 			rotate: rotateDeg * DEG_TO_RAD
@@ -321,10 +400,13 @@ var layoutNode = (node, measureText, nameStack, nodeDistance, scopeChain = [], l
 		strokeOpacity: node.drawOpacity,
 		strokeWidth: node.strokeWidth,
 		dashPattern: resolveDashArray(node.dashArray, node.dashed, node.dotted),
-		roundedCorners: node.roundedCorners,
+		cornerRadius: node.cornerRadius,
 		textColor: node.textColor,
 		opacity: node.opacity,
-		labels
+		labels,
+		boundary: node.boundary,
+		meta: node.meta,
+		shapes
 	};
 };
 /** 从 NodeLayout 收敛 emit 所需的视觉样式子集（ShapeStyle，不含几何 / 文本）；fill 经 resolveFill 转 PaintValue */
@@ -335,7 +417,7 @@ var toShapeStyle = (layout, resolveFill) => ({
 	strokeOpacity: layout.strokeOpacity,
 	strokeWidth: layout.strokeWidth,
 	dashPattern: layout.dashPattern,
-	roundedCorners: layout.roundedCorners,
+	cornerRadius: layout.cornerRadius,
 	opacity: layout.opacity
 });
 /**
@@ -380,7 +462,7 @@ var emitNodePrimitives = (layout, round, resolveFill) => {
 		...layout.rect,
 		rotate: 0
 	};
-	const shapePrims = [...layout.shapeDef.emit(axisAlignedRect, toShapeStyle(layout, resolveFill), round)];
+	const shapePrims = [...layout.shapeDef.emit(axisAlignedRect, toShapeStyle(layout, resolveFill), round, layout.shapeParams ?? EMPTY_SHAPE_PARAMS)];
 	const inner = [...shapePrims];
 	if (layout.lines) {
 		const halfBlockW = layout.textWidth / 2;
@@ -463,6 +545,7 @@ var emitNodePrimitives = (layout, round, resolveFill) => {
 	}
 	if (!(layout.rotateDeg !== 0 || layout.lines !== void 0)) {
 		if (layout.id !== void 0) for (const prim of shapePrims) prim.id = layout.id;
+		if (layout.meta !== void 0) for (const prim of shapePrims) prim.meta = layout.meta;
 		return inner;
 	}
 	const group = {
@@ -470,6 +553,7 @@ var emitNodePrimitives = (layout, round, resolveFill) => {
 		children: inner
 	};
 	if (layout.id !== void 0) group.id = layout.id;
+	if (layout.meta !== void 0) group.meta = layout.meta;
 	if (layout.rotateDeg !== 0) group.transforms = [{
 		kind: "rotate",
 		degrees: round(layout.rotateDeg),

package/dist/es/compile/path/anchor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAyB/C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,QAAQ,EAChB,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,UAAU,GAAG,IA8Bf,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,GACnB,MAAM,UAAU,EAChB,MAAM,UAAU,EAChB,KAAK,IAAI,GAAG,IAAI,KACf,UACqD,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,QAAQ,EAChB,QAAQ,UAAU,EAClB,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,UAAU,GAAG,IAsBf,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,GAAG,IAAI,EAAE,GAAG,UAAU,GAAG,IAAI,KAAG,OACzB,CAAC;AAE/C,6BAA6B;AAC7B,eAAO,MAAM,WAAW,GAAI,GAAG,UAAU,EAAE,QAAQ,UAAU,EAAE,MAAM,MAAM,KAAG,UAM7E,CAAC"}
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AA6B/C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,QAAQ,EAChB,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,UAAU,GAAG,IA8Bf,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,GACnB,MAAM,UAAU,EAChB,MAAM,UAAU,EAChB,KAAK,IAAI,GAAG,IAAI,KACf,UACqD,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,QAAQ,EAChB,QAAQ,UAAU,EAClB,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,UAAU,GAAG,IAuBf,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,GAAG,IAAI,EAAE,GAAG,UAAU,GAAG,IAAI,KAAG,OACzB,CAAC;AAE/C,6BAA6B;AAC7B,eAAO,MAAM,WAAW,GAAI,GAAG,UAAU,EAAE,QAAQ,UAAU,EAAE,MAAM,MAAM,KAAG,UAM7E,CAAC"}