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

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

@@ -157,6 +157,75 @@ export declare const NODE_TEXT_ALIGNS: {
 };
 /** 多行文本对齐字面量类型 */
 export type NodeTextAlign = ValueOf<typeof NODE_TEXT_ALIGNS>;
+/**
+ * 节点附属标签（label）——TikZ `[label=above:foo]` / `[label={[red]30:foo}]` 同义。
+ *
+ * 一个 Node 可挂多个 label（数组形态）；label 自身不参与 viewBox（视觉外延少时可接受）。
+ *
+ * `position` 接受两种形态：
+ * - 8 方向枚举（`above` / `right` / `above-left` ...）：标签贴在 node 该方向边界外
+ * - 数字角度：以 node 中心为原点，按该角度方向投射；约定与 polar 一致（0° = +x，90° = +y 屏幕下方）
+ *
+ * 默认 `position = 'above'`，`distance = 4`（user units，标签与 node 边界的距离）。
+ */
+export declare const NodeLabelSchema: z.ZodObject<{
+    text: z.ZodString;
+    position: z.ZodOptional<z.ZodUnion<[z.ZodNativeEnum<{
+        readonly above: "above";
+        readonly below: "below";
+        readonly left: "left";
+        readonly right: "right";
+        readonly 'above-left': "above-left";
+        readonly 'above-right': "above-right";
+        readonly 'below-left': "below-left";
+        readonly 'below-right': "below-right";
+    }>, z.ZodNumber]>>;
+    distance: z.ZodOptional<z.ZodNumber>;
+    textColor: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+    font: z.ZodOptional<z.ZodObject<{
+        family: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["normal", "bold"]>, z.ZodNumber]>>;
+        style: z.ZodOptional<z.ZodEnum<["normal", "italic", "oblique"]>>;
+    }, "strip", z.ZodTypeAny, {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    }, {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    distance?: number | undefined;
+    position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+    opacity?: number | undefined;
+    font?: {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    } | undefined;
+    textColor?: string | undefined;
+}, {
+    text: string;
+    distance?: number | undefined;
+    position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+    opacity?: number | undefined;
+    font?: {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    } | undefined;
+    textColor?: string | undefined;
+}>;
+/** Node label IR 类型——单条 label 的字段集 */
+export type IRNodeLabel = z.infer<typeof NodeLabelSchema>;
 export declare const NodeSchema: z.ZodObject<{
     type: z.ZodLiteral<"node">;
     id: z.ZodOptional<z.ZodString>;
@@ -166,7 +235,28 @@ export declare const NodeSchema: z.ZodObject<{
         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>]>;
+    position: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('./position').PolarPosition, z.ZodTypeDef, import('./position').PolarPosition>, z.ZodObject<{
+        direction: z.ZodNativeEnum<{
+            readonly above: "above";
+            readonly below: "below";
+            readonly left: "left";
+            readonly right: "right";
+            readonly 'above-left': "above-left";
+            readonly 'above-right': "above-right";
+            readonly 'below-left': "below-left";
+            readonly 'below-right': "below-right";
+        }>;
+        of: z.ZodString;
+        distance: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    }, {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    }>]>;
     rotate: z.ZodOptional<z.ZodNumber>;
     text: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
         text: z.ZodString;
@@ -253,9 +343,124 @@ export declare const NodeSchema: z.ZodObject<{
         weight?: number | "normal" | "bold" | undefined;
         style?: "normal" | "italic" | "oblique" | undefined;
     }>>;
+    label: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        text: z.ZodString;
+        position: z.ZodOptional<z.ZodUnion<[z.ZodNativeEnum<{
+            readonly above: "above";
+            readonly below: "below";
+            readonly left: "left";
+            readonly right: "right";
+            readonly 'above-left': "above-left";
+            readonly 'above-right': "above-right";
+            readonly 'below-left': "below-left";
+            readonly 'below-right': "below-right";
+        }>, z.ZodNumber]>>;
+        distance: z.ZodOptional<z.ZodNumber>;
+        textColor: z.ZodOptional<z.ZodString>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        font: z.ZodOptional<z.ZodObject<{
+            family: z.ZodOptional<z.ZodString>;
+            size: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["normal", "bold"]>, z.ZodNumber]>>;
+            style: z.ZodOptional<z.ZodEnum<["normal", "italic", "oblique"]>>;
+        }, "strip", z.ZodTypeAny, {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        }, {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    }, {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    }>, z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        position: z.ZodOptional<z.ZodUnion<[z.ZodNativeEnum<{
+            readonly above: "above";
+            readonly below: "below";
+            readonly left: "left";
+            readonly right: "right";
+            readonly 'above-left': "above-left";
+            readonly 'above-right': "above-right";
+            readonly 'below-left': "below-left";
+            readonly 'below-right': "below-right";
+        }>, z.ZodNumber]>>;
+        distance: z.ZodOptional<z.ZodNumber>;
+        textColor: z.ZodOptional<z.ZodString>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        font: z.ZodOptional<z.ZodObject<{
+            family: z.ZodOptional<z.ZodString>;
+            size: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["normal", "bold"]>, z.ZodNumber]>>;
+            style: z.ZodOptional<z.ZodEnum<["normal", "italic", "oblique"]>>;
+        }, "strip", z.ZodTypeAny, {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        }, {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    }, {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    }>, "many">]>>;
 }, "strip", z.ZodTypeAny, {
     type: "node";
-    position: [number, number] | import('./position').PolarPosition;
+    position: [number, number] | import('./position').PolarPosition | {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    };
     fill?: string | undefined;
     text?: string | (string | {
         text: string;
@@ -268,6 +473,31 @@ export declare const NodeSchema: z.ZodObject<{
             style?: "normal" | "italic" | "oblique" | undefined;
         } | undefined;
     })[] | undefined;
+    label?: {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    } | {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    }[] | undefined;
     shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
     stroke?: string | undefined;
     strokeWidth?: number | undefined;
@@ -280,6 +510,7 @@ export declare const NodeSchema: z.ZodObject<{
         weight?: number | "normal" | "bold" | undefined;
         style?: "normal" | "italic" | "oblique" | undefined;
     } | undefined;
+    textColor?: string | undefined;
     id?: string | undefined;
     rotate?: number | undefined;
     align?: "left" | "right" | "center" | undefined;
@@ -294,7 +525,6 @@ export declare const NodeSchema: z.ZodObject<{
     scale?: number | undefined;
     xScale?: number | undefined;
     yScale?: number | undefined;
-    textColor?: string | undefined;
     innerXSep?: number | undefined;
     innerYSep?: number | undefined;
     outerSep?: number | undefined;
@@ -302,7 +532,11 @@ export declare const NodeSchema: z.ZodObject<{
     margin?: number | undefined;
 }, {
     type: "node";
-    position: [number, number] | import('./position').PolarPosition;
+    position: [number, number] | import('./position').PolarPosition | {
+        direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+        of: string;
+        distance?: number | undefined;
+    };
     fill?: string | undefined;
     text?: string | (string | {
         text: string;
@@ -315,6 +549,31 @@ export declare const NodeSchema: z.ZodObject<{
             style?: "normal" | "italic" | "oblique" | undefined;
         } | undefined;
     })[] | undefined;
+    label?: {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    } | {
+        text: string;
+        distance?: number | undefined;
+        position?: number | "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right" | undefined;
+        opacity?: number | undefined;
+        font?: {
+            family?: string | undefined;
+            size?: number | undefined;
+            weight?: number | "normal" | "bold" | undefined;
+            style?: "normal" | "italic" | "oblique" | undefined;
+        } | undefined;
+        textColor?: string | undefined;
+    }[] | undefined;
     shape?: "diamond" | "circle" | "rectangle" | "ellipse" | undefined;
     stroke?: string | undefined;
     strokeWidth?: number | undefined;
@@ -327,6 +586,7 @@ export declare const NodeSchema: z.ZodObject<{
         weight?: number | "normal" | "bold" | undefined;
         style?: "normal" | "italic" | "oblique" | undefined;
     } | undefined;
+    textColor?: string | undefined;
     id?: string | undefined;
     rotate?: number | undefined;
     align?: "left" | "right" | "center" | undefined;
@@ -341,7 +601,6 @@ export declare const NodeSchema: z.ZodObject<{
     scale?: number | undefined;
     xScale?: number | undefined;
     yScale?: number | undefined;
-    textColor?: string | undefined;
     innerXSep?: number | undefined;
     innerYSep?: number | undefined;
     outerSep?: number | undefined;

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;AAGxC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX,mCAAmC;AACnC,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,WAAW,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;EAwBpB,CAAC;AAEJ,oCAAoC;AACpC,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsBxB,CAAC;AAEJ,4BAA4B;AAC5B,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAIxB,CAAC;AAEJ,yCAAyC;AACzC,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,kBAAkB;AAClB,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyKpB,CAAC;AAEJ,4CAA4C;AAC5C,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;AAGxC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX,mCAAmC;AACnC,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,WAAW,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;EAwBpB,CAAC;AAEJ,oCAAoC;AACpC,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsBxB,CAAC;AAEJ,4BAA4B;AAC5B,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAIxB,CAAC;AAEJ,yCAAyC;AACzC,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,kBAAkB;AAClB,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCzB,CAAC;AAEJ,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE1D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+KpB,CAAC;AAEJ,4CAA4C;AAC5C,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/es/ir/node.js

@@ -1,5 +1,6 @@
 import { PositionSchema } from "./position/position.js";
 import { PolarPositionSchema } from "./position/polar-position.js";
+import { AT_DIRECTIONS, AtPositionSchema } from "./position/at-position.js";
 import { z } from "zod";
 //#region src/ir/node.ts
 /**
@@ -70,11 +71,34 @@ var NODE_TEXT_ALIGNS = {
 	center: "center",
 	right: "right"
 };
+/**
+* 节点附属标签（label）——TikZ `[label=above:foo]` / `[label={[red]30:foo}]` 同义。
+*
+* 一个 Node 可挂多个 label（数组形态）；label 自身不参与 viewBox（视觉外延少时可接受）。
+*
+* `position` 接受两种形态：
+* - 8 方向枚举（`above` / `right` / `above-left` ...）：标签贴在 node 该方向边界外
+* - 数字角度：以 node 中心为原点，按该角度方向投射；约定与 polar 一致（0° = +x，90° = +y 屏幕下方）
+*
+* 默认 `position = 'above'`，`distance = 4`（user units，标签与 node 边界的距离）。
+*/
+var NodeLabelSchema = z.object({
+	text: z.string().describe("Label text content; rendered as a single line."),
+	position: z.union([z.nativeEnum(AT_DIRECTIONS), z.number()]).optional().describe("Placement around the node border: 8-direction enum (above / right / above-left / ...) or numeric angle in degrees (`label=30:foo` for radial placement). Default `above`. Numeric uses the polar convention (0° = +x, 90° = +y, screen-down)."),
+	distance: z.number().nonnegative().optional().describe("Gap between the node border and the label center, in user units. Default 4."),
+	textColor: z.string().optional().describe("Label text color; falls back to currentColor."),
+	opacity: z.number().min(0).max(1).optional().describe("Label-only opacity 0..1; multiplied with the node opacity if both are set."),
+	font: FontSchema.optional().describe("Label font overrides; missing fields inherit from the parent node font, then renderer defaults.")
+}).describe("Extra text attached around a node border. Multiple labels supported via array form on `Node.label`.");
 var NodeSchema = z.object({
 	type: z.literal("node").describe("Discriminator marking this child as a node"),
 	id: z.string().min(1).optional().describe("Optional unique id; required if any path needs to reference this node by string"),
 	shape: z.nativeEnum(NODE_SHAPES).optional().describe("Node visual shape; defaults to `rectangle`. The boundary fully contains text + padding (circumscribed for circle / ellipse / diamond)."),
-	position: z.union([PositionSchema, PolarPositionSchema]).describe("Center point of the node content box; Cartesian [x, y] or polar (resolved at compile time)"),
+	position: z.union([
+		PositionSchema,
+		PolarPositionSchema,
+		AtPositionSchema
+	]).describe("Center point of the node content box; Cartesian [x, y], polar, or relative-to-another-node (`at`-style with `direction` / `of` / `distance?`). 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: NodeTextSchema.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)."),
@@ -101,7 +125,8 @@ var NodeSchema = z.object({
 	outerSep: z.number().nonnegative().optional().describe("Outer margin from border to path attachment point in user units; does NOT change the visible border. Falls back to `margin`."),
 	padding: z.number().nonnegative().optional().describe("Symmetric inner padding (alias for `innerXSep` + `innerYSep`); axis-specific fields take precedence."),
 	margin: z.number().nonnegative().optional().describe("Symmetric outer margin (alias for `outerSep`); axis-specific field takes precedence."),
-	font: FontSchema.optional().describe("Font spec for the inner text label (family / size / weight / style); all fields optional, all fall back to renderer defaults.")
+	font: FontSchema.optional().describe("Font spec for the inner text label (family / size / weight / style); all fields optional, all fall back to renderer defaults."),
+	label: z.union([NodeLabelSchema, z.array(NodeLabelSchema)]).optional().describe("Extra label(s) attached around the node border (TikZ `[label=above:foo]`); single object or array form. Compiled into one TextPrim per label, positioned by `position` direction / angle and `distance`.")
 }).describe("Node primitive: a positioned, optionally textual shape (rectangle / circle / ellipse / diamond)");
 //#endregion
-export { FontSchema, LineSpecSchema, NODE_SHAPES, NODE_TEXT_ALIGNS, NodeSchema, NodeTextSchema };
+export { FontSchema, LineSpecSchema, NODE_SHAPES, NODE_TEXT_ALIGNS, NodeLabelSchema, NodeSchema, NodeTextSchema };

package/dist/es/ir/position/at-position.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { ValueOf } from '../../types';
+/**
+ * 节点相对方向常量。8 方向（4 主向 + 4 对角），按视觉语义：
+ * - above:  y 减小（视觉上方）
+ * - below:  y 增大（视觉下方）
+ * - left:   x 减小（视觉左方）
+ * - right:  x 增大（视觉右方）
+ * - 4 对角：两轴各 1/√2 单位向量分量（对角距离与 distance 等长）
+ *
+ * 与 TikZ `positioning` library 的 `above of` / `right of` / `above right of` 对齐
+ * （TikZ y 向上、retikz y 向下，但 `above` 视觉语义在两边一致——视觉上方）。
+ */
+export declare const AT_DIRECTIONS: {
+    readonly above: "above";
+    readonly below: "below";
+    readonly left: "left";
+    readonly right: "right";
+    readonly 'above-left': "above-left";
+    readonly 'above-right': "above-right";
+    readonly 'below-left': "below-left";
+    readonly 'below-right': "below-right";
+};
+/** at 方向字面量类型；由 `AT_DIRECTIONS` 派生 */
+export type AtDirection = ValueOf<typeof AT_DIRECTIONS>;
+export declare const AtPositionSchema: z.ZodObject<{
+    direction: z.ZodNativeEnum<{
+        readonly above: "above";
+        readonly below: "below";
+        readonly left: "left";
+        readonly right: "right";
+        readonly 'above-left': "above-left";
+        readonly 'above-right': "above-right";
+        readonly 'below-left': "below-left";
+        readonly 'below-right': "below-right";
+    }>;
+    of: z.ZodString;
+    distance: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+    of: string;
+    distance?: number | undefined;
+}, {
+    direction: "above" | "below" | "left" | "right" | "above-left" | "above-right" | "below-left" | "below-right";
+    of: string;
+    distance?: number | undefined;
+}>;
+/** 相对定位的 IR 类型——`{ direction, of, distance? }`，与 `IRPosition` / `PolarPosition` 在 union 里平级 */
+export type IRAtPosition = z.infer<typeof AtPositionSchema>;
+//# sourceMappingURL=at-position.d.ts.map

package/dist/es/ir/position/at-position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"at-position.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/at-position.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;;;;;;;;;CAShB,CAAC;AAEX,sCAAsC;AACtC,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAuB1B,CAAC;AAEJ,+FAA+F;AAC/F,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/es/ir/position/at-position.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+//#region src/ir/position/at-position.ts
+/**
+* 节点相对方向常量。8 方向（4 主向 + 4 对角），按视觉语义：
+* - above:  y 减小（视觉上方）
+* - below:  y 增大（视觉下方）
+* - left:   x 减小（视觉左方）
+* - right:  x 增大（视觉右方）
+* - 4 对角：两轴各 1/√2 单位向量分量（对角距离与 distance 等长）
+*
+* 与 TikZ `positioning` library 的 `above of` / `right of` / `above right of` 对齐
+* （TikZ y 向上、retikz y 向下，但 `above` 视觉语义在两边一致——视觉上方）。
+*/
+var AT_DIRECTIONS = {
+	above: "above",
+	below: "below",
+	left: "left",
+	right: "right",
+	"above-left": "above-left",
+	"above-right": "above-right",
+	"below-left": "below-left",
+	"below-right": "below-right"
+};
+var AtPositionSchema = z.object({
+	direction: z.nativeEnum(AT_DIRECTIONS).describe("Direction from the referenced node toward this node, in visual convention (above = visually upward, screen y-)."),
+	of: z.string().min(1).describe("Id of the referenced node or coordinate; must be defined earlier in the IR (forward references rejected, mirroring polar `origin` and string targets)."),
+	distance: z.number().positive().optional().describe("Distance from the referenced node center to this node center in user units. Falls back to the Tikz `nodeDistance` compile-time context, then to 1.")
+}).describe("Relative position: place this node at `direction` direction from `of`, `distance` away. Mirrors TikZ `[<direction>=<distance> of <id>]` from the positioning library.");
+//#endregion
+export { AT_DIRECTIONS, AtPositionSchema };

package/dist/es/ir/position/index.d.ts

@@ -1,3 +1,4 @@
 export * from './position';
 export * from './polar-position';
+export * from './at-position';
 //# sourceMappingURL=index.d.ts.map

package/dist/es/ir/position/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC"}