@retikz/core 0.1.0-alpha.4 → 0.1.0-beta.1

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

@@ -1 +1 @@
-{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../../src/ir/path/step.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../../src/ir/path/step.ts"],"names":[],"mappings":"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"}

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

@@ -3,17 +3,20 @@ import { TargetSchema } from "./target.js";
 import { z } from "zod";
 //#region src/ir/path/step.ts
 /**
-* 边标注（ADR-0004）：挂在画线 step 上的 label，渲染时按段几何 + side 偏移
-* 翻译为一个 TextPrim。`move` / `cycle` 不挂 label——前者不画线、后者是闭合
-* 标记，标签语义不清。
+* 边标注：画线 step 上的 label
+* @description 按段几何 + side 偏移翻译为 TextPrim；move/cycle 不挂 label
 */
 var StepLabelSchema = z.object({
 	text: z.string().describe("Label text content. Single-line; for multi-line use \\n."),
-	position: z.enum([
-		"midway",
+	position: z.union([z.enum([
+		"at-start",
+		"very-near-start",
 		"near-start",
-		"near-end"
-	]).optional().describe("Position along the step segment (TikZ `midway` / `near start` / `near end`). Default `midway`."),
+		"midway",
+		"near-end",
+		"very-near-end",
+		"at-end"
+	]), z.number().min(0).max(1)]).optional().describe("Normalized position t along the step (TikZ `pos`). Accepts a number 0..1 or one of 7 keyword sugars (at-start=0 / very-near-start=0.125 / near-start=0.25 / midway=0.5 / near-end=0.75 / very-near-end=0.875 / at-end=1). Geometric meaning of t varies by step kind: line/step use normalized arc length (fold partitions t equally across N legs — corner sits at t=j/N); curve/cubic/bend use the Bezier parameter (NOT arc length, so t=0.5 is not always the visual midpoint); arc maps t linearly across startAngle..endAngle; circlePath/ellipsePath use angle parametrization with t=0 at angle 0 (+x axis), CCW growth. Default `midway` (t=0.5)."),
 	side: z.enum([
 		"above",
 		"below",
@@ -21,15 +24,15 @@ var StepLabelSchema = z.object({
 		"right",
 		"sloped"
 	]).optional().describe("Side relative to segment direction. `above` / `below` / `left` / `right` offset along segment normal; `sloped` rotates label along the tangent (no normal offset). Default `above`.")
-}).describe("Edge label spec attached to a drawn step (ADR-0004); compiled to a TextPrim positioned along the segment.");
+}).describe("Edge label spec attached to a drawn step; compiled to a TextPrim positioned along the segment.");
 var MoveStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
-	kind: z.literal("move").describe("Move the cursor to the target without drawing (like SVG path \"M\")"),
+	kind: z.literal("move").describe("Move the cursor to the target without drawing (TikZ `(A)`, no drawing operation)"),
 	to: TargetSchema.describe("Destination point of the move")
 }).describe("Move action: relocate the path cursor without drawing");
 var LineStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
-	kind: z.literal("line").describe("Draw a straight line from the current cursor to the target (like SVG path \"L\")"),
+	kind: z.literal("line").describe("Draw a straight line from the current cursor to the target (TikZ `(A) -- (B)`)"),
 	to: TargetSchema.describe("Destination point of the line segment"),
 	label: StepLabelSchema.optional().describe("Edge label attached to this line segment")
 }).describe("Line action: straight-line segment from cursor to target");
@@ -42,27 +45,23 @@ var FoldStepSchema = z.object({
 }).describe("Fold action: TikZ-style right-angle fold with a single intermediate point chosen by `via`");
 var CycleStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
-	kind: z.literal("cycle").describe("Close the path back to the most recent move target (TikZ `cycle` / SVG path \"Z\")")
+	kind: z.literal("cycle").describe("Close the path back to the most recent move target (TikZ `cycle`)")
 }).describe("Cycle action: close the current sub-path back to its starting point; carries no `to` field");
 /**
-* 控制点的 schema 别名。
-*
-* alpha.3：仅支持笛卡尔 `[x, y]`（与 ADR-0001 字面一致）。
-* 未来扩展点：要支持节点 ref / 极坐标作为控制点（如 TikZ `controls (B)`）时，
-* 只把这里改成 `z.union([PositionSchema, PolarPositionSchema, z.string().min(1)])`，
-* curve / cubic schema 与下游消费侧不变。
+* 控制点 schema 别名
+* @description 当前仅支持笛卡尔 `[x,y]`；未来扩展节点 ref/极坐标时只改本处 union，curve/cubic schema 与下游不变
 */
 var ControlPointSchema = PositionSchema.describe("Bezier control point. Currently Cartesian [x, y]; reserved for node ref / polar in future versions.");
 var CurveStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
-	kind: z.literal("curve").describe("Quadratic Bezier curve from cursor to target with one control point (TikZ `.. controls (B) ..`, SVG path \"Q\")"),
+	kind: z.literal("curve").describe("Quadratic Bezier curve from cursor to target with one control point (TikZ `.. controls (B) ..`)"),
 	to: TargetSchema.describe("Destination point of the curve"),
 	control: ControlPointSchema.describe("Single control point for the quadratic Bezier"),
 	label: StepLabelSchema.optional().describe("Edge label attached to this quadratic Bezier")
 }).describe("Curve action: quadratic Bezier; one control point shapes the bend");
 var CubicStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
-	kind: z.literal("cubic").describe("Cubic Bezier curve from cursor to target with two control points (TikZ `.. controls (B) and (C) ..`, SVG path \"C\")"),
+	kind: z.literal("cubic").describe("Cubic Bezier curve from cursor to target with two control points (TikZ `.. controls (B) and (C) ..`)"),
 	to: TargetSchema.describe("Destination point of the cubic curve"),
 	control1: ControlPointSchema.describe("First control point (influences the start tangent)"),
 	control2: ControlPointSchema.describe("Second control point (influences the end tangent)"),
@@ -79,20 +78,20 @@ var BendStepSchema = z.object({
 var ArcStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
 	kind: z.literal("arc").describe("Arc segment from cursor as center, sweeping startAngle → endAngle on a circle of given radius (TikZ `arc[start angle=…, end angle=…, radius=…]`); pen ends at the arc endpoint, not the center"),
-	startAngle: z.number().describe("Arc start angle in degrees, CCW from +x axis (math convention; SVG y-down means visual CW)"),
+	startAngle: z.number().describe("Arc start angle in degrees, measured from +x axis. 0° = +x, 90° = +y = screen-down (visual clockwise under screen y-down); matches polar / Node label angle convention."),
 	endAngle: z.number().describe("Arc end angle in degrees; sweep direction inferred from startAngle vs endAngle"),
 	radius: z.number().positive().describe("Arc radius in user units"),
 	label: StepLabelSchema.optional().describe("Edge label attached to this arc")
 }).describe("Arc action: TikZ-style arc with implicit center at the cursor; startAngle / endAngle / radius give the geometry. Pen is left at the arc endpoint.");
 var CirclePathStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
-	kind: z.literal("circlePath").describe("Full circle centered at the cursor with given radius (TikZ `circle[radius=…]`); SVG path emits two semi-arcs to avoid the 360° A-command degeneracy. Pen returns to the center."),
+	kind: z.literal("circlePath").describe("Full circle centered at the cursor with given radius (TikZ `circle[radius=…]`); compiled to a single full-sweep ellipse arc command. Pen returns to the center."),
 	radius: z.number().positive().describe("Circle radius in user units"),
 	label: StepLabelSchema.optional().describe("Edge label attached to this full circle")
 }).describe("CirclePath action: full closed circle around the cursor as center; pen returns to center after.");
 var EllipsePathStepSchema = z.object({
 	type: z.literal("step").describe("Discriminator marking this as a path step node"),
-	kind: z.literal("ellipsePath").describe("Full ellipse centered at the cursor with given x/y radii (TikZ `ellipse[x radius=…, y radius=…]`); SVG path emits two semi-arcs. Pen returns to the center."),
+	kind: z.literal("ellipsePath").describe("Full ellipse centered at the cursor with given x/y radii (TikZ `ellipse[x radius=…, y radius=…]`); compiled to a single full-sweep ellipse arc command. Pen returns to the center."),
 	radiusX: z.number().positive().describe("Ellipse x-axis radius (semi-major or semi-minor on x)"),
 	radiusY: z.number().positive().describe("Ellipse y-axis radius (semi-major or semi-minor on y)"),
 	label: StepLabelSchema.optional().describe("Edge label attached to this full ellipse")

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

@@ -1,35 +1,44 @@
 import { z } from 'zod';
-export declare const RelTargetSchema: z.ZodObject<{
-    rel: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+export declare const RelativeTargetSchema: z.ZodObject<{
+    relative: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
 }, "strip", z.ZodTypeAny, {
-    rel: [number, number];
+    relative: [number, number];
 }, {
-    rel: [number, number];
+    relative: [number, number];
 }>;
-export declare const RelAccumulateTargetSchema: z.ZodObject<{
-    relAccumulate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+export declare const RelativeAccumulateTargetSchema: z.ZodObject<{
+    relativeAccumulate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
 }, "strip", z.ZodTypeAny, {
-    relAccumulate: [number, number];
+    relativeAccumulate: [number, number];
 }, {
-    relAccumulate: [number, number];
+    relativeAccumulate: [number, number];
 }>;
 export declare const TargetSchema: z.ZodUnion<[z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('..').PolarPosition, z.ZodTypeDef, import('..').PolarPosition>, z.ZodString, z.ZodObject<{
-    rel: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    relative: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
 }, "strip", z.ZodTypeAny, {
-    rel: [number, number];
+    relative: [number, number];
 }, {
-    rel: [number, number];
+    relative: [number, number];
 }>, z.ZodObject<{
-    relAccumulate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    relativeAccumulate: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
 }, "strip", z.ZodTypeAny, {
-    relAccumulate: [number, number];
+    relativeAccumulate: [number, number];
 }, {
-    relAccumulate: [number, number];
+    relativeAccumulate: [number, number];
+}>, z.ZodObject<{
+    of: z.ZodUnion<[z.ZodString, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('..').PolarPosition, z.ZodTypeDef, import('..').PolarPosition>]>;
+    offset: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+}, "strip", z.ZodTypeAny, {
+    of: string | [number, number] | import('..').PolarPosition;
+    offset: [number, number];
+}, {
+    of: string | [number, number] | import('..').PolarPosition;
+    offset: [number, number];
 }>]>;
 /** 路径端点：直接坐标 [x, y]、极坐标、节点 id 字符串、相对偏移对象 */
 export type IRTarget = z.infer<typeof TargetSchema>;
 /** 相对前一 step 终点的偏移；不更新 prevEnd（TikZ `(+x, +y)`） */
-export type IRRelTarget = z.infer<typeof RelTargetSchema>;
+export type IRRelativeTarget = z.infer<typeof RelativeTargetSchema>;
 /** 累积相对偏移；更新 prevEnd（TikZ `(++x, ++y)`） */
-export type IRRelAccumulateTarget = z.infer<typeof RelAccumulateTargetSchema>;
+export type IRRelativeAccumulateTarget = z.infer<typeof RelativeAccumulateTargetSchema>;
 //# sourceMappingURL=target.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../../../src/ir/path/target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,eAAe;;;;;;EAQzB,CAAC;AAEJ,eAAO,MAAM,yBAAyB;;;;;;EAQnC,CAAC;AAEJ,eAAO,MAAM,YAAY;;;;;;;;;;;;IAUtB,CAAC;AAEJ,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEpD,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE1D,2CAA2C;AAC3C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../../../src/ir/path/target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,oBAAoB;;;;;;EAQ9B,CAAC;AAEJ,eAAO,MAAM,8BAA8B;;;;;;EAQxC,CAAC;AAEJ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;IAWtB,CAAC;AAEJ,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEpD,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEpE,2CAA2C;AAC3C,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC"}

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

@@ -1,15 +1,17 @@
 import { PositionSchema } from "../position/position.js";
 import { PolarPositionSchema } from "../position/polar-position.js";
+import { OffsetPositionSchema } from "../position/offset-position.js";
 import { z } from "zod";
 //#region src/ir/path/target.ts
-var RelTargetSchema = z.object({ rel: z.tuple([z.number(), z.number()]).describe("Relative offset (dx, dy)") }).describe("Relative offset from the previous step end point (does NOT update the cursor position; matches TikZ `(+x, +y)` syntax)");
-var RelAccumulateTargetSchema = z.object({ relAccumulate: z.tuple([z.number(), z.number()]).describe("Accumulated relative offset (dx, dy)") }).describe("Accumulated relative offset from the previous step end point (DOES update the cursor; matches TikZ `(++x, ++y)` syntax)");
+var RelativeTargetSchema = z.object({ relative: z.tuple([z.number(), z.number()]).describe("Relative offset (dx, dy)") }).describe("Relative offset from the previous step end point (does NOT update the cursor position; matches TikZ `(+x, +y)` syntax)");
+var RelativeAccumulateTargetSchema = z.object({ relativeAccumulate: z.tuple([z.number(), z.number()]).describe("Accumulated relative offset (dx, dy)") }).describe("Accumulated relative offset from the previous step end point (DOES update the cursor; matches TikZ `(++x, ++y)` syntax)");
 var TargetSchema = z.union([
 	PositionSchema,
 	PolarPositionSchema,
 	z.string().min(1),
-	RelTargetSchema,
-	RelAccumulateTargetSchema
-]).describe("Path endpoint: Cartesian [x, y], polar position, node id reference, or relative offset object ({ rel } / { relAccumulate }) resolved at compile time");
+	RelativeTargetSchema,
+	RelativeAccumulateTargetSchema,
+	OffsetPositionSchema
+]).describe("Path endpoint: Cartesian [x, y], polar position, node id reference, relative offset object ({ relative } / { relativeAccumulate }), or offset position ({ of, offset } mirroring TikZ `calc`) resolved at compile time");
 //#endregion
-export { RelAccumulateTargetSchema, RelTargetSchema, TargetSchema };
+export { RelativeAccumulateTargetSchema, RelativeTargetSchema, TargetSchema };

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

@@ -1,15 +1,8 @@
 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` 视觉语义在两边一致——视觉上方）。
+ * 节点相对方向 8 方向常量（视觉语义）
+ * @description above/below=y 减/增（视觉上/下）；left/right=x 减/增；4 对角分量 1/√2 让对角距离与 distance 等长。与 TikZ positioning 的 `above of` 等对齐（TikZ y 向上 retikz y 向下，但视觉语义一致）
  */
 export declare const AT_DIRECTIONS: {
     readonly above: "above";
@@ -21,7 +14,7 @@ export declare const AT_DIRECTIONS: {
     readonly 'below-left': "below-left";
     readonly 'below-right': "below-right";
 };
-/** at 方向字面量类型；由 `AT_DIRECTIONS` 派生 */
+/** at 方向字面量类型 */
 export type AtDirection = ValueOf<typeof AT_DIRECTIONS>;
 export declare const AtPositionSchema: z.ZodObject<{
     direction: z.ZodNativeEnum<{
@@ -45,6 +38,6 @@ export declare const AtPositionSchema: z.ZodObject<{
     of: string;
     distance?: number | undefined;
 }>;
-/** 相对定位的 IR 类型——`{ direction, of, distance? }`，与 `IRPosition` / `PolarPosition` 在 union 里平级 */
+/** 相对定位 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

@@ -1 +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"}
+{"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;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;CAShB,CAAC;AAEX,iBAAiB;AACjB,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAuB1B,CAAC;AAEJ,oFAAoF;AACpF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

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

@@ -1,15 +1,8 @@
 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` 视觉语义在两边一致——视觉上方）。
+* 节点相对方向 8 方向常量（视觉语义）
+* @description above/below=y 减/增（视觉上/下）；left/right=x 减/增；4 对角分量 1/√2 让对角距离与 distance 等长。与 TikZ positioning 的 `above of` 等对齐（TikZ y 向上 retikz y 向下，但视觉语义一致）
 */
 var AT_DIRECTIONS = {
 	above: "above",

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

@@ -1,4 +1,5 @@
 export * from './position';
 export * from './polar-position';
 export * from './at-position';
+export * from './offset-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;AACjC,cAAc,eAAe,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;AAC9B,cAAc,mBAAmB,CAAC"}

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

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const OffsetPositionSchema: z.ZodObject<{
+    of: z.ZodUnion<[z.ZodString, z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, z.ZodType<import('./polar-position').PolarPosition, z.ZodTypeDef, import('./polar-position').PolarPosition>]>;
+    offset: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+}, "strip", z.ZodTypeAny, {
+    of: string | [number, number] | import('./polar-position').PolarPosition;
+    offset: [number, number];
+}, {
+    of: string | [number, number] | import('./polar-position').PolarPosition;
+    offset: [number, number];
+}>;
+/** 偏移定位 IR 类型 `{ of, offset }`，与 IRPosition/PolarPosition/IRAtPosition union 平级 */
+export type IROffsetPosition = z.infer<typeof OffsetPositionSchema>;
+//# sourceMappingURL=offset-position.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"offset-position.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/offset-position.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,oBAAoB;;;;;;;;;EAa9B,CAAC;AAEJ,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

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

@@ -0,0 +1,14 @@
+import { PositionSchema } from "./position.js";
+import { PolarPositionSchema } from "./polar-position.js";
+import { z } from "zod";
+//#region src/ir/position/offset-position.ts
+var OffsetPositionSchema = z.object({
+	of: z.union([
+		z.string().min(1),
+		PositionSchema,
+		PolarPositionSchema
+	]).describe("Reference base point: node id string (forward references rejected), Cartesian [x, y] literal (no pre-definition needed), or PolarPosition (recursive polar chain via its own origin). Mirrors PolarPosition.origin union shape."),
+	offset: z.tuple([z.number().finite(), z.number().finite()]).describe("Offset (dx, dy) from the reference point in user units; rejects NaN / ±Infinity")
+}).describe("Offset position: base point `of` plus a Cartesian `(dx, dy)` offset. Mirrors TikZ `calc` syntax `($(of) + (dx, dy)$)`. The base point may itself be a node id, a literal coordinate, or a polar expression — covering all referent shapes available to PolarPosition.origin.");
+//#endregion
+export { OffsetPositionSchema };

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

@@ -1,9 +1,6 @@
 import { z } from 'zod';
 import { PolarPosition } from '../../geometry/polar';
-/**
- * 极坐标点 schema（递归——origin 可嵌套）。
- * 用 z.lazy 处理自引用；TS 类型从 geometry/polar 导入并 cast 到 schema。
- */
+/** 极坐标点 schema（递归 origin 可嵌套）；z.lazy 处理自引用，TS 类型从 geometry/polar 导入 */
 export declare const PolarPositionSchema: z.ZodType<PolarPosition>;
 export type { PolarPosition } from '../../geometry/polar';
 //# sourceMappingURL=polar-position.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"polar-position.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/polar-position.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAmBxD,CAAC;AAGF,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"polar-position.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/polar-position.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAuBxD,CAAC;AAGF,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

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

@@ -1,18 +1,15 @@
 import { PositionSchema } from "./position.js";
 import { z } from "zod";
 //#region src/ir/position/polar-position.ts
-/**
-* 极坐标点 schema（递归——origin 可嵌套）。
-* 用 z.lazy 处理自引用；TS 类型从 geometry/polar 导入并 cast 到 schema。
-*/
+/** 极坐标点 schema（递归 origin 可嵌套）；z.lazy 处理自引用，TS 类型从 geometry/polar 导入 */
 var PolarPositionSchema = z.lazy(() => z.object({
 	origin: z.union([
 		z.string().min(1),
 		PositionSchema,
 		PolarPositionSchema
 	]).optional().describe("Origin reference: node id string, Cartesian [x, y], or nested PolarPosition (chained); defaults to [0, 0] when omitted"),
-	angle: z.number().describe("Angle in degrees, counter-clockwise positive (TikZ convention)"),
-	radius: z.number().describe("Radius / distance in user units")
+	angle: z.number().finite().describe("Angle in degrees, measured from +x axis (0°). 90° = +y = screen-down (visual clockwise under screen y-down); negative angles go upward. Matches retikz convention used by ArcStep / Node label."),
+	radius: z.number().finite().describe("Radius / distance in user units")
 }).describe("Polar coordinate position; resolved to Cartesian at Scene compile time"));
 //#endregion
 export { PolarPositionSchema };

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

@@ -1 +1 @@
-{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/position.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc,8CAEa,CAAC;AAEzC,mBAAmB;AACnB,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../../src/ir/position/position.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc,8CAEqF,CAAC;AAEjH,mBAAmB;AACnB,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
 //#region src/ir/position/position.ts
-var PositionSchema = z.tuple([z.number(), z.number()]).describe("Cartesian position [x, y]");
+var PositionSchema = z.tuple([z.number().finite(), z.number().finite()]).describe("Cartesian position [x, y]; rejects NaN / ±Infinity to keep IR JSON-serializable round-trip stable");
 //#endregion
 export { PositionSchema };