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

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

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+/**
+ * 单行文本规格：纯字符串走块级默认，对象形式可覆盖 fill/opacity/font
+ * @description 行级覆盖只生效于本行；font 子字段未填则继承块级；align/lineHeight 不可被行覆盖
+ */
+export declare const LineSpecSchema: z.ZodUnion<[z.ZodString, z.ZodObject<{
+    text: z.ZodString;
+    fill: 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;
+    fill?: string | undefined;
+    opacity?: number | undefined;
+    font?: {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    } | undefined;
+}, {
+    text: string;
+    fill?: string | undefined;
+    opacity?: number | undefined;
+    font?: {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    } | undefined;
+}>]>;
+/** 行规格 IR 类型 */
+export type IRLineSpec = z.infer<typeof LineSpecSchema>;
+/**
+ * 文本块：单字符串或非空多行 LineSpec 数组
+ * @description 选数组而非 `\n` 字符串：JSON 友好无 escape，行级覆盖天然落字段；通用文本结构，Node text / 未来 Step.label 等共用
+ */
+export declare const TextBlockSchema: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
+    text: z.ZodString;
+    fill: 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;
+    fill?: string | undefined;
+    opacity?: number | undefined;
+    font?: {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    } | undefined;
+}, {
+    text: string;
+    fill?: string | undefined;
+    opacity?: number | undefined;
+    font?: {
+        family?: string | undefined;
+        size?: number | undefined;
+        weight?: number | "normal" | "bold" | undefined;
+        style?: "normal" | "italic" | "oblique" | undefined;
+    } | undefined;
+}>]>, "many">]>;
+/** 文本块 IR 类型（单字符串或多行 LineSpec 数组） */
+export type IRTextBlock = z.infer<typeof TextBlockSchema>;
+//# sourceMappingURL=text.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/ir/text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsBxB,CAAC;AAEJ,gBAAgB;AAChB,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAIzB,CAAC;AAEJ,qCAAqC;AACrC,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/es/ir/text.js

@@ -0,0 +1,20 @@
+import { FontSchema } from "./font.js";
+import { z } from "zod";
+//#region src/ir/text.ts
+/**
+* 单行文本规格：纯字符串走块级默认，对象形式可覆盖 fill/opacity/font
+* @description 行级覆盖只生效于本行；font 子字段未填则继承块级；align/lineHeight 不可被行覆盖
+*/
+var LineSpecSchema = z.union([z.string(), z.object({
+	text: z.string().describe("Line content"),
+	fill: z.string().optional().describe("Per-line text color; overrides block default"),
+	opacity: z.number().min(0).max(1).optional().describe("Per-line opacity 0..1"),
+	font: FontSchema.optional().describe("Per-line font overrides; missing fields inherit from block-level `font`")
+})]).describe("Single line of text: bare string for default styling, or an object with per-line `fill` / `opacity` / `font` overrides.");
+/**
+* 文本块：单字符串或非空多行 LineSpec 数组
+* @description 选数组而非 `\n` 字符串：JSON 友好无 escape，行级覆盖天然落字段；通用文本结构，Node text / 未来 Step.label 等共用
+*/
+var TextBlockSchema = z.union([z.string(), z.array(LineSpecSchema).min(1)]).describe("Text block: a single string for one line, or a non-empty array of line specs (string for default, object for per-line overrides).");
+//#endregion
+export { LineSpecSchema, TextBlockSchema };

package/dist/es/parsers/parseTargetSugar.d.ts

@@ -1,3 +1,7 @@
 import { IRTarget } from '../ir';
+/**
+ * Sugar 字符串解析：TikZ 风格相对偏移字面量 → IR 对象
+ * @description `'+dx,dy'` → `{relative:[dx,dy]}`（TikZ `+`，不更新 prevEnd）；`'++dx,dy'` → `{relativeAccumulate:[dx,dy]}`（TikZ `++`，累积）；其他形态（节点 id、笛卡尔 / 极坐标、已是 relative 对象）原样返回。纯函数无 nodeIndex 依赖，react adapter 与 Draw DSL 共用
+ */
 export declare const parseTargetSugar: (input: unknown) => IRTarget;
 //# sourceMappingURL=parseTargetSugar.d.ts.map

package/dist/es/parsers/parseTargetSugar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseTargetSugar.d.ts","sourceRoot":"","sources":["../../../src/parsers/parseTargetSugar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAQtC,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,QAWjD,CAAC"}
+{"version":3,"file":"parseTargetSugar.d.ts","sourceRoot":"","sources":["../../../src/parsers/parseTargetSugar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAKtC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,QAWjD,CAAC"}

package/dist/es/parsers/parseTargetSugar.js

@@ -1,9 +1,10 @@
 //#region src/parsers/parseTargetSugar.ts
+/** TikZ 风格相对偏移字面量正则：捕获 `+` / `++` 前缀 + dx / dy 数值 */
+var RELATIVE_OFFSET_RE = /^(\+{1,2})\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)$/;
 /**
 * Sugar 字符串解析：TikZ 风格相对偏移字面量 → IR 对象
-* @description `'+dx,dy'` → `{relative:[dx,dy]}`（TikZ `+`，不更新 prevEnd）；`'++dx,dy'` → `{relativeAccumulate:[dx,dy]}`（TikZ `++`，累积）；其他形态（节点 id、笛卡尔/极坐标、已是 relative 对象）原样返回。纯函数无 nodeIndex 依赖，react adapter 与 Draw DSL 共用
+* @description `'+dx,dy'` → `{relative:[dx,dy]}`（TikZ `+`，不更新 prevEnd）；`'++dx,dy'` → `{relativeAccumulate:[dx,dy]}`（TikZ `++`，累积）；其他形态（节点 id、笛卡尔 / 极坐标、已是 relative 对象）原样返回。纯函数无 nodeIndex 依赖，react adapter 与 Draw DSL 共用
 */
-var RELATIVE_OFFSET_RE = /^(\+{1,2})\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)$/;
 var parseTargetSugar = (input) => {
 	if (typeof input !== "string") return input;
 	const match = input.match(RELATIVE_OFFSET_RE);

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

@@ -1,6 +1,6 @@
 /**
- * 椭圆原语，对应 SVG `<ellipse>`
- * @description 圆形（rx=ry）复用同一 prim 单 case 处理；rotate 度数绕中心，非零时 renderer 用 SVG transform 包裹
+ * 椭圆原语（cx/cy 圆心，rx/ry 半径）
+ * @description 圆形（rx=ry）复用同一 prim 单 case 处理；rotate 度数绕中心，非零时由 renderer 在 emit 阶段应用旋转变换
  */
 export type EllipsePrim = {
     type: 'ellipse';

package/dist/es/primitive/group.d.ts

@@ -1,22 +1,38 @@
 import { ScenePrimitive } from './scene';
-/**
- * Group transform：结构化变换
- * @description 按数组顺序应用（与 SVG transform 多操作列表语义一致）；角度=度，缩放 y 缺省等比 x，rotate cx/cy 缺省绕原点
- */
-export type Transform = {
+/** Translate transform：沿 x / y 平移（user units） */
+export type TranslateTransform = {
+    /** 鉴别字面量 */
     kind: 'translate';
+    /** x 方向位移 */
     x: number;
+    /** y 方向位移（屏幕 y-down） */
     y: number;
-} | {
+};
+/** Rotate transform：按角度旋转，可指定旋转中心；中心缺省 = 绕原点 (0, 0) */
+export type RotateTransform = {
+    /** 鉴别字面量 */
     kind: 'rotate';
+    /** 旋转角度（度，正向 = 屏幕 y-down 下的视觉顺时针） */
     degrees: number;
+    /** 旋转中心 x（缺省 0） */
     cx?: number;
+    /** 旋转中心 y（缺省 0） */
     cy?: number;
-} | {
+};
+/** Scale transform：等比 / 非等比缩放；y 缺省 = x（等比） */
+export type ScaleTransform = {
+    /** 鉴别字面量 */
     kind: 'scale';
+    /** x 轴缩放因子 */
     x: number;
+    /** y 轴缩放因子；缺省 = x（等比缩放） */
     y?: number;
 };
+/**
+ * Group transform：结构化变换（3 分支 discriminated union）
+ * @description 按数组顺序应用（与 SVG transform 多操作列表语义一致）；角度=度，缩放 y 缺省等比 x，rotate cx/cy 缺省绕原点。每个 kind 有对应 named type export。
+ */
+export type Transform = TranslateTransform | RotateTransform | ScaleTransform;
 /** 编组：把若干 primitive 用结构化 transforms 包起来 */
 export type GroupPrim = {
     /** 类型判别符 */

package/dist/es/primitive/group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../../src/primitive/group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,2CAA2C;AAC3C,MAAM,MAAM,SAAS,GAAG;IACtB,YAAY;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9B,YAAY;IACZ,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;CACjC,CAAC"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../../src/primitive/group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,iDAAiD;AACjD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY;IACZ,IAAI,EAAE,WAAW,CAAC;IAClB,aAAa;IACb,CAAC,EAAE,MAAM,CAAC;IACV,wBAAwB;IACxB,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAEF,uDAAuD;AACvD,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY;IACZ,IAAI,EAAE,QAAQ,CAAC;IACf,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG;IAC3B,YAAY;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,cAAc;IACd,CAAC,EAAE,MAAM,CAAC;IACV,2BAA2B;IAC3B,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB,kBAAkB,GAClB,eAAe,GACf,cAAc,CAAC;AAEnB,2CAA2C;AAC3C,MAAM,MAAM,SAAS,GAAG;IACtB,YAAY;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9B,YAAY;IACZ,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;CACjC,CAAC"}

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

@@ -1,42 +1,82 @@
 import { ArrowShape } from '../ir/path/arrow';
-/**
- * Path 命令：结构化路径绘制操作
- * @description discriminated union 按 kind 分发；坐标 / 角度均使用 user units（角度=度，0=+x、90=+y/视觉下、CW=正）。各 adapter 自行翻译为原生 API：SVG 拼 `d` 字符串、Canvas 调 ctx.moveTo/lineTo/arc 等
- */
-export type PathCommand = {
+/** Move command：移动游标到目标点，不绘制 */
+export type MovePathCommand = {
+    /** 鉴别字面量 */
     kind: 'move';
+    /** 目标点 [x, y] */
     to: [number, number];
-} | {
+};
+/** Line command：从游标到目标点画直线 */
+export type LinePathCommand = {
+    /** 鉴别字面量 */
     kind: 'line';
+    /** 终点 [x, y] */
     to: [number, number];
-} | {
+};
+/** Quad command：二次贝塞尔，一个控制点 */
+export type QuadPathCommand = {
+    /** 鉴别字面量 */
     kind: 'quad';
+    /** 控制点 [x, y] */
     control: [number, number];
+    /** 终点 [x, y] */
     to: [number, number];
-} | {
+};
+/** Cubic command：三次贝塞尔，两个控制点 */
+export type CubicPathCommand = {
+    /** 鉴别字面量 */
     kind: 'cubic';
+    /** 第一控制点 [x, y]（影响起点切线） */
     control1: [number, number];
+    /** 第二控制点 [x, y]（影响终点切线） */
     control2: [number, number];
+    /** 终点 [x, y] */
     to: [number, number];
-} | {
+};
+/** Arc command：以 center 为圆心、给定半径与起末角度的圆弧（center-parameterization） */
+export type ArcPathCommand = {
+    /** 鉴别字面量 */
     kind: 'arc';
+    /** 圆心 [x, y] */
     center: [number, number];
+    /** 半径（user units） */
     radius: number;
+    /** 起始角度（度，0° = +x、90° = +y screen-down） */
     startAngle: number;
+    /** 终止角度（度） */
     endAngle: number;
+    /** 是否逆时针扫描；缺省 / `false` = CW（屏幕坐标系正向） */
     counterClockwise?: boolean;
-} | {
+};
+/** EllipseArc command：以 center 为圆心、给定 x/y 半径与起末角度的椭圆弧；可选 rotation */
+export type EllipseArcPathCommand = {
+    /** 鉴别字面量 */
     kind: 'ellipseArc';
+    /** 圆心 [x, y] */
     center: [number, number];
+    /** x 轴半径 */
     radiusX: number;
+    /** y 轴半径 */
     radiusY: number;
+    /** 椭圆整体旋转角度（度），缺省 0 */
     rotation?: number;
+    /** 起始角度（度） */
     startAngle: number;
+    /** 终止角度（度） */
     endAngle: number;
+    /** 是否逆时针扫描；缺省 / `false` = CW */
     counterClockwise?: boolean;
-} | {
+};
+/** Close command：闭合当前子路径回最近一次 move 起点 */
+export type ClosePathCommand = {
+    /** 鉴别字面量；无其他字段 */
     kind: 'close';
 };
+/**
+ * Path 命令：结构化路径绘制操作（7 分支 discriminated union）
+ * @description discriminated union 按 kind 分发；坐标 / 角度均使用 user units（角度=度，0=+x、90=+y/视觉下、CW=正）。各 adapter 自行翻译为原生 API：SVG 拼 `d` 字符串、Canvas 调 ctx.moveTo/lineTo/arc 等。每个 kind 有对应 named type export，便于 wrapper / `Pick<>` 派生。
+ */
+export type PathCommand = MovePathCommand | LinePathCommand | QuadPathCommand | CubicPathCommand | ArcPathCommand | EllipseArcPathCommand | ClosePathCommand;
 /**
  * 端点级解析后的箭头视觉规格（Scene primitive 层）
  * @description compile/path.ts 把 IR `arrowDetail` 顶层 + start/end merge 后产出此结构。`shape` 必填、其余视觉字段全 optional：缺省字段交给 renderer 走 context-stroke / 硬编码 fallback，保持向后兼容

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

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/primitive/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACjE;IACE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtB,GACD;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GACD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU;IACV,KAAK,EAAE,UAAU,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC7B,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,UAAU;IACV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,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,+BAA+B;IAC/B,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/primitive/path.ts"],"names":[],"mappings":"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"}

package/dist/es/primitive/rect.d.ts

@@ -16,11 +16,11 @@ export type RectPrim = {
     fillOpacity?: number;
     /** 描边色 */
     stroke?: string;
-    /** 描边透明度 0~1（SVG stroke-opacity） */
+    /** 描边透明度 0~1 */
     strokeOpacity?: number;
     /** 描边宽度 */
     strokeWidth?: number;
-    /** SVG stroke-dasharray 模式 */
+    /** 描边 dash 模式（如 '4 2'，与 SVG/CSS `stroke-dasharray` 同格式） */
     strokeDasharray?: string;
     /** 圆角半径（同时作用于 rx/ry） */
     cornerRadius?: number;

package/dist/es/primitive/rect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rect.d.ts","sourceRoot":"","sources":["../../../src/primitive/rect.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,aAAa;IACb,CAAC,EAAE,MAAM,CAAC;IACV,aAAa;IACb,CAAC,EAAE,MAAM,CAAC;IACV,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU;IACV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"rect.d.ts","sourceRoot":"","sources":["../../../src/primitive/rect.ts"],"names":[],"mappings":"AAAA,WAAW;AACX,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,aAAa;IACb,CAAC,EAAE,MAAM,CAAC;IACV,aAAa;IACb,CAAC,EAAE,MAAM,CAAC;IACV,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU;IACV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}

package/dist/es/primitive/text.d.ts

@@ -1,16 +1,23 @@
-/** 行级字段（`<tspan>` 可独立指定），未填走块级 TextPrim 默认 */
+/** 行级字段（每行可独立指定），未填走块级 TextPrim 默认 */
 export type TextLine = {
+    /** 行文字内容 */
     text: string;
+    /** 行级字号 override（user units）；缺省走块级 TextPrim.fontSize */
     fontSize?: number;
+    /** 行级字体族 override（CSS font-family）；缺省走块级 */
     fontFamily?: string;
+    /** 行级字重 override（CSS font-weight）；缺省走块级 */
     fontWeight?: string | number;
+    /** 行级字形 override；缺省走块级 */
     fontStyle?: 'normal' | 'italic' | 'oblique';
+    /** 行级文字颜色 override；缺省走块级 TextPrim.fill */
     fill?: string;
+    /** 行级透明度 0..1 override；缺省走块级 */
     opacity?: number;
 };
 /**
  * 文本原语（measuredWidth/Height 由 Scene 编译阶段算好）
- * @description 多行 lines 至少 1 行；renderer 每行画 `<tspan>`，按 lineHeight 堆叠，按 baseline 在 (x,y) 锚点上下对齐。顶层属性是块级默认，单行 TextLine 可覆盖
+ * @description 多行 lines 至少 1 行；renderer 按 lineHeight 堆叠每行、按 baseline 在 (x,y) 锚点上下对齐。顶层属性是块级默认，单行 TextLine 可覆盖
  */
 export type TextPrim = {
     type: 'text';
@@ -26,7 +33,7 @@ export type TextPrim = {
     fontStyle?: 'normal' | 'italic' | 'oblique';
     align: 'start' | 'middle' | 'end';
     baseline: 'top' | 'middle' | 'bottom' | 'alphabetic';
-    /** 行高，多行下相邻 `<tspan>` 垂直距离 */
+    /** 行高，多行下相邻行的垂直距离 */
     lineHeight: number;
     /** 编译期算好的整块文字宽度 = max line width */
     measuredWidth: number;

package/dist/es/primitive/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/primitive/text.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,0CAA0C;IAC1C,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;IACrD,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../../src/primitive/text.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,0BAA0B;IAC1B,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,0CAA0C;IAC1C,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAClC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;IACrD,qBAAqB;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}

package/dist/es/primitive/view-box.d.ts

@@ -1,4 +1,4 @@
-/** SVG viewBox 数值四元组 */
+/** viewBox 数值四元组 `[x, y, w, h]`（与 SVG `viewBox` 同语义） */
 export type ViewBox = {
     /** 视口左上角横坐标 */
     x: number;

package/dist/es/primitive/view-box.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-box.d.ts","sourceRoot":"","sources":["../../../src/primitive/view-box.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,MAAM,MAAM,OAAO,GAAG;IACpB,eAAe;IACf,CAAC,EAAE,MAAM,CAAC;IACV,eAAe;IACf,CAAC,EAAE,MAAM,CAAC;IACV,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC"}
+{"version":3,"file":"view-box.d.ts","sourceRoot":"","sources":["../../../src/primitive/view-box.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,MAAM,OAAO,GAAG;IACpB,eAAe;IACf,CAAC,EAAE,MAAM,CAAC;IACV,eAAe;IACf,CAAC,EAAE,MAAM,CAAC;IACV,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/dist/es/types.d.ts

@@ -1,3 +1,11 @@
 /** 获取对象所有值的联合类型，等价于 (typeof T)[keyof typeof T] */
 export type ValueOf<T extends object> = T[keyof T];
+/**
+ * 类型层等价检查工具（internal idiom，公开 API 不导出）
+ * @description 当 A、B 完全等价时类型为 `true`，否则为 `false`——配合 `as const satisfies` 实现"字段表必须完备覆盖类型 key 集合"的互锁；漏字段或多字段 TS 编译期报错
+ * @example
+ *   const NODE_FIELDS = ['id', 'shape'] as const satisfies ReadonlyArray<keyof IRNode>;
+ *   type _Check = AssertEqual<typeof NODE_FIELDS[number], keyof IRNode>;
+ */
+export type AssertEqual<TActual, TExpected> = [TActual] extends [TExpected] ? [TExpected] extends [TActual] ? true : false : false;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +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"}
+{"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;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,EAAE,SAAS,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,GACvE,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,GAC3B,IAAI,GACJ,KAAK,GACP,KAAK,CAAC"}

package/dist/lib/compile/compile.cjs

@@ -2,7 +2,7 @@ const require_rect = require("../geometry/rect.cjs");
 const require_position = require("./position.cjs");
 const require_node = require("./node.cjs");
 const require_text_metrics = require("./text-metrics.cjs");
-const require_path = require("./path.cjs");
+const require_index = require("./path/index.cjs");
 const require_precision = require("./precision.cjs");
 const require_view_box = require("./view-box.cjs");
 //#region src/compile/compile.ts
@@ -29,6 +29,14 @@ var coordinateAsLayout = (id, center) => ({
 	fontSize: 0
 });
 /**
+* 默认 warn dispatcher：dev 模式 console.warn、生产静默
+* @description 用户传 onWarn 时使用用户的；不传走此 fallback
+*/
+var defaultWarnDispatcher = (warning) => {
+	if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+	console.warn(`[retikz] ${warning.code} at ${warning.path}: ${warning.message}`);
+};
+/**
 * IR → Scene 纯函数转换，所有 adapter 共享
 * @description Pass 1 处理 Node/coordinate 并注册 nodeIndex、发 primitive、累积 bbox；Pass 2 解析 Path 端点写 d 字符串；末端按 precision 折算 viewBox
 */
@@ -37,24 +45,41 @@ var compileToScene = (ir, options = {}) => {
 	const viewBoxPadding = options.padding ?? 10;
 	const round = require_precision.makeRound(options.precision ?? 2);
 	const nodeDistance = options.nodeDistance;
+	const onWarn = options.onWarn ?? defaultWarnDispatcher;
 	const primitives = [];
 	const nodeIndex = /* @__PURE__ */ new Map();
 	const allPoints = [];
-	for (const child of ir.children) if (child.type === "node") {
-		const layout = require_node.layoutNode(child, measureText, nodeIndex, nodeDistance);
-		if (child.id) nodeIndex.set(child.id, layout);
-		for (const prim of require_node.emitNodePrimitives(layout, round)) primitives.push(prim);
-		allPoints.push(require_rect.rect.anchor(layout.rect, "north-west"), require_rect.rect.anchor(layout.rect, "north-east"), require_rect.rect.anchor(layout.rect, "south-west"), require_rect.rect.anchor(layout.rect, "south-east"));
-	} else if (child.type === "coordinate") {
-		const center = require_position.resolvePosition(child.position, nodeIndex, nodeDistance);
-		if (!center) throw new Error(`Cannot resolve position for coordinate ${child.id}; polar.origin or at.of may reference an undefined node`);
-		nodeIndex.set(child.id, coordinateAsLayout(child.id, center));
+	for (let i = 0; i < ir.children.length; i++) {
+		const child = ir.children[i];
+		if (child.type === "node") {
+			const layout = require_node.layoutNode(child, measureText, nodeIndex, nodeDistance);
+			if (child.id) nodeIndex.set(child.id, layout);
+			for (const prim of require_node.emitNodePrimitives(layout, round)) primitives.push(prim);
+			allPoints.push(require_rect.rect.anchor(layout.rect, "north-west"), require_rect.rect.anchor(layout.rect, "north-east"), require_rect.rect.anchor(layout.rect, "south-west"), require_rect.rect.anchor(layout.rect, "south-east"));
+		} else if (child.type === "coordinate") {
+			const center = require_position.resolvePosition(child.position, nodeIndex, nodeDistance);
+			if (!center) {
+				onWarn({
+					code: "POLAR_ORIGIN_UNRESOLVED",
+					message: `Cannot resolve position for coordinate '${child.id}'; polar.origin or at.of may reference an undefined node`,
+					path: `children[${i}].coordinate.position`
+				});
+				throw new Error(`Cannot resolve position for coordinate ${child.id}; polar.origin or at.of may reference an undefined node`);
+			}
+			nodeIndex.set(child.id, coordinateAsLayout(child.id, center));
+		}
 	}
-	for (const child of ir.children) if (child.type === "path") {
-		const result = require_path.emitPathPrimitive(child, nodeIndex, round, measureText);
-		if (result) {
-			for (const prim of result.primitives) primitives.push(prim);
-			for (const p of result.points) allPoints.push(p);
+	for (let i = 0; i < ir.children.length; i++) {
+		const child = ir.children[i];
+		if (child.type === "path") {
+			const result = require_index.emitPathPrimitive(child, nodeIndex, round, measureText, {
+				onWarn,
+				irPath: `children[${i}].path`
+			});
+			if (result) {
+				for (const prim of result.primitives) primitives.push(prim);
+				for (const p of result.points) allPoints.push(p);
+			}
 		}
 	}
 	return {

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

@@ -1,6 +1,18 @@
 import { IR } from '../ir';
 import { Scene } from '../primitive';
 import { TextMeasurer } from './text-metrics';
+/** 编译期警告：path / position 解析失败时通过 `CompileOptions.onWarn` 发出，不影响编译产物 */
+export type CompileWarning = {
+    /**
+     * 警告类型代码（机器可读）
+     * @description 用户可按 code 分支处理；未来 alpha 加新 code 不破坏调用方
+     */
+    code: 'UNRESOLVED_NODE_REFERENCE' | 'PATH_TOO_SHORT' | 'ANCHOR_RESOLUTION_FAILED' | 'OFFSET_BASE_UNRESOLVED' | 'POLAR_ORIGIN_UNRESOLVED' | 'AT_TARGET_UNRESOLVED' | 'RELATIVE_INITIAL_NO_PREV_END' | 'BBOX_EXTREME_INPUT' | (string & {});
+    /** 人类可读消息（英文） */
+    message: string;
+    /** IR locator 路径（jq-like，如 `'children[3].path.children[1].to'`） */
+    path: string;
+};
 /** compileToScene 的可选参数 */
 export type CompileOptions = {
     /** 注入文字度量函数；不传则用 fallback（不准但可跑） */
@@ -17,6 +29,11 @@ export type CompileOptions = {
      * @description `Node.position` 为 `{ direction, of }` 且未自带 `distance` 时取此值；未配回退到 1
      */
     nodeDistance?: number;
+    /**
+     * 编译期警告收集器
+     * @description path / position 解析失败时按 IR locator + code + message 同步触发；不传时 dev 模式（`process.env.NODE_ENV !== 'production'`）默认 `console.warn`、生产静默
+     */
+    onWarn?: (warning: CompileWarning) => void;
 };
 /**
  * IR → Scene 纯函数转换，所有 adapter 共享

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

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAkB,MAAM,cAAc,CAAC;AAK1D,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAuBrE,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAsDrE,CAAC"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAkB,MAAM,cAAc,CAAC;AAK1D,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AAuBrE,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,IAAI,EACA,2BAA2B,GAC3B,gBAAgB,GAChB,0BAA0B,GAC1B,wBAAwB,GACxB,yBAAyB,GACzB,sBAAsB,GACtB,8BAA8B,GAC9B,oBAAoB,GACpB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAClB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG;IAC3B,oCAAoC;IACpC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;CAC5C,CAAC;AAWF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAkErE,CAAC"}

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

@@ -1,7 +1,7 @@
 export * from './compile';
 export * from './node';
 export * from './parseTarget';
-export * from './path';
+export * from './path/index';
 export * from './position';
 export * from './precision';
 export * from './text-metrics';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/compile/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/compile/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/lib/compile/node.cjs

@@ -21,7 +21,7 @@ var resolveDashArray = (dashArray, dashed, dotted) => {
 	if (dashed) return DASHED_PATTERN;
 	if (dotted) return DOTTED_PATTERN;
 };
-/** IR align → SVG textAnchor */
+/** IR align → 文字对齐锚点（start / middle / end） */
 var alignToTextAnchor = (a) => a === "left" ? "start" : a === "right" ? "end" : "middle";
 /** 从 layout 构造 Rect（带 margin 扩张） */
 var rectOf = (layout, marginAdd) => ({

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

@@ -13,7 +13,7 @@ export type NodeLayout = {
      * @description rectangle: rect 本身；circle: width=height=2×radius；ellipse: 2×rx,2×ry；diamond: 2×halfA,2×halfB。x,y 是几何中心，rotate 弧度
      */
     rect: Rect;
-    /** IR 原始旋转角（度数），供 emit 写 SVG transform */
+    /** IR 原始旋转角（度数），供 emit 阶段写入 GroupPrim 的 rotate transform */
     rotateDeg: number;
     /** 外边距（≥ 0），path 附着到外扩 margin 的虚拟边界 */
     margin: number;
@@ -26,7 +26,7 @@ export type NodeLayout = {
     textWidth: number;
     /** 文本块高度 ≈ lines × lineHeight */
     textHeight: number;
-    /** 文本对齐（已映射到 SVG textAnchor 三态） */
+    /** 文本对齐（start / middle / end 三态） */
     align: 'start' | 'middle' | 'end';
     /** 行高（已应用默认值） */
     lineHeight: number;
@@ -48,7 +48,7 @@ export type NodeLayout = {
     strokeOpacity?: number;
     /** 边框宽度，emit 时 1 兜底 */
     strokeWidth?: number;
-    /** SVG stroke-dasharray，已把 dashed/dotted 预设解析为具体 pattern */
+    /** 描边 dash 模式（与 SVG/CSS `stroke-dasharray` 同格式），已把 dashed/dotted 预设解析为具体 pattern */
     strokeDasharray?: string;
     /** rectangle 圆角半径（非 rect shape 无效） */
     roundedCorners?: number;

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

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