@retikz/core 0.2.0-alpha.1 → 0.2.0-alpha.3

package/dist/es/ir/scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/ir/scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,aAAa,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAChC,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,CAAC;CAC3D,CAAC;AAOF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,CAAC,CAAC,UAAU,KAAG,IAE5D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyCrB,CAAC"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/ir/scope.ts"],"names":[],"mappings":"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmGrB,CAAC"}

package/dist/es/ir/scope.js

@@ -1,6 +1,47 @@
+import { FontSchema } from "./font.js";
+import { ArrowDetailSchema } from "./path/arrow.js";
+import { PathSchema } from "./path/path.js";
+import { NodeSchema } from "./node.js";
 import { TransformSchema } from "./transform.js";
 import { z } from "zod";
 //#region src/ir/scope.ts
+/**
+* every node 默认样式 schema
+* @description 从 NodeSchema 派生，排除实例专属字段（type / id / position / text / label）；
+*   含形状 / 间距 / scale / rotate / color 等所有可作默认的 node 样式字段
+*/
+var NodeDefaultSchema = NodeSchema.omit({
+	type: true,
+	id: true,
+	position: true,
+	text: true,
+	label: true
+}).strict();
+/**
+* every path 默认样式 schema
+* @description 从 PathSchema 派生，排除 type / children / arrow / arrowDetail（arrow 走独立 arrowDefault 通道，免双入口）
+*/
+var PathDefaultSchema = PathSchema.omit({
+	type: true,
+	children: true,
+	arrow: true,
+	arrowDetail: true
+}).strict();
+/**
+* every label 默认样式 schema（node label 与 step label 共享）
+* @description 单通道双宿主：node-label 跟 node.color、step-label 跟 path.color；本 schema 只定义可继承的 label 样式字段
+*/
+var LabelDefaultSchema = z.object({
+	color: z.string().optional().describe("Master color for labels in this scope; textColor falls back to it."),
+	textColor: z.string().optional().describe("Default text color for node labels and step labels in this scope."),
+	opacity: z.number().min(0).max(1).optional().describe("Default label opacity 0..1."),
+	font: FontSchema.optional().describe("Default label font (family / size / weight / style); per-field fallback.")
+}).strict().describe("Default style applied to every label (node label + step label) in this scope (TikZ `every label`). All fields optional; unknown keys are rejected.");
+/**
+* every arrow 默认样式 schema
+* @description 直接复用 ArrowDetailSchema（shape / scale / length / width / color / fill / opacity / lineWidth + start / end）
+*/
+var ArrowDefaultSchema = ArrowDetailSchema;
 /** schema 注册顺序：scene.ts import 时由 __registerChildSchema 一次性回灌；之后只读 */
 var childSchemaRef = null;
 /**
@@ -11,19 +52,38 @@ var __registerChildSchema = (schema) => {
 	childSchemaRef = schema;
 };
 /**
-* Scope schema：4 IRScope 字段
+* Scope schema：容器 + 局部 transform + 样式默认挂点
 * @description 直接 `z.object` 让 ChildSchema discriminatedUnion 能识别 `type` 鉴别字段；
-* children 字段内部用 z.lazy 引用 ChildSchema 实现递归，避免直接 `z.lazy(() => z.object(...))` 让外层 union 拒识 type
+* children 字段内部用 z.lazy 引用 ChildSchema 实现递归，避免直接 `z.lazy(() => z.object(...))` 让外层 union 拒识 type。
+* alpha.2 加：① 级联 graphic state（color + stroke / fill / strokeWidth / opacity / fillOpacity / drawOpacity）；
+* ② 四通道 every-X 默认（nodeDefault / pathDefault / labelDefault / arrowDefault）；③ resetStyle 继承屏障。
 */
 var ScopeSchema = z.object({
 	type: z.literal("scope").describe("Discriminator marking this child as a scope container."),
 	id: z.string().min(1).optional().describe("Optional reference id; when set, the scope registers a synthetic rectangle bbox node in the **parent** namespace frame so paths / positions can target the scope as a whole. scope.id always registers in the parent frame, regardless of `localNamespace` (it is the external handle)."),
 	localNamespace: z.boolean().optional().describe("When true, the scope creates a local namespace boundary — child node / coordinate / nested-scope ids registered inside do NOT propagate to the parent namespace; external lookups cannot see them. Default false (matches TikZ pgf default: child ids flow up to global). scope.id itself always registers in the parent frame regardless of this flag."),
 	transforms: z.array(TransformSchema).optional().describe("Local transforms applied to all scope children; array order = application order (first element applied innermost, matching Scene `GroupPrim.transforms` / SVG transform list). Supports 6 variants; the 4 translate variants are lowered to Cartesian translate at compile time."),
+	color: z.string().optional().describe("Cascading master color for all elements in this scope (TikZ scope `color=`). Stroke / fill / text of inner elements default to it unless individually overridden; cascades into edge labels and arrows."),
+	stroke: z.string().optional().describe("Cascading default stroke color for inner nodes and paths; overrides the cascading master color for the stroke channel."),
+	fill: z.string().optional().describe("Cascading default fill color for inner nodes and paths."),
+	strokeWidth: z.number().optional().describe("Cascading default stroke width (user units) for inner nodes and paths."),
+	opacity: z.number().min(0).max(1).optional().describe("Cascading default whole-element opacity 0..1. Replaces (does NOT compound across nested scopes — TikZ default)."),
+	fillOpacity: z.number().min(0).max(1).optional().describe("Cascading default fill opacity 0..1 for inner nodes and paths."),
+	drawOpacity: z.number().min(0).max(1).optional().describe("Cascading default stroke opacity 0..1 (TikZ `draw opacity`) for inner nodes and paths."),
+	nodeDefault: NodeDefaultSchema.optional().describe("Default style applied to every node in this scope (TikZ `every node`). Flat channel, independent from the other defaults."),
+	pathDefault: PathDefaultSchema.optional().describe("Default style applied to every path in this scope (TikZ `every path`); arrows use the separate arrowDefault channel."),
+	labelDefault: LabelDefaultSchema.optional().describe("Default style applied to every label (node label + step label) in this scope (TikZ `every label`)."),
+	arrowDefault: ArrowDefaultSchema.optional().describe("Default style applied to every arrow in this scope (TikZ `every arrow`)."),
+	resetStyle: z.union([z.boolean(), z.array(z.enum([
+		"node",
+		"path",
+		"label",
+		"arrow"
+	]))]).optional().describe("Inheritance barrier: drop the outer scope cascade + every-X defaults for the listed channels (or all when true), falling back to the built-in baseline. Only cuts the scope-inheritance axis; labels / arrows still follow their host path / node resolved color (structural relation, not scope inheritance)."),
 	children: z.array(z.lazy(() => {
 		if (!childSchemaRef) throw new Error("ScopeSchema: ChildSchema not registered yet; ensure scene.ts loaded");
 		return childSchemaRef;
 	})).describe("Scope children: nested nodes / paths / coordinates / scopes. Recursive via the parent ChildSchema (registered late to break the IRChild <-> IRScope cycle).")
-}).describe("Scope container: groups child IR elements and applies local transforms. Corresponds to TikZ `\\begin{scope}` (with optional `local bounding box=id` when id is set, and `name prefix`-like isolation when localNamespace is true).");
+}).describe("Scope container: groups child IR elements, applies local transforms, and acts as a style-default anchor (cascading graphic state + every-X defaults + resetStyle barrier). Corresponds to TikZ `\\begin{scope}`.");
 //#endregion
-export { ScopeSchema, __registerChildSchema };
+export { ArrowDefaultSchema, LabelDefaultSchema, NodeDefaultSchema, PathDefaultSchema, ScopeSchema, __registerChildSchema };

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

@@ -0,0 +1,7 @@
+import { RectAnchor } from '../geometry/rect';
+/**
+ * 把任意字符串收窄为合法 RectAnchor，否则 undefined
+ * @description 内置 4 shape 的 anchor 只认这 9 名；不在集合内返回 undefined，由 `anchorOf` 抛 Unknown anchor
+ */
+export declare const asRectAnchor: (name: string) => RectAnchor | undefined;
+//# sourceMappingURL=_shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../src/shapes/_shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKjE;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,UAAU,GAAG,SACK,CAAC"}

package/dist/es/shapes/_shared.js

@@ -0,0 +1,11 @@
+import { RECT_ANCHORS } from "../geometry/rect.js";
+//#region src/shapes/_shared.ts
+/** RECT_ANCHORS 的 9 个合法 anchor 名集合（成员校验用） */
+var RECT_ANCHOR_SET = new Set(Object.values(RECT_ANCHORS));
+/**
+* 把任意字符串收窄为合法 RectAnchor，否则 undefined
+* @description 内置 4 shape 的 anchor 只认这 9 名；不在集合内返回 undefined，由 `anchorOf` 抛 Unknown anchor
+*/
+var asRectAnchor = (name) => RECT_ANCHOR_SET.has(name) ? name : void 0;
+//#endregion
+export { asRectAnchor };

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

@@ -0,0 +1,8 @@
+import { ShapeDefinition } from './types';
+/**
+ * circle 注册项
+ * @description circumscribe = 内框对角线/2（两轴相等）；几何走 circle 数学层；
+ *   emit 复用 `ellipse.emit`（circle = rx=ry 的 ellipse），与旧 circle→`emitEllipseShape` 等价
+ */
+export declare const circle: ShapeDefinition;
+//# sourceMappingURL=circle.d.ts.map

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

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

package/dist/es/shapes/circle.js

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

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

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

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

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

package/dist/es/shapes/diamond.js

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

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

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

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

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

package/dist/es/shapes/ellipse.js

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

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

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

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

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

package/dist/es/shapes/index.js

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

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

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

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

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

package/dist/es/shapes/rectangle.js

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

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

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

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

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

package/dist/lib/compile/compile.cjs

@@ -1,11 +1,13 @@
 const require_rect = require("../geometry/rect.cjs");
+const require_index = require("../shapes/index.cjs");
 const require_name_stack = require("./name-stack.cjs");
 const require_scope = require("./scope.cjs");
 const require_position = require("./position.cjs");
 const require_node = require("./node.cjs");
 const require_text_metrics = require("./text-metrics.cjs");
-const require_index = require("./path/index.cjs");
+const require_index$1 = require("./path/index.cjs");
 const require_precision = require("./precision.cjs");
+const require_style = require("./style.cjs");
 const require_layout = require("./layout.cjs");
 //#region src/compile/compile.ts
 /**
@@ -15,7 +17,8 @@ const require_layout = require("./layout.cjs");
 */
 var zeroSizeRectAt = (id, [cx, cy]) => ({
 	id,
-	shape: "rectangle",
+	shapeName: "rectangle",
+	shapeDef: require_index.BUILTIN_SHAPES.rectangle,
 	rect: {
 		x: cx,
 		y: cy,
@@ -83,6 +86,17 @@ var compileToScene = (ir, options = {}) => {
 	const round = require_precision.makeRound(options.precision ?? 2);
 	const nodeDistance = options.nodeDistance;
 	const onWarn = options.onWarn ?? defaultWarnDispatcher;
+	const effectiveShapes = options.shapes ? {
+		...require_index.BUILTIN_SHAPES,
+		...options.shapes
+	} : require_index.BUILTIN_SHAPES;
+	if (options.shapes) {
+		for (const name of Object.keys(options.shapes)) if (Object.prototype.hasOwnProperty.call(require_index.BUILTIN_SHAPES, name)) onWarn({
+			code: "SHAPE_OVERRIDES_BUILTIN",
+			message: `Injected shape '${name}' overrides the built-in shape of the same name.`,
+			path: `options.shapes.${name}`
+		});
+	}
 	const primitives = [];
 	const nameStack = new require_name_stack.NameStack({ onDuplicate: (info) => onWarn(formatDuplicateWarning(info)) });
 	const allPoints = [];
@@ -97,7 +111,7 @@ var compileToScene = (ir, options = {}) => {
 		nameStack.enterLookupPhase();
 		try {
 			for (const item of pending) {
-				const result = require_index.emitPathPrimitive(item.path, nameStack, round, measureText, {
+				const result = require_index$1.emitPathPrimitive(item.path, nameStack, round, measureText, {
 					onWarn,
 					irPath: item.irPath,
 					scopeChain: item.scopeChain
@@ -120,12 +134,13 @@ var compileToScene = (ir, options = {}) => {
 	* @param locatorPrefix IR locator 前缀（如 `''` 表示顶层、`children[2].scope.` 表示某 scope 内）
 	* @param layoutsAccumulator 当前 scope 子树所有"实体"layout（node / coordinate / 嵌套 scope.id synthetic）累积——专给上层 scope.id bbox 计算用；顶层调用传一个共享数组（用得着就用，丢弃也不影响）
 	* @param pathsAccumulator 当前层级收集的 pending paths——由调用方分配并在合适时机 resolve
+	* @param styleStack 从根到当前层级累积的样式 frame 栈（scope 级联 graphic state + 四通道 every-X + resetStyle）；node / path 进入时按 inside-out per-field 解析 effective 样式
 	*/
-	const processChildren = (children, chain, sink, locatorPrefix, layoutsAccumulator, pathsAccumulator) => {
+	const processChildren = (children, chain, sink, locatorPrefix, layoutsAccumulator, pathsAccumulator, styleStack) => {
 		for (let i = 0; i < children.length; i++) {
 			const child = children[i];
 			if (child.type === "node") {
-				const layout = require_node.layoutNode(child, measureText, nameStack, nodeDistance, chain);
+				const layout = require_node.layoutNode(require_style.resolveNodeStyle(child, styleStack), measureText, nameStack, nodeDistance, chain, require_style.resolveLabelDefault(styleStack), effectiveShapes);
 				const globalLayout = chain.length === 0 ? layout : require_scope.projectLayoutToGlobal(layout, chain);
 				if (child.id) nameStack.register(child.id, globalLayout, `${locatorPrefix}children[${i}].node.id`);
 				for (const prim of require_node.emitNodePrimitives(layout, round)) sink.push(prim);
@@ -165,7 +180,7 @@ var compileToScene = (ir, options = {}) => {
 				*  让 scope 内 path 自引用本 scope.id 端点取真 bbox 而非 placeholder */
 				const innerPaths = [];
 				try {
-					processChildren(child.children, innerChain, innerSink, `${locatorPrefix}children[${i}].scope.`, innerLayouts, innerPaths);
+					processChildren(child.children, innerChain, innerSink, `${locatorPrefix}children[${i}].scope.`, innerLayouts, innerPaths, [...styleStack, require_style.buildStyleFrame(child)]);
 					if (child.id) {
 						const bbox = require_scope.computeScopeBoundingBox(innerLayouts);
 						const fallbackOrigin = innerChain.length === 0 ? [0, 0] : require_scope.applyTransformChain([0, 0], innerChain);
@@ -186,14 +201,14 @@ var compileToScene = (ir, options = {}) => {
 				if (hasOwnTransforms) group.transforms = [...ownTransforms];
 				sink.push(group);
 			} else pathsAccumulator.push({
-				path: child,
+				path: require_style.resolveEffectivePath(child, styleStack),
 				irPath: `${locatorPrefix}children[${i}].path`,
 				scopeChain: chain
 			});
 		}
 	};
 	const rootPaths = [];
-	processChildren(ir.children, [], primitives, "", [], rootPaths);
+	processChildren(ir.children, [], primitives, "", [], rootPaths, []);
 	resolvePendingPaths(rootPaths);
 	return {
 		primitives,

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

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

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

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