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

package/dist/es/shapes/star.js

@@ -0,0 +1,113 @@
+import { localToWorld } from "../geometry/_transform.js";
+import { defineShape } from "./define.js";
+import { boundaryFromContour, contourCommands } from "../geometry/roundedContour.js";
+import { contourToPathCommands, verticesToSegments } from "./_contour.js";
+import { z } from "zod";
+//#region src/shapes/star.ts
+var DEG_TO_RAD = Math.PI / 180;
+/**
+* 计算 star 单一真源几何
+* @description 局部系以中心为原点：顶点 k 角 = (rotate ?? 0) + k·(180/points) − 90，半径偶 outer / 奇 inner，
+*   point = [r·cosθ, r·sinθ]（0°=+x，90°=+y screen y-down）。−90 基准使默认第一尖角朝上（−y）。
+*   AABB 半轴 = 各顶点 |x| / |y| 的最大值（对称 → 中心即原点）。
+*/
+var starGeometry = (params) => {
+	const { points, innerRadius, outerRadius } = params;
+	const rotate = params.rotate ?? 0;
+	const step = 180 / points;
+	const vertices = [];
+	let maxAbsX = 0;
+	let maxAbsY = 0;
+	for (let k = 0; k < 2 * points; k++) {
+		const angle = (rotate + k * step - 90) * DEG_TO_RAD;
+		const radius = k % 2 === 0 ? outerRadius : innerRadius;
+		const x = radius * Math.cos(angle);
+		const y = radius * Math.sin(angle);
+		vertices.push([x, y]);
+		if (Math.abs(x) > maxAbsX) maxAbsX = Math.abs(x);
+		if (Math.abs(y) > maxAbsY) maxAbsY = Math.abs(y);
+	}
+	return {
+		vertices,
+		aabbHalfAxes: {
+			halfWidth: maxAbsX,
+			halfHeight: maxAbsY
+		}
+	};
+};
+/** 局部顶点（中心为原点）→ 世界系（经 rect 旋转 / 平移） */
+var toWorld = (rect, local) => localToWorld(rect, local);
+/**
+* 世界系顶点环（局部 2×points 顶点逐个经 rect 投世界）
+* @description emit 收轴对齐 rect（rotate=0）、boundaryPoint 收带 rotate 的 rect，二者共用此构造；
+*   绕向 = starGeometry 顶点顺序（偶尖 / 奇凹交替），供 verticesToSegments → rounded-contour 模块倒角。
+*/
+var worldVertices = (rect, geo) => geo.vertices.map((v) => toWorld(rect, v));
+/**
+* star 注册项：星形（外径尖角 / 内径凹角交替的 2×points 顶点闭合多边形）
+* @description params-半径驱动的纯几何形状（像 sector，尺寸由 outerRadius 定、忽略文本内框）：四何函数共用
+*   `starGeometry`（单一真源）。circumscribe 返回含全部尖角的精确 AABB 半轴（随 rotate 变，不随 cornerRadius 变）；
+*   星形关于中心对称 → AABB 中心 = 星形中心 = node position，无需 circumscribeOffset。emit / boundaryPoint 把
+*   `2×points` 顶点环构造成折线段，委托 rounded-contour 模块：cornerRadius 省略 / 0 出原尖角轮廓、>0 在每个顶点
+*   插逐角夹紧的 fillet 弧——凸尖与凹角（notch）由模块按接缝转向叉积统一处理（凹角弧 sweep 反向、圆心在凸侧），
+*   emit 与 boundaryPoint 共用同一份 fillet 结果。emit 收轴对齐 rect（旋转由外层 group 施加）、boundaryPoint
+*   收带 rotate 的 rect 且 rayOrigin = 星形几何中心（关于中心对称，AABB 中心 = 形心 = node position）。
+*   anchor 含 center / tip-N（第 N 尖角）/ notch-N（第 N 凹角）——恒在原尖角 / 凹角逻辑顶点，不随 cornerRadius 移；
+*   self-rotate（params.rotate）与 Node.rotate 叠加。scaleParams 只缩 inner/outerRadius / cornerRadius（长度）、
+*   不缩 points（计数）/ rotate（角度）。
+*/
+var star = defineShape({
+	paramsSchema: z.strictObject({
+		points: z.number().int().min(3).describe("Number of star points (>= 3)."),
+		innerRadius: z.number().finite().positive().describe("Inner (notch) radius in user units."),
+		outerRadius: z.number().finite().positive().describe("Outer (tip) radius in user units; must be > innerRadius."),
+		rotate: z.number().finite().optional().describe("Shape self-rotation in degrees; default 0 = first tip points up (screen -y / top); positive rotates clockwise (screen). Composes with Node.rotate."),
+		cornerRadius: z.number().finite().nonnegative().optional().describe("Corner radius in user units; 0 / omitted = sharp corners. Clamped per corner to the largest non-self-intersecting fillet.")
+	}).refine((p) => p.outerRadius > p.innerRadius, { message: "outerRadius must be greater than innerRadius" }),
+	circumscribe: (_hw, _hh, params) => starGeometry(params).aabbHalfAxes,
+	boundaryPoint: (rect, toward, params) => {
+		const segments = verticesToSegments(worldVertices(rect, starGeometry(params)));
+		const center = toWorld(rect, [0, 0]);
+		return boundaryFromContour(segments, params.cornerRadius, center, toward) ?? center;
+	},
+	anchor: (rect, name, params) => {
+		const geo = starGeometry(params);
+		if (name === "center") return toWorld(rect, [0, 0]);
+		const tip = /^tip-(\d+)$/.exec(name);
+		if (tip) {
+			const index = 2 * Number(tip[1]);
+			if (index >= geo.vertices.length) return void 0;
+			return toWorld(rect, geo.vertices[index]);
+		}
+		const notch = /^notch-(\d+)$/.exec(name);
+		if (notch) {
+			const index = 2 * Number(notch[1]) + 1;
+			if (index >= geo.vertices.length) return void 0;
+			return toWorld(rect, geo.vertices[index]);
+		}
+	},
+	*emit(rect, style, round, params) {
+		yield {
+			type: "path",
+			commands: contourToPathCommands(contourCommands(verticesToSegments(worldVertices(rect, starGeometry(params))), params.cornerRadius), round),
+			fill: style.fill ?? "transparent",
+			fillOpacity: style.fillOpacity,
+			stroke: style.stroke ?? "currentColor",
+			strokeOpacity: style.strokeOpacity,
+			strokeWidth: style.strokeWidth ?? 1,
+			dashPattern: style.dashPattern,
+			opacity: style.opacity
+		};
+	},
+	scaleParams: (params, sx, sy) => {
+		const factor = Math.sqrt(sx * sy);
+		return {
+			...params,
+			innerRadius: params.innerRadius * factor,
+			outerRadius: params.outerRadius * factor,
+			...params.cornerRadius === void 0 ? {} : { cornerRadius: params.cornerRadius * factor }
+		};
+	}
+});
+//#endregion
+export { star };

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

@@ -1,5 +1,7 @@
+import { z } from 'zod';
 import { Position } from '../geometry/point';
 import { Rect } from '../geometry/rect';
+import { IRJsonObject } from '../ir/json';
 import { PaintValue, ScenePrimitive } from '../primitive';
 /**
  * emit 需要的视觉样式子集
@@ -13,38 +15,69 @@ export type ShapeStyle = {
     strokeOpacity?: number;
     strokeWidth?: number;
     dashPattern?: Array<number>;
-    roundedCorners?: number;
+    cornerRadius?: number;
     opacity?: number;
 };
 /**
- * 一个 shape 的可注册定义：外接 / 边界 / anchor / emit 四件事
- * @description plain object（factory 友好：`createPolygonShape(6)` 这类普通函数返回它即可）；含函数、
- *   **不进 IR**，走 `CompileOptions.shapes` 运行时注入。内置 4 shape 也是注册项（无内置特权）。
+ * 一个 shape 的参数化可注册定义（定义点 typed 形态）
+ * @description plain object（factory 友好：`createPolygonShape(6)` 这类普通函数返回它即可）；含函数与
+ *   `paramsSchema`，**不进 IR**，走 `CompileOptions.shapes` 运行时注入。内置 4 shape 也是注册项（无内置特权）。
+ *   每个计算函数末位收 per-instance `params`（类型由 `paramsSchema.parse` 在编译期保证），无参形状用
+ *   `z.strictObject({})` 并忽略 `params`。
+ *
+ *   - `paramsSchema`：类型约束输出 JSON-safe（`z.ZodType<TParams>`）。这是类型层约束，不是运行时唯一保证——
+ *     compile 在 `paramsSchema.parse(params)` 之后还会对结果跑一次 `JsonObjectSchema.parse`，拦下宽松
+ *     schema 放过的非 JSON 输出（function / undefined 等）。
  *
  *   坐标语义两套，第三方最易写错：
  *   - `boundaryPoint` / `anchor` 收**带 `rotate` 的 Rect**——用 re-export 的 `worldToLocal` / `localToWorld` 写局部系几何。
  *   - `emit` 收**轴对齐 Rect（rotate=0）**——旋转由编译器在外层 `GroupPrim` 统一施加。
  */
-export type ShapeDefinition = {
+export type ShapeDefinitionInput<TParams extends IRJsonObject> = {
+    /** params 的 zod schema；类型约束输出 JSON-safe（运行时双 parse 才是真正护栏，见编译期桥接） */
+    paramsSchema: z.ZodType<TParams>;
     /**
-     * 外接：内容半轴（text + padding）→ 外接框半轴。
-     * @description rectangle: identity；circle: √(hw²+hh²) 两轴相等；ellipse: ×√2；diamond: ×2。
+     * 外接：内容半轴（text + padding）+ params → 外接框半轴。
+     * @description 必返回**包含完整 shape 的精确 AABB 半轴**（compile 的 viewBox / scope bbox 只累积该 AABB
+     *   四角）。rectangle: identity；circle: √(hw²+hh²) 两轴相等；ellipse: ×√2；diamond: ×2；参数化形状据 params 算。
      */
-    circumscribe: (innerHalfWidth: number, innerHalfHeight: number) => {
+    circumscribe: (innerHalfWidth: number, innerHalfHeight: number, params: TParams) => {
         halfWidth: number;
         halfHeight: number;
     };
-    /** 中心 → toward 射线 ∩ 边界（rect 带 rotate）。 */
-    boundaryPoint: (rect: Rect, toward: Position) => Position;
+    /**
+     * AABB 中心相对 node `position` 的偏移（可选；缺省 `[0, 0]` = AABB 中心即 position）。
+     * @description 多数 shape 的视觉 AABB 以 position 为中心（rectangle / ellipse / diamond）；但 sector 等
+     *   形状的语义锚点（圆心 apex）才是 position，其外接 AABB 中心偏在一侧——此 hook 让 compile 把
+     *   `rect.center` 放到 `position + offset`，使 bbox / viewBox 罩住完整形状、anchor 以 AABB 中心 rect 计算时
+     *   apex 落回 position。返回**未旋转**局部偏移（compile 在施加 node rotate 前用于定位 rect 中心）。
+     */
+    circumscribeOffset?: (params: TParams) => Position;
+    /** 中心 → toward 射线 ∩ 边界（rect 带 rotate）；params 喂参数化边界。 */
+    boundaryPoint: (rect: Rect, toward: Position, params: TParams) => Position;
     /** 命名 anchor 世界坐标；shape 不认识的名字返回 `undefined`（调用方据此抛清晰错误）。 */
-    anchor: (rect: Rect, name: string) => Position | undefined;
+    anchor: (rect: Rect, name: string, params: TParams) => Position | undefined;
     /**
      * 边上比例点：side 真实边界从约定起点起 t∈[0,1] 处（轴对齐空间求出后由 layout 投回世界系）。
      * @description 可选——内置 4 shape 必实现，不实现的 shape 收到 `{ side, t }` 时编译期（resolveEdgePoint）抛明确错。
      *   与 `anchor` 同坐标语义：收**带 rotate 的 Rect**，自行用 worldToLocal/localToWorld 处理旋转。
      */
-    edgePoint?: (rect: Rect, side: 'north' | 'south' | 'east' | 'west', t: number) => Position;
-    /** 视觉 primitive，**轴对齐空间**（rotate 由编译器外层 GroupPrim 统一施加）。 */
-    emit: (rect: Rect, style: ShapeStyle, round: (n: number) => number) => Iterable<ScenePrimitive>;
+    edgePoint?: (rect: Rect, side: 'north' | 'south' | 'east' | 'west', t: number, params: TParams) => Position;
+    /** 视觉 primitive，**轴对齐空间**（rotate 由编译器外层 GroupPrim 统一施加）；params 喂参数化几何。 */
+    emit: (rect: Rect, style: ShapeStyle, round: (n: number) => number, params: TParams) => Iterable<ScenePrimitive>;
+    /**
+     * node scale 作用于 params 的方式（可选）。
+     * @description 给定原始 params 与水平 / 垂直缩放因子 `sx` / `sy`，返回缩放后的 params。
+     *   缺省时编译器沿用默认行为——深度缩放 params 里所有数值叶子（uniform 几何均值因子）。
+     *   适用于 params 含「非长度」语义字段（如角度）的形状：sector / arc 只缩半径、不缩角度，
+     *   通过本 hook 把 startAngle / endAngle 排除在缩放外。不缩放任何 params 的形状不必实现。
+     */
+    scaleParams?: (params: TParams, sx: number, sy: number) => TParams;
 };
+/**
+ * shape 定义的擦除形态：registry 存这个
+ * @description 所有函数收 `IRJsonObject`（实际类型由 `paramsSchema.parse` 在编译期保证）；registry 同构
+ *   `Record<string, ShapeDefinition>`、不泛型化（避免逆变 / 落 any）。定义点用 `defineShape<TParams>` 拿类型安全。
+ */
+export type ShapeDefinition = ShapeDefinitionInput<IRJsonObject>;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shapes/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,YAAY,EAAE,CACZ,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,KACpB;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,0CAA0C;IAC1C,aAAa,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,KAAK,QAAQ,CAAC;IAC1D,6DAA6D;IAC7D,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IAC3D;;;;OAIG;IACH,SAAS,CAAC,EAAE,CACV,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,EACzC,CAAC,EAAE,MAAM,KACN,QAAQ,CAAC;IACd,4DAA4D;IAC5D,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAAK,QAAQ,CAAC,cAAc,CAAC,CAAC;CACjG,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shapes/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,CAAC,OAAO,SAAS,YAAY,IAAI;IAC/D,qEAAqE;IACrE,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC;;;;OAIG;IACH,YAAY,EAAE,CACZ,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,OAAO,KACZ;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ,CAAC;IACnD,wDAAwD;IACxD,aAAa,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,KAAK,QAAQ,CAAC;IAC3E,6DAA6D;IAC7D,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,QAAQ,GAAG,SAAS,CAAC;IAC5E;;;;OAIG;IACH,SAAS,CAAC,EAAE,CACV,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,EACzC,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,OAAO,KACZ,QAAQ,CAAC;IACd,0EAA0E;IAC1E,IAAI,EAAE,CACJ,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC5B,MAAM,EAAE,OAAO,KACZ,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC9B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CACpE,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC"}

package/dist/lib/compile/anchor-cache.cjs

@@ -1,3 +1,4 @@
+const require_boundary = require("./boundary.cjs");
 const require_node = require("./node.cjs");
 //#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(require_node.angleBoundaryOf(layout, Number(anchorName)));
-	return positionToIR(require_node.anchorOf(layout, anchorName));
+var computeAnchor = (layout, anchorName, boundary) => {
+	if (ANGLE_RE.test(anchorName)) return positionToIR(require_node.angleBoundaryOf(layout, Number(anchorName), boundary));
+	return positionToIR(require_node.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 = `${require_boundary.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/lib/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/lib/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/lib/compile/boundary.cjs

@@ -0,0 +1,65 @@
+const require_ellipse = require("../shapes/ellipse.cjs");
+const require_rectangle = require("../shapes/rectangle.cjs");
+//#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: require_ellipse.ellipse,
+		rect: squareToMax(visualRect),
+		params: {}
+	};
+	if (boundary === "rectangle") return {
+		def: require_rectangle.rectangle,
+		rect: visualRect,
+		params: {}
+	};
+	if (boundary === "ellipse") return {
+		def: require_ellipse.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
+exports.boundaryKey = boundaryKey;
+exports.resolveBoundary = resolveBoundary;

package/dist/lib/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/lib/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/lib/compile/compile.cjs

@@ -38,7 +38,8 @@ var zeroSizeRectAt = (id, [cx, cy]) => ({
 	textHeight: 0,
 	align: "middle",
 	lineHeight: 0,
-	fontSize: 0
+	fontSize: 0,
+	shapes: require_index.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
 */
@@ -304,6 +315,8 @@ var compileToScene = (ir, options = {}) => {
 					type: "group",
 					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);
@@ -338,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) : require_layout.computeLayout(allPoints, layoutPadding, round),
+		layout: loweredIr.viewBox !== void 0 ? viewBoxToLayout(loweredIr.viewBox, round) : assertFiniteLayout(require_layout.computeLayout(allPoints, layoutPadding, round)),
 		...resources.length > 0 ? { resources } : {}
 	};
 };

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;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,KAiWrE,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"}