@retikz/core 0.1.0-alpha.0 → 0.1.0-alpha.1

package/dist/lib/ir/scene.d.ts

@@ -2,6 +2,12 @@ import { z } from 'zod';
 export declare const ChildSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"node">;
     id: z.ZodOptional<z.ZodString>;
+    shape: z.ZodOptional<z.ZodNativeEnum<{
+        readonly rectangle: "rectangle";
+        readonly circle: "circle";
+        readonly ellipse: "ellipse";
+        readonly diamond: "diamond";
+    }>>;
     position: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('./position').PolarPosition, z.ZodTypeDef, import('./position').PolarPosition>]>;
     rotate: z.ZodOptional<z.ZodNumber>;
     text: z.ZodOptional<z.ZodString>;
@@ -15,6 +21,7 @@ export declare const ChildSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: "node";
     position: [number, number] | import('./position').PolarPosition;
     fill?: string | undefined;
+    shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
     stroke?: string | undefined;
     strokeWidth?: number | undefined;
     id?: string | undefined;
@@ -27,6 +34,7 @@ export declare const ChildSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: "node";
     position: [number, number] | import('./position').PolarPosition;
     fill?: string | undefined;
+    shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
     stroke?: string | undefined;
     strokeWidth?: number | undefined;
     id?: string | undefined;
@@ -40,6 +48,18 @@ export declare const ChildSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     stroke: z.ZodOptional<z.ZodString>;
     strokeWidth: z.ZodOptional<z.ZodNumber>;
     strokeDasharray: z.ZodOptional<z.ZodString>;
+    arrow: z.ZodOptional<z.ZodEnum<["none", "->", "<-", "<->"]>>;
+    arrowShape: z.ZodOptional<z.ZodNativeEnum<{
+        readonly normal: "normal";
+        readonly open: "open";
+        readonly stealth: "stealth";
+        readonly diamond: "diamond";
+        readonly openDiamond: "openDiamond";
+        readonly circle: "circle";
+        readonly openCircle: "openCircle";
+    }>>;
+    fill: z.ZodOptional<z.ZodString>;
+    fillRule: z.ZodOptional<z.ZodEnum<["nonzero", "evenodd"]>>;
     children: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         type: z.ZodLiteral<"step">;
         kind: z.ZodLiteral<"move">;
@@ -64,6 +84,30 @@ export declare const ChildSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: "step";
         kind: "line";
         to: string | [number, number] | import('./position').PolarPosition;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"step">;
+        kind: z.ZodLiteral<"step">;
+        via: z.ZodEnum<["-|", "|-"]>;
+        to: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('./position').PolarPosition, z.ZodTypeDef, import('./position').PolarPosition>, z.ZodString]>;
+    }, "strip", z.ZodTypeAny, {
+        type: "step";
+        kind: "step";
+        to: string | [number, number] | import('./position').PolarPosition;
+        via: "-|" | "|-";
+    }, {
+        type: "step";
+        kind: "step";
+        to: string | [number, number] | import('./position').PolarPosition;
+        via: "-|" | "|-";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"step">;
+        kind: z.ZodLiteral<"cycle">;
+    }, "strip", z.ZodTypeAny, {
+        type: "step";
+        kind: "cycle";
+    }, {
+        type: "step";
+        kind: "cycle";
     }>]>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "path";
@@ -75,10 +119,22 @@ export declare const ChildSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: "step";
         kind: "line";
         to: string | [number, number] | import('./position').PolarPosition;
+    } | {
+        type: "step";
+        kind: "step";
+        to: string | [number, number] | import('./position').PolarPosition;
+        via: "-|" | "|-";
+    } | {
+        type: "step";
+        kind: "cycle";
     })[];
+    fill?: string | undefined;
     stroke?: string | undefined;
     strokeWidth?: number | undefined;
     strokeDasharray?: string | undefined;
+    arrow?: "none" | "->" | "<-" | "<->" | undefined;
+    arrowShape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+    fillRule?: "nonzero" | "evenodd" | undefined;
 }, {
     type: "path";
     children: ({
@@ -89,10 +145,22 @@ export declare const ChildSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: "step";
         kind: "line";
         to: string | [number, number] | import('./position').PolarPosition;
+    } | {
+        type: "step";
+        kind: "step";
+        to: string | [number, number] | import('./position').PolarPosition;
+        via: "-|" | "|-";
+    } | {
+        type: "step";
+        kind: "cycle";
     })[];
+    fill?: string | undefined;
     stroke?: string | undefined;
     strokeWidth?: number | undefined;
     strokeDasharray?: string | undefined;
+    arrow?: "none" | "->" | "<-" | "<->" | undefined;
+    arrowShape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+    fillRule?: "nonzero" | "evenodd" | undefined;
 }>]>;
 /** 顶层 Scene 的子节点：node 或 path */
 export type IRChild = z.infer<typeof ChildSchema>;
@@ -102,6 +170,12 @@ export declare const SceneSchema: z.ZodObject<{
     children: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
         type: z.ZodLiteral<"node">;
         id: z.ZodOptional<z.ZodString>;
+        shape: z.ZodOptional<z.ZodNativeEnum<{
+            readonly rectangle: "rectangle";
+            readonly circle: "circle";
+            readonly ellipse: "ellipse";
+            readonly diamond: "diamond";
+        }>>;
         position: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('./position').PolarPosition, z.ZodTypeDef, import('./position').PolarPosition>]>;
         rotate: z.ZodOptional<z.ZodNumber>;
         text: z.ZodOptional<z.ZodString>;
@@ -115,6 +189,7 @@ export declare const SceneSchema: z.ZodObject<{
         type: "node";
         position: [number, number] | import('./position').PolarPosition;
         fill?: string | undefined;
+        shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         id?: string | undefined;
@@ -127,6 +202,7 @@ export declare const SceneSchema: z.ZodObject<{
         type: "node";
         position: [number, number] | import('./position').PolarPosition;
         fill?: string | undefined;
+        shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         id?: string | undefined;
@@ -140,6 +216,18 @@ export declare const SceneSchema: z.ZodObject<{
         stroke: z.ZodOptional<z.ZodString>;
         strokeWidth: z.ZodOptional<z.ZodNumber>;
         strokeDasharray: z.ZodOptional<z.ZodString>;
+        arrow: z.ZodOptional<z.ZodEnum<["none", "->", "<-", "<->"]>>;
+        arrowShape: z.ZodOptional<z.ZodNativeEnum<{
+            readonly normal: "normal";
+            readonly open: "open";
+            readonly stealth: "stealth";
+            readonly diamond: "diamond";
+            readonly openDiamond: "openDiamond";
+            readonly circle: "circle";
+            readonly openCircle: "openCircle";
+        }>>;
+        fill: z.ZodOptional<z.ZodString>;
+        fillRule: z.ZodOptional<z.ZodEnum<["nonzero", "evenodd"]>>;
         children: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
             type: z.ZodLiteral<"step">;
             kind: z.ZodLiteral<"move">;
@@ -164,6 +252,30 @@ export declare const SceneSchema: z.ZodObject<{
             type: "step";
             kind: "line";
             to: string | [number, number] | import('./position').PolarPosition;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"step">;
+            kind: z.ZodLiteral<"step">;
+            via: z.ZodEnum<["-|", "|-"]>;
+            to: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('./position').PolarPosition, z.ZodTypeDef, import('./position').PolarPosition>, z.ZodString]>;
+        }, "strip", z.ZodTypeAny, {
+            type: "step";
+            kind: "step";
+            to: string | [number, number] | import('./position').PolarPosition;
+            via: "-|" | "|-";
+        }, {
+            type: "step";
+            kind: "step";
+            to: string | [number, number] | import('./position').PolarPosition;
+            via: "-|" | "|-";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"step">;
+            kind: z.ZodLiteral<"cycle">;
+        }, "strip", z.ZodTypeAny, {
+            type: "step";
+            kind: "cycle";
+        }, {
+            type: "step";
+            kind: "cycle";
         }>]>, "many">;
     }, "strip", z.ZodTypeAny, {
         type: "path";
@@ -175,10 +287,22 @@ export declare const SceneSchema: z.ZodObject<{
             type: "step";
             kind: "line";
             to: string | [number, number] | import('./position').PolarPosition;
+        } | {
+            type: "step";
+            kind: "step";
+            to: string | [number, number] | import('./position').PolarPosition;
+            via: "-|" | "|-";
+        } | {
+            type: "step";
+            kind: "cycle";
         })[];
+        fill?: string | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         strokeDasharray?: string | undefined;
+        arrow?: "none" | "->" | "<-" | "<->" | undefined;
+        arrowShape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        fillRule?: "nonzero" | "evenodd" | undefined;
     }, {
         type: "path";
         children: ({
@@ -189,10 +313,22 @@ export declare const SceneSchema: z.ZodObject<{
             type: "step";
             kind: "line";
             to: string | [number, number] | import('./position').PolarPosition;
+        } | {
+            type: "step";
+            kind: "step";
+            to: string | [number, number] | import('./position').PolarPosition;
+            via: "-|" | "|-";
+        } | {
+            type: "step";
+            kind: "cycle";
         })[];
+        fill?: string | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         strokeDasharray?: string | undefined;
+        arrow?: "none" | "->" | "<-" | "<->" | undefined;
+        arrowShape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        fillRule?: "nonzero" | "evenodd" | undefined;
     }>]>, "many">;
 }, "strip", z.ZodTypeAny, {
     type: "scene";
@@ -206,14 +342,27 @@ export declare const SceneSchema: z.ZodObject<{
             type: "step";
             kind: "line";
             to: string | [number, number] | import('./position').PolarPosition;
+        } | {
+            type: "step";
+            kind: "step";
+            to: string | [number, number] | import('./position').PolarPosition;
+            via: "-|" | "|-";
+        } | {
+            type: "step";
+            kind: "cycle";
         })[];
+        fill?: string | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         strokeDasharray?: string | undefined;
+        arrow?: "none" | "->" | "<-" | "<->" | undefined;
+        arrowShape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        fillRule?: "nonzero" | "evenodd" | undefined;
     } | {
         type: "node";
         position: [number, number] | import('./position').PolarPosition;
         fill?: string | undefined;
+        shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         id?: string | undefined;
@@ -236,14 +385,27 @@ export declare const SceneSchema: z.ZodObject<{
             type: "step";
             kind: "line";
             to: string | [number, number] | import('./position').PolarPosition;
+        } | {
+            type: "step";
+            kind: "step";
+            to: string | [number, number] | import('./position').PolarPosition;
+            via: "-|" | "|-";
+        } | {
+            type: "step";
+            kind: "cycle";
         })[];
+        fill?: string | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         strokeDasharray?: string | undefined;
+        arrow?: "none" | "->" | "<-" | "<->" | undefined;
+        arrowShape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        fillRule?: "nonzero" | "evenodd" | undefined;
     } | {
         type: "node";
         position: [number, number] | import('./position').PolarPosition;
         fill?: string | undefined;
+        shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
         stroke?: string | undefined;
         strokeWidth?: number | undefined;
         id?: string | undefined;

package/dist/lib/ir/scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/ir/scene.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAIrB,CAAC;AAEJ,gCAAgC;AAChC,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAElD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBrB,CAAC;AAEJ,4CAA4C;AAC5C,MAAM,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE7C,qCAAqC;AACrC,eAAO,MAAM,kBAAkB,EAAG,CAAU,CAAC"}
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/ir/scene.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAIrB,CAAC;AAEJ,gCAAgC;AAChC,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAElD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBrB,CAAC;AAEJ,4CAA4C;AAC5C,MAAM,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE7C,qCAAqC;AACrC,eAAO,MAAM,kBAAkB,EAAG,CAAU,CAAC"}

package/dist/lib/parsers/parseWay.cjs

@@ -1,11 +1,51 @@
 //#region src/parsers/parseWay.ts
 /**
+* Sugar 层 way 数组的"关键字常量"。
+*
+* - `DrawWay.cycle`：闭合到 way 起点（way 元素位置）。**底层字符串故意取得很丑**
+*   （`'retikz-keyword_cycle'`），保证不会与任何合理的节点 id 冲突；用户应当
+*   只通过 `DrawWay.cycle` 引用，不要直接写裸字面量。
+* - `DrawWay.hv`：折角算子，先水平后垂直（裸字面量 `'-|'`）。
+* - `DrawWay.vh`：折角算子，先垂直后水平（裸字面量 `'|-'`）。
+*
+* 折角值（`-|` / `|-`）含特殊字符，与节点 id 不会冲突，因此**保留字面量与
+* 常量两种写法都合法**。way 数组里直接放 `'-|'` 或 `'|-'`（infix 算子）
+* 即把"上一项 → 下一项"那一段改成折角。
+*
+* 这里**故意不用 TS enum**——enum 在数值场景下生成 reverse-mapping 表、
+* 在 string 场景下与字面量类型不互通，而 const + `as const` 的字面量联合
+* 既可枚举也可与字面量字符串无缝混用。
+*/
+var DrawWay = {
+	/**
+	* 闭合 way 到起点，等价于 `<Step kind="cycle" />`（TikZ 同名保留字 / SVG `Z`）。
+	* 底层字符串值刻意写丑以避开节点 id 冲突；不要硬编码这个字符串。
+	*/
+	cycle: "retikz-keyword_cycle",
+	/** 折角：先水平后垂直（TikZ `-|`） */
+	hv: "-|",
+	/** 折角：先垂直后水平（TikZ `|-`） */
+	vh: "|-"
+};
+var isWayCycle = (item) => item === DrawWay.cycle;
+var isWayVia = (item) => item === DrawWay.hv || item === DrawWay.vh;
+/** 把 WayItem 归约为它的"目标点"——target 直接返回；算子/关键字返回 null */
+var targetOf = (item) => {
+	if (isWayCycle(item) || isWayVia(item)) return null;
+	return item;
+};
+/**
 * 把 way 数组翻译为 IRStep 序列。
-* 第一个元素永远是 move；之后的默认是 line。
 *
-* 这是纯函数，住在 core，被各框架 adapter 的 Sugar 组件复用。
+* - 第一个元素始终是 move：取 way[0] 的目标点；若 way[0] 是 cycle / via 算子等
+*   非 target 项，则降级到原点 `[0, 0]`（容错）。
+* - 后续元素：
+*   - 普通 target → line
+*   - `DrawWay.cycle` → cycle 步
+*   - `'-|'` / `'|-'` → 与**下一项**合并成 fold 步；操作符在 way 末尾或后
+*     接非 target 项时抛错
 *
-* 类型校验由 TS 编译期完成；本函数不做运行时类型守卫。
+* 这是纯函数，住在 core，被各框架 adapter 的 Sugar 组件复用。
 */
 var parseWay = (way) => {
 	if (way.length < 2) throw new Error("parseWay: way must contain at least 2 items");
@@ -13,18 +53,41 @@ var parseWay = (way) => {
 	const moveStep = {
 		type: "step",
 		kind: "move",
-		to: way[0]
+		to: targetOf(way[0]) ?? [0, 0]
 	};
 	out.push(moveStep);
 	for (let i = 1; i < way.length; i++) {
+		const item = way[i];
+		if (isWayCycle(item)) {
+			out.push({
+				type: "step",
+				kind: "cycle"
+			});
+			continue;
+		}
+		if (isWayVia(item)) {
+			if (i + 1 >= way.length) throw new Error(`parseWay: via operator '${item}' at end of way must be followed by a target`);
+			const next = way[i + 1];
+			if (isWayCycle(next) || isWayVia(next)) throw new Error(`parseWay: via operator '${item}' must be followed by a target, got '${String(next)}'`);
+			const fold = {
+				type: "step",
+				kind: "step",
+				via: item,
+				to: next
+			};
+			out.push(fold);
+			i++;
+			continue;
+		}
 		const lineStep = {
 			type: "step",
 			kind: "line",
-			to: way[i]
+			to: item
 		};
 		out.push(lineStep);
 	}
 	return out;
 };
 //#endregion
+exports.DrawWay = DrawWay;
 exports.parseWay = parseWay;

package/dist/lib/parsers/parseWay.d.ts

@@ -1,25 +1,71 @@
 import { IRStep, IRTarget } from '../ir';
+/**
+ * Sugar 层 way 数组的"关键字常量"。
+ *
+ * - `DrawWay.cycle`：闭合到 way 起点（way 元素位置）。**底层字符串故意取得很丑**
+ *   （`'retikz-keyword_cycle'`），保证不会与任何合理的节点 id 冲突；用户应当
+ *   只通过 `DrawWay.cycle` 引用，不要直接写裸字面量。
+ * - `DrawWay.hv`：折角算子，先水平后垂直（裸字面量 `'-|'`）。
+ * - `DrawWay.vh`：折角算子，先垂直后水平（裸字面量 `'|-'`）。
+ *
+ * 折角值（`-|` / `|-`）含特殊字符，与节点 id 不会冲突，因此**保留字面量与
+ * 常量两种写法都合法**。way 数组里直接放 `'-|'` 或 `'|-'`（infix 算子）
+ * 即把"上一项 → 下一项"那一段改成折角。
+ *
+ * 这里**故意不用 TS enum**——enum 在数值场景下生成 reverse-mapping 表、
+ * 在 string 场景下与字面量类型不互通，而 const + `as const` 的字面量联合
+ * 既可枚举也可与字面量字符串无缝混用。
+ */
+export declare const DrawWay: {
+    /**
+     * 闭合 way 到起点，等价于 `<Step kind="cycle" />`（TikZ 同名保留字 / SVG `Z`）。
+     * 底层字符串值刻意写丑以避开节点 id 冲突；不要硬编码这个字符串。
+     */
+    readonly cycle: "retikz-keyword_cycle";
+    /** 折角：先水平后垂直（TikZ `-|`） */
+    readonly hv: "-|";
+    /** 折角：先垂直后水平（TikZ `|-`） */
+    readonly vh: "|-";
+};
+/**
+ * way 折角算子的字面量类型。`DrawWay.hv` / `DrawWay.vh` 与裸字面量等价。
+ */
+export type WayVia = typeof DrawWay.hv | typeof DrawWay.vh;
+/**
+ * way 闭合关键字的字面量类型，由 `DrawWay.cycle` 派生。
+ */
+export type WayCycle = typeof DrawWay.cycle;
 /**
  * Sugar 层的 way 数组 DSL 元素。
  *
- * v0.1.0-alpha 接受三种形态（与 `IRTarget` 等价）：
- * - 节点 id 字符串：`'A'`
- * - 直接笛卡尔坐标：`[x, y]`
- * - 极坐标：`{ origin?, angle, radius }`
+ * v0.1.0-alpha.1 接受五种形态：
+ * - 节点 id 字符串：`'A'` → line（首项时为 move）
+ * - 笛卡尔坐标：`[x, y]` → line
+ * - 极坐标：`{ origin?, angle, radius }` → line
+ * - 折角算子：`'-|'` / `'|-'`（或 `DrawWay.hv` / `DrawWay.vh`）→ 当前项 +
+ *   **下一项**合并成一个折角 step（与 TikZ 的 `(A) -| (B)` infix 写法对齐）
+ * - 闭合关键字：`DrawWay.cycle` → cycle（闭合到起点）
  *
- * 后续会加：折角对象（`{ via: '-|' }`）、相对位移（`{ rel: [x, y] }`）、
- * curve / cubic / 'close' 等——届时 WayItem 与 IRTarget 才会出现真正分歧。
+ * 后续会加：相对位移（`{ rel: [x, y] }`）、curve / cubic 等。
+ *
+ * 注意：闭合刻意只走 `DrawWay.cycle`（底层字符串是 `'retikz-keyword_cycle'`），
+ * 这样裸字符串 `'cycle'` 仍可作为正常节点 id 使用。
  */
-export type WayItem = IRTarget;
+export type WayItem = IRTarget | WayVia | WayCycle;
 /** way DSL 数组：sugar `<Draw way={...}>` 接受的输入形态 */
 export type WayDSL = Array<WayItem>;
 /**
  * 把 way 数组翻译为 IRStep 序列。
- * 第一个元素永远是 move；之后的默认是 line。
  *
- * 这是纯函数，住在 core，被各框架 adapter 的 Sugar 组件复用。
+ * - 第一个元素始终是 move：取 way[0] 的目标点；若 way[0] 是 cycle / via 算子等
+ *   非 target 项，则降级到原点 `[0, 0]`（容错）。
+ * - 后续元素：
+ *   - 普通 target → line
+ *   - `DrawWay.cycle` → cycle 步
+ *   - `'-|'` / `'|-'` → 与**下一项**合并成 fold 步；操作符在 way 末尾或后
+ *     接非 target 项时抛错
  *
- * 类型校验由 TS 编译期完成；本函数不做运行时类型守卫。
+ * 这是纯函数，住在 core，被各框架 adapter 的 Sugar 组件复用。
  */
 export declare const parseWay: (way: WayDSL) => Array<IRStep>;
 //# sourceMappingURL=parseWay.d.ts.map

package/dist/lib/parsers/parseWay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseWay.d.ts","sourceRoot":"","sources":["../../../src/parsers/parseWay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0B,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC;AAE/B,kDAAkD;AAClD,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,KAAK,CAAC,MAAM,CAYlD,CAAA"}
+{"version":3,"file":"parseWay.d.ts","sourceRoot":"","sources":["../../../src/parsers/parseWay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,MAAM,EACN,QAAQ,EACT,MAAM,OAAO,CAAC;AAEf;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO;IAClB;;;OAGG;;IAEH,2BAA2B;;IAE3B,2BAA2B;;CAEnB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,EAAE,GAAG,OAAO,OAAO,CAAC,EAAE,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,OAAO,CAAC,KAAK,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnD,kDAAkD;AAClD,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;AAapC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,KAAK,CAAC,MAAM,CAoClD,CAAC"}

package/dist/lib/primitive/ellipse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 椭圆原语：SVG `<ellipse>` 直对应。
+ * 圆形（半长轴 = 半短轴）用同一个 EllipsePrim 表示，让 renderer 单一 case 处理。
+ * 旋转走 `rotate` 字段（度数，绕中心）；非零时 renderer 用 SVG transform 包裹。
+ */
+export type EllipsePrim = {
+    /** 类型判别符 */
+    type: 'ellipse';
+    /** 中心横坐标 */
+    cx: number;
+    /** 中心纵坐标 */
+    cy: number;
+    /** 水平半轴 */
+    rx: number;
+    /** 垂直半轴 */
+    ry: number;
+    /** 绕中心的旋转角（度数，与 RectPrim 风格一致）；省略或 0 不旋转 */
+    rotate?: number;
+    /** 填充色 */
+    fill?: string;
+    /** 填充透明度 0~1 */
+    fillOpacity?: number;
+    /** 描边色 */
+    stroke?: string;
+    /** 描边宽度 */
+    strokeWidth?: number;
+    /** SVG stroke-dasharray 模式 */
+    strokeDasharray?: string;
+    /** 整体透明度 0~1 */
+    opacity?: number;
+};
+//# sourceMappingURL=ellipse.d.ts.map

package/dist/lib/primitive/ellipse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipse.d.ts","sourceRoot":"","sources":["../../../src/primitive/ellipse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,YAAY;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,YAAY;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU;IACV,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU;IACV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}

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

@@ -1,4 +1,5 @@
 export * from './rect';
+export * from './ellipse';
 export * from './text';
 export * from './path';
 export * from './group';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitive/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitive/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}

package/dist/lib/primitive/path.d.ts

@@ -1,3 +1,4 @@
+import { ArrowShape } from '../ir/path/arrow';
 /** 路径原语：SVG path d 字符串；Canvas/PDF renderer 自行解析 */
 export type PathPrim = {
     /** 类型判别符 */
@@ -6,6 +7,8 @@ export type PathPrim = {
     d: string;
     /** 填充色；不填表示不填充 */
     fill?: string;
+    /** SVG fill-rule：`nonzero`（默认）/ `evenodd`（环形 / 孔洞场景） */
+    fillRule?: 'nonzero' | 'evenodd';
     /** 描边色 */
     stroke?: string;
     /** 描边宽度 */
@@ -16,6 +19,10 @@ export type PathPrim = {
     strokeLinecap?: 'butt' | 'round' | 'square';
     /** 拐点形状 */
     strokeLinejoin?: 'miter' | 'round' | 'bevel';
+    /** 起点箭头形状；undefined = 无 */
+    arrowStart?: ArrowShape;
+    /** 终点箭头形状；undefined = 无 */
+    arrowEnd?: ArrowShape;
     /** 整体透明度 0~1 */
     opacity?: number;
 };

package/dist/lib/primitive/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/primitive/path.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU;IACV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW;IACX,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,WAAW;IACX,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IAC7C,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/primitive/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,mDAAmD;AACnD,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,UAAU;IACV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW;IACX,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,WAAW;IACX,cAAc,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IAC7C,2BAA2B;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}

package/dist/lib/primitive/scene.d.ts

@@ -1,3 +1,4 @@
+import { EllipsePrim } from './ellipse';
 import { GroupPrim } from './group';
 import { PathPrim } from './path';
 import { RectPrim } from './rect';
@@ -9,7 +10,7 @@ import { ViewBox } from './view-box';
  *
  * 不允许出现 SVG-only 或 Canvas-only 特性（filter、marker、imageData 等）。
  */
-export type ScenePrimitive = RectPrim | TextPrim | PathPrim | GroupPrim;
+export type ScenePrimitive = RectPrim | EllipsePrim | TextPrim | PathPrim | GroupPrim;
 /** 场景：渲染目标无关的"已布局好的图元集合 + viewBox" */
 export type Scene = {
     /** 已布局好的图元数组，按渲染顺序排列 */

package/dist/lib/primitive/scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/primitive/scene.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAExE,sCAAsC;AACtC,MAAM,MAAM,KAAK,GAAG;IAClB,wBAAwB;IACxB,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAClC,gBAAgB;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC"}
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/primitive/scene.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtF,sCAAsC;AACtC,MAAM,MAAM,KAAK,GAAG;IAClB,wBAAwB;IACxB,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAClC,gBAAgB;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC"}

package/dist/lib/types.d.ts

@@ -0,0 +1,3 @@
+/** 获取对象所有值的联合类型，等价于 (typeof T)[keyof typeof T] */
+export type ValueOf<T extends object> = T[keyof T];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retikz/core",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "retikz v0.1 core: framework-agnostic IR, scene compiler, and pure parsers.",
   "type": "module",
   "homepage": "https://pionpill.github.io/retikz/",