@retikz/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/es/ir/json.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/**
+ * 递归 JSON 值 schema
+ * @description 守 IR 100% JSON 可序列化：path generator step 的 params 只能由 JSON 值构成；
+ *   函数 / undefined / class 实例 / Symbol / Map / Set 等非 JSON 值在 parse 阶段被拒。
+ *   `z.lazy` 让 array / object 分支可递归引用本 schema，深度不限。
+ */
+export declare const JsonValueSchema: z.ZodType<JsonValue>;
+/**
+ * JSON 对象 schema
+ * @description path generator step 的 `params` 类型；键为字符串、值为递归 JSON 值。
+ *   作为 compile 运行时的第二道护栏：即便外部 `paramsSchema` 是宽松类型，对其 parse 结果再跑本 schema
+ *   可拦下非 JSON 输出（function / undefined 等）。core 公开供外部 refine。
+ */
+export declare const JsonObjectSchema: z.ZodRecord<z.ZodString, z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>>;
+/** 单个 JSON 值（字符串 / 数字 / 布尔 / null / 数组 / 对象，递归） */
+export type JsonValue = string | number | boolean | null | Array<JsonValue> | {
+    [key: string]: JsonValue;
+};
+/** JSON 对象类型（path generator step 的 params 形态） */
+export type IRJsonObject = z.infer<typeof JsonObjectSchema>;
+//# sourceMappingURL=json.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/ir/json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAahD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,yEAI1B,CAAC;AAEJ,mDAAmD;AACnD,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,KAAK,CAAC,SAAS,CAAC,GAChB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,iDAAiD;AACjD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/es/ir/json.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+//#region src/ir/json.ts
+/**
+* 递归 JSON 值 schema
+* @description 守 IR 100% JSON 可序列化：path generator step 的 params 只能由 JSON 值构成；
+*   函数 / undefined / class 实例 / Symbol / Map / Set 等非 JSON 值在 parse 阶段被拒。
+*   `z.lazy` 让 array / object 分支可递归引用本 schema，深度不限。
+*/
+var JsonValueSchema = z.lazy(() => z.union([
+	z.string(),
+	z.number().finite(),
+	z.boolean(),
+	z.null(),
+	z.array(JsonValueSchema),
+	JsonObjectSchema
+]).describe("A JSON value: string, finite number, boolean, null, an array of JSON values, or an object of JSON values. Recursive with no depth limit. Functions, undefined, Symbol, class instances, Map, and Set are rejected to keep the IR fully JSON-serializable."));
+/**
+* JSON 对象 schema
+* @description path generator step 的 `params` 类型；键为字符串、值为递归 JSON 值。
+*   作为 compile 运行时的第二道护栏：即便外部 `paramsSchema` 是宽松类型，对其 parse 结果再跑本 schema
+*   可拦下非 JSON 输出（function / undefined 等）。core 公开供外部 refine。
+*/
+var JsonObjectSchema = z.record(JsonValueSchema).describe("A JSON object: string keys mapping to recursive JSON values. Used as the params payload of a path generator step and as the runtime guard that the value is fully JSON-serializable. No maximum depth or size is enforced.");
+//#endregion
+export { JsonObjectSchema, JsonValueSchema };

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

@@ -153,7 +153,7 @@ export declare const NodeSchema: z.ZodObject<{
     }, {
         of: string | [number, number] | import('./position').PolarPosition;
         offset: [number, number];
-    }>]>;
+    }>, z.ZodType<import('./position').IRBetweenPosition, z.ZodTypeDef, import('./position').IRBetweenPosition>]>;
     rotate: z.ZodOptional<z.ZodNumber>;
     text: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
         text: z.ZodString;
@@ -273,7 +273,7 @@ export declare const NodeSchema: z.ZodObject<{
         center?: [number, number] | undefined;
     }>, z.ZodObject<{
         type: z.ZodLiteral<"pattern">;
-        shape: z.ZodEnum<["lines", "dots", "grid"]>;
+        shape: z.ZodString;
         color: z.ZodOptional<z.ZodString>;
         background: z.ZodOptional<z.ZodString>;
         size: z.ZodOptional<z.ZodNumber>;
@@ -281,7 +281,7 @@ export declare const NodeSchema: z.ZodObject<{
         rotation: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         type: "pattern";
-        shape: "lines" | "dots" | "grid";
+        shape: string;
         size?: number | undefined;
         color?: string | undefined;
         background?: string | undefined;
@@ -289,7 +289,7 @@ export declare const NodeSchema: z.ZodObject<{
         rotation?: number | undefined;
     }, {
         type: "pattern";
-        shape: "lines" | "dots" | "grid";
+        shape: string;
         size?: number | undefined;
         color?: string | undefined;
         background?: string | undefined;
@@ -524,7 +524,7 @@ export declare const NodeSchema: z.ZodObject<{
     } | {
         of: string | [number, number] | import('./position').PolarPosition;
         offset: [number, number];
-    };
+    } | import('./position').IRBetweenPosition;
     fill?: string | {
         type: "linearGradient";
         stops: {
@@ -544,7 +544,7 @@ export declare const NodeSchema: z.ZodObject<{
         center?: [number, number] | undefined;
     } | {
         type: "pattern";
-        shape: "lines" | "dots" | "grid";
+        shape: string;
         size?: number | undefined;
         color?: string | undefined;
         background?: string | undefined;
@@ -555,6 +555,7 @@ export declare const NodeSchema: z.ZodObject<{
         href: string;
         fit?: "fill" | "contain" | "cover" | undefined;
     } | undefined;
+    id?: string | undefined;
     color?: string | undefined;
     opacity?: number | undefined;
     shape?: string | undefined;
@@ -576,7 +577,6 @@ export declare const NodeSchema: z.ZodObject<{
         style?: "normal" | "italic" | "oblique" | undefined;
     } | undefined;
     scale?: number | undefined;
-    id?: string | undefined;
     textColor?: string | undefined;
     label?: {
         text: string;
@@ -649,7 +649,7 @@ export declare const NodeSchema: z.ZodObject<{
     } | {
         of: string | [number, number] | import('./position').PolarPosition;
         offset: [number, number];
-    };
+    } | import('./position').IRBetweenPosition;
     fill?: string | {
         type: "linearGradient";
         stops: {
@@ -669,7 +669,7 @@ export declare const NodeSchema: z.ZodObject<{
         center?: [number, number] | undefined;
     } | {
         type: "pattern";
-        shape: "lines" | "dots" | "grid";
+        shape: string;
         size?: number | undefined;
         color?: string | undefined;
         background?: string | undefined;
@@ -680,6 +680,7 @@ export declare const NodeSchema: z.ZodObject<{
         href: string;
         fit?: "fill" | "contain" | "cover" | undefined;
     } | undefined;
+    id?: string | undefined;
     color?: string | undefined;
     opacity?: number | undefined;
     shape?: string | undefined;
@@ -701,7 +702,6 @@ export declare const NodeSchema: z.ZodObject<{
         style?: "normal" | "italic" | "oblique" | undefined;
     } | undefined;
     scale?: number | undefined;
-    id?: string | undefined;
     textColor?: string | undefined;
     label?: {
         text: string;

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

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/ir/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAMxC;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEzD,+BAA+B;AAC/B,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2DzB,CAAC;AAEJ,uBAAuB;AACvB,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE1D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuMpB,CAAC;AAEJ,sCAAsC;AACtC,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/ir/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAMxC;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEzD,+BAA+B;AAC/B,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2DzB,CAAC;AAEJ,uBAAuB;AACvB,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE1D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6MpB,CAAC;AAEJ,sCAAsC;AACtC,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/es/ir/node.js

@@ -2,6 +2,7 @@ import { PositionSchema } from "./position/position.js";
 import { PolarPositionSchema } from "./position/polar-position.js";
 import { AT_DIRECTIONS, AtPositionSchema } from "./position/at-position.js";
 import { OffsetPositionSchema } from "./position/offset-position.js";
+import { BetweenPositionSchema } from "./position/between-position.js";
 import { FontSchema } from "./font.js";
 import { PaintSpecSchema } from "./paint.js";
 import { TextBlockSchema } from "./text.js";
@@ -54,8 +55,9 @@ var NodeSchema = z.object({
 		PositionSchema,
 		PolarPositionSchema,
 		AtPositionSchema,
-		OffsetPositionSchema
-	]).describe("Center point of the node content box; Cartesian [x, y], polar, relative-to-another-node (`at`-style with `direction` / `of` / `distance?`), or offset from a base point (`{ of, offset }` form mirroring TikZ `calc`). All non-Cartesian forms resolve at compile time."),
+		OffsetPositionSchema,
+		BetweenPositionSchema
+	]).describe("Center point of the node content box; Cartesian [x, y], polar, relative-to-another-node (`at`-style with `direction` / `of` / `distance?`), offset from a base point (`{ of, offset }` form mirroring TikZ `calc`), or between two endpoints (`{ between: [A, B], t }` proportional point). All non-Cartesian forms resolve at compile time."),
 	rotate: z.number().optional().describe("Rotation in degrees around the node center; positive = clockwise (matches TikZ rotate=...)"),
 	text: TextBlockSchema.optional(),
 	align: z.nativeEnum(NODE_TEXT_ALIGNS).optional().describe("Multi-line text alignment within the text block; `left` / `center` / `right`. Defaults to `center` (matches TikZ)."),

package/dist/es/ir/paint.d.ts

@@ -1,4 +1,26 @@
 import { z } from 'zod';
+import { ValueOf } from '../types';
+/**
+ * 内置 pattern motif 名常量（用 const + ValueOf 派生，不用 TS enum）
+ * @description 内置 3 motif：`lines`（横向阴影线）/ `dots`（波点）/ `grid`（横竖网格）。
+ *   各 motif 的 tile 几何由 `BUILTIN_PATTERNS` 的 `PatternDefinition.emit` 在 compile 期产出。
+ */
+export declare const PATTERN_SHAPES: {
+    readonly lines: "lines";
+    readonly dots: "dots";
+    readonly grid: "grid";
+};
+/**
+ * 内置 3 pattern motif 名联合
+ * @description `BUILTIN_PATTERNS` 的 Record key（保穷尽性约束，不随 `PatternShapeName` 开放而退化为 `string`）
+ */
+export type BuiltinPatternName = ValueOf<typeof PATTERN_SHAPES>;
+/**
+ * pattern motif 名：开放字符串
+ * @description 内置 `BuiltinPatternName`，或经 `CompileOptions.patterns` 注册的扩展 motif 名；
+ *   `& {}` 让 IDE 仍对内置 3 名自动补全，同时接受任意非空字符串
+ */
+export type PatternShapeName = BuiltinPatternName | (string & {});
 /**
  * 渐变 stop：位置 + 颜色 + 可选透明度
  * @description offset 0..1（沿渐变轴的位置）；color 任意 CSS 颜色（含 `currentColor` 主题反应）；opacity 0..1。
@@ -90,7 +112,7 @@ export declare const PaintSpecSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     center?: [number, number] | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"pattern">;
-    shape: z.ZodEnum<["lines", "dots", "grid"]>;
+    shape: z.ZodString;
     color: z.ZodOptional<z.ZodString>;
     background: z.ZodOptional<z.ZodString>;
     size: z.ZodOptional<z.ZodNumber>;
@@ -98,7 +120,7 @@ export declare const PaintSpecSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     rotation: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     type: "pattern";
-    shape: "lines" | "dots" | "grid";
+    shape: string;
     size?: number | undefined;
     color?: string | undefined;
     background?: string | undefined;
@@ -106,7 +128,7 @@ export declare const PaintSpecSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObje
     rotation?: number | undefined;
 }, {
     type: "pattern";
-    shape: "lines" | "dots" | "grid";
+    shape: string;
     size?: number | undefined;
     color?: string | undefined;
     background?: string | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../../src/ir/paint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAMY,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAmEwF,CAAC;AAErH,iBAAiB;AACjB,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../../src/ir/paint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,OAAO,cAAc,CAAC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAMY,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsEwF,CAAC;AAErH,iBAAiB;AACjB,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/es/ir/paint.js

@@ -1,6 +1,16 @@
 import { z } from "zod";
 //#region src/ir/paint.ts
 /**
+* 内置 pattern motif 名常量（用 const + ValueOf 派生，不用 TS enum）
+* @description 内置 3 motif：`lines`（横向阴影线）/ `dots`（波点）/ `grid`（横竖网格）。
+*   各 motif 的 tile 几何由 `BUILTIN_PATTERNS` 的 `PatternDefinition.emit` 在 compile 期产出。
+*/
+var PATTERN_SHAPES = {
+	lines: "lines",
+	dots: "dots",
+	grid: "grid"
+};
+/**
 * 渐变 stop：位置 + 颜色 + 可选透明度
 * @description offset 0..1（沿渐变轴的位置）；color 任意 CSS 颜色（含 `currentColor` 主题反应）；opacity 0..1。
 */
@@ -28,11 +38,7 @@ var PaintSpecSchema = z.discriminatedUnion("type", [
 	}).describe("Radial gradient paint server"),
 	z.object({
 		type: z.literal("pattern"),
-		shape: z.enum([
-			"lines",
-			"dots",
-			"grid"
-		]).describe("Pattern motif: `lines` (hatching) / `dots` / `grid` (crosshatch)"),
+		shape: z.string().min(1).describe("Registered pattern motif name; built-in `lines` (hatching) / `dots` / `grid` (crosshatch), or an extension motif registered via `CompileOptions.patterns`. Any non-empty string passes schema validation; unregistered names are rejected at compile time."),
 		color: z.string().optional().describe("Motif color; any CSS color, defaults to `currentColor`"),
 		background: z.string().optional().describe("Tile background fill; omitted = transparent"),
 		size: z.number().finite().positive().optional().describe("Tile period in user units (line gap / dot spacing); default 8"),
@@ -50,4 +56,4 @@ var PaintSpecSchema = z.discriminatedUnion("type", [
 	}).describe("Image paint server (fills the shape with an image)")
 ]).describe("Paint server spec: gradient / pattern / image. Solid color stays a plain string on `fill` / `stroke`.");
 //#endregion
-export { GradientStopSchema, PaintSpecSchema };
+export { GradientStopSchema, PATTERN_SHAPES, PaintSpecSchema };

package/dist/es/ir/path/arrow.d.ts

@@ -15,6 +15,18 @@ export declare const ARROW_SHAPES: {
 };
 /** 箭头形状字面量类型 */
 export type ArrowShape = ValueOf<typeof ARROW_SHAPES>;
+/**
+ * 内置 7 箭头名联合
+ * @description `BUILTIN_ARROWS` 的 Record key（保穷尽性约束，不随 `ArrowShapeName` 开放而退化为 `string`）；
+ *   等价于历史 `ArrowShape`，独立命名对齐 `node.ts` 的 `BuiltinShapeName` 范式
+ */
+export type BuiltinArrowName = ValueOf<typeof ARROW_SHAPES>;
+/**
+ * 箭头形状名：开放字符串
+ * @description 内置 `BuiltinArrowName`，或经 `CompileOptions.arrows` 注册的扩展箭头名；
+ *   `& {}` 让 IDE 仍对内置 7 名自动补全，同时接受任意非空字符串（对齐 `node.ts` 的 `NodeShape`）
+ */
+export type ArrowShapeName = BuiltinArrowName | (string & {});
 /** 箭头默认形状 */
 export declare const DEFAULT_ARROW_SHAPE: "stealth";
 /**
@@ -31,15 +43,7 @@ export declare const ARROW_MARKER_HOLLOW_DEFAULT_LINE_WIDTH = 1.5;
  * @description 顶层 8 字段全 optional；fill 在空心 shape 上 silent no-op（schema 不拒绝、compile/render 丢字段）；start/end 子对象用相同字段集（无 start/end 递归）
  */
 export declare const ArrowEndDetailSchema: z.ZodObject<{
-    shape: 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";
-    }>>;
+    shape: z.ZodOptional<z.ZodString>;
     scale: z.ZodOptional<z.ZodNumber>;
     length: z.ZodOptional<z.ZodNumber>;
     width: z.ZodOptional<z.ZodNumber>;
@@ -52,34 +56,26 @@ export declare const ArrowEndDetailSchema: z.ZodObject<{
     fill?: string | undefined;
     color?: string | undefined;
     opacity?: number | undefined;
-    shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+    shape?: string | undefined;
     lineWidth?: number | undefined;
-    scale?: number | undefined;
     width?: number | undefined;
+    scale?: number | undefined;
 }, {
     length?: number | undefined;
     fill?: string | undefined;
     color?: string | undefined;
     opacity?: number | undefined;
-    shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+    shape?: string | undefined;
     lineWidth?: number | undefined;
-    scale?: number | undefined;
     width?: number | undefined;
+    scale?: number | undefined;
 }>;
 /**
  * Path 级箭头详细配置 schema
  * @description 顶层视觉字段（与 `ArrowEndDetailSchema` 同字段集）作为起末共享默认；`start` / `end` 子对象逐字段 merge 顶层（缺省字段继承，已填字段 override）
  */
 export declare const ArrowDetailSchema: z.ZodObject<{
-    shape: 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";
-    }>>;
+    shape: z.ZodOptional<z.ZodString>;
     scale: z.ZodOptional<z.ZodNumber>;
     length: z.ZodOptional<z.ZodNumber>;
     width: z.ZodOptional<z.ZodNumber>;
@@ -89,15 +85,7 @@ export declare const ArrowDetailSchema: z.ZodObject<{
     lineWidth: z.ZodOptional<z.ZodNumber>;
 } & {
     start: z.ZodOptional<z.ZodObject<{
-        shape: 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";
-        }>>;
+        shape: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodNumber>;
         length: z.ZodOptional<z.ZodNumber>;
         width: z.ZodOptional<z.ZodNumber>;
@@ -110,30 +98,22 @@ export declare const ArrowDetailSchema: z.ZodObject<{
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     }, {
         length?: number | undefined;
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     }>>;
     end: z.ZodOptional<z.ZodObject<{
-        shape: 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";
-        }>>;
+        shape: z.ZodOptional<z.ZodString>;
         scale: z.ZodOptional<z.ZodNumber>;
         length: z.ZodOptional<z.ZodNumber>;
         width: z.ZodOptional<z.ZodNumber>;
@@ -146,77 +126,77 @@ export declare const ArrowDetailSchema: z.ZodObject<{
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     }, {
         length?: number | undefined;
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
     length?: number | undefined;
     fill?: string | undefined;
     color?: string | undefined;
     opacity?: number | undefined;
-    shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+    shape?: string | undefined;
     lineWidth?: number | undefined;
-    scale?: number | undefined;
     width?: number | undefined;
+    scale?: number | undefined;
     start?: {
         length?: number | undefined;
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     } | undefined;
     end?: {
         length?: number | undefined;
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     } | undefined;
 }, {
     length?: number | undefined;
     fill?: string | undefined;
     color?: string | undefined;
     opacity?: number | undefined;
-    shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+    shape?: string | undefined;
     lineWidth?: number | undefined;
-    scale?: number | undefined;
     width?: number | undefined;
+    scale?: number | undefined;
     start?: {
         length?: number | undefined;
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     } | undefined;
     end?: {
         length?: number | undefined;
         fill?: string | undefined;
         color?: string | undefined;
         opacity?: number | undefined;
-        shape?: "normal" | "open" | "stealth" | "diamond" | "openDiamond" | "circle" | "openCircle" | undefined;
+        shape?: string | undefined;
         lineWidth?: number | undefined;
-        scale?: number | undefined;
         width?: number | undefined;
+        scale?: number | undefined;
     } | undefined;
 }>;
 /** 端点级箭头视觉规格 */

package/dist/es/ir/path/arrow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arrow.d.ts","sourceRoot":"","sources":["../../../../src/ir/path/arrow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;CAQf,CAAC;AAEX,gBAAgB;AAChB,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,YAAY,CAAC,CAAC;AAEtD,aAAa;AACb,eAAO,MAAM,mBAAmB,WAAuB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,iBAA6D,CAAC;AAE9F,wCAAwC;AACxC,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,0CAA0C;AAC1C,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2D9B,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS7B,CAAC;AAEF,gBAAgB;AAChB,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACpE,mBAAmB;AACnB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
+{"version":3,"file":"arrow.d.ts","sourceRoot":"","sources":["../../../../src/ir/path/arrow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;CAQf,CAAC;AAEX,gBAAgB;AAChB,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,YAAY,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,YAAY,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE9D,aAAa;AACb,eAAO,MAAM,mBAAmB,WAAuB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,iBAA6D,CAAC;AAE9F,wCAAwC;AACxC,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,0CAA0C;AAC1C,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgE9B,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS7B,CAAC;AAEF,gBAAgB;AAChB,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACpE,mBAAmB;AACnB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/es/ir/path/arrow.js

@@ -33,14 +33,14 @@ var ARROW_MARKER_HOLLOW_DEFAULT_LINE_WIDTH = 1.5;
 * @description 顶层 8 字段全 optional；fill 在空心 shape 上 silent no-op（schema 不拒绝、compile/render 丢字段）；start/end 子对象用相同字段集（无 start/end 递归）
 */
 var ArrowEndDetailSchema = z.object({
-	shape: z.nativeEnum(ARROW_SHAPES).optional().describe("Arrow tip shape. Defaults to `stealth` (sharp barb). Other values: `normal` (filled triangle), `open` (hollow triangle), `diamond`, `openDiamond`, `circle`, `openCircle`."),
-	scale: z.number().positive().optional().describe("Uniform tip scale factor; multiplies `length` and `width` (e.g. `length=10, scale=1.5` → effective 15). Defaults to 1."),
-	length: z.number().nonnegative().optional().describe("Tip length in user units (the dimension along the path direction). Defaults to ~6."),
-	width: z.number().nonnegative().optional().describe("Tip width in user units (perpendicular to the path). Defaults to ~6."),
+	shape: z.string().min(1).optional().describe("Registered arrow name: built-in 7 (`normal` / `open` / `stealth` / `diamond` / `openDiamond` / `circle` / `openCircle`) or an extension arrow registered via `CompileOptions.arrows`. Any non-empty string passes schema validation; unregistered names are rejected at compile time (throw). Defaults to `stealth`."),
+	scale: z.number().finite().positive().optional().describe("Uniform tip scale factor; multiplies `length` and `width` (e.g. `length=10, scale=1.5` → effective 15). Defaults to 1."),
+	length: z.number().finite().nonnegative().optional().describe("Tip length in user units (the dimension along the path direction). Defaults to ~6."),
+	width: z.number().finite().nonnegative().optional().describe("Tip width in user units (perpendicular to the path). Defaults to ~6."),
 	color: z.string().optional().describe("Stroke color override. When omitted, the renderer should inherit the path stroke."),
 	fill: z.string().optional().describe("Fill color override (effective only on solid shapes). Hollow shapes (`open` / `openDiamond` / `openCircle`) silently ignore this field — `color` drives the stroke."),
 	opacity: z.number().min(0).max(1).optional().describe("Arrow opacity 0..1, independent from the path opacity. When omitted, inherits the path opacity."),
-	lineWidth: z.number().nonnegative().optional().describe("Stroke width for hollow shapes (user units). Defaults to 1.5. Solid shapes ignore this field.")
+	lineWidth: z.number().finite().nonnegative().optional().describe("Stroke width for hollow shapes (user units). Defaults to 1.5. Solid shapes ignore this field.")
 }).describe("Per-end arrow visual spec: shape + visual fields (scale / length / width / color / fill / opacity / lineWidth). All optional; omitted fields fall through to top-level `arrowDetail` defaults and then built-in defaults.");
 /**
 * Path 级箭头详细配置 schema