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

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';
@@ -17,7 +17,7 @@ export type EllipsePrim = {
     /** 描边透明度 0~1 */
     strokeOpacity?: number;
     strokeWidth?: number;
-    strokeDasharray?: string;
+    dashPattern?: Array<number>;
     /** 整体透明度 0~1 */
     opacity?: number;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"ellipse.d.ts","sourceRoot":"","sources":["../../../src/primitive/ellipse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,cAAc;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"ellipse.d.ts","sourceRoot":"","sources":["../../../src/primitive/ellipse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,cAAc;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}

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/index.d.ts

@@ -3,6 +3,6 @@ export * from './ellipse';
 export * from './text';
 export * from './path';
 export * from './group';
-export * from './view-box';
+export * from './layout';
 export * from './scene';
 //# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1,12 @@
+/** 场景整体布局边界 */
+export type Layout = {
+    /** 布局边界左上角横坐标 */
+    x: number;
+    /** 布局边界左上角纵坐标 */
+    y: number;
+    /** 布局边界宽度 */
+    width: number;
+    /** 布局边界高度 */
+    height: number;
+};
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/primitive/layout.ts"],"names":[],"mappings":"AAAA,eAAe;AACf,MAAM,MAAM,MAAM,GAAG;IACnB,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAC;IACV,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAC;IACV,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,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，保持向后兼容
@@ -69,16 +109,16 @@ export type PathPrim = {
     fill?: string;
     /** 填充透明度 0~1 */
     fillOpacity?: number;
-    /** SVG fill-rule：`nonzero`（默认）/ `evenodd`（环形 / 孔洞场景） */
+    /** 填充规则：`nonzero`（默认）/ `evenodd`（环形 / 孔洞场景） */
     fillRule?: 'nonzero' | 'evenodd';
     /** 描边色 */
     stroke?: string;
-    /** 描边透明度 0~1（SVG stroke-opacity） */
+    /** 描边透明度 0~1 */
     strokeOpacity?: number;
     /** 描边宽度 */
     strokeWidth?: number;
-    /** SVG stroke-dasharray 模式 */
-    strokeDasharray?: string;
+    /** 描边 dash pattern */
+    dashPattern?: Array<number>;
     /** 端点形状 */
     strokeLinecap?: 'butt' | 'round' | 'square';
     /** 拐点形状 */

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

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/primitive/path.ts"],"names":[],"mappings":"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"}
+{"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,12 +16,12 @@ export type RectPrim = {
     fillOpacity?: number;
     /** 描边色 */
     stroke?: string;
-    /** 描边透明度 0~1（SVG stroke-opacity） */
+    /** 描边透明度 0~1 */
     strokeOpacity?: number;
     /** 描边宽度 */
     strokeWidth?: number;
-    /** SVG stroke-dasharray 模式 */
-    strokeDasharray?: string;
+    /** 描边 dash pattern（如 [4, 2]） */
+    dashPattern?: Array<number>;
     /** 圆角半径（同时作用于 rx/ry） */
     cornerRadius?: number;
     /** 整体透明度 0~1 */

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,gCAAgC;IAChC,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,wBAAwB;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}

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

@@ -3,17 +3,17 @@ import { GroupPrim } from './group';
 import { PathPrim } from './path';
 import { RectPrim } from './rect';
 import { TextPrim } from './text';
-import { ViewBox } from './view-box';
+import { Layout } from './layout';
 /**
  * Scene primitive：渲染目标无关的最大公约子集
  * @description 所有 adapter（SVG/Canvas/PDF/Skia）都应能消费；不允许出现 SVG-only 或 Canvas-only 特性（filter/marker/imageData）
  */
 export type ScenePrimitive = RectPrim | EllipsePrim | TextPrim | PathPrim | GroupPrim;
-/** 场景：渲染目标无关的"已布局好的图元集合 + viewBox" */
+/** 场景：渲染目标无关的"已布局好的图元集合 + layout" */
 export type Scene = {
     /** 已布局好的图元数组，按渲染顺序排列 */
     primitives: Array<ScenePrimitive>;
-    /** 整个场景的视口范围 */
-    viewBox: ViewBox;
+    /** 整个场景的布局边界 */
+    layout: Layout;
 };
 //# sourceMappingURL=scene.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/primitive/scene.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtF,sCAAsC;AACtC,MAAM,MAAM,KAAK,GAAG;IAClB,wBAAwB;IACxB,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAClC,gBAAgB;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC"}
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../../src/primitive/scene.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtF,qCAAqC;AACrC,MAAM,MAAM,KAAK,GAAG;IAClB,wBAAwB;IACxB,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAClC,gBAAgB;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,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/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,9 +2,9 @@ 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");
+const require_layout = require("./layout.cjs");
 //#region src/compile/compile.ts
 /**
 * 把 coordinate 注册成 0×0 NodeLayout
@@ -29,37 +29,62 @@ 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
+* @description Pass 1 处理 Node/coordinate 并注册 nodeIndex、发 primitive、累积 bbox；Pass 2 解析 Path 端点写 d 字符串；末端按 precision 折算 layout
 */
 var compileToScene = (ir, options = {}) => {
 	const measureText = options.measureText ?? require_text_metrics.fallbackMeasurer;
-	const viewBoxPadding = options.padding ?? 10;
+	const layoutPadding = 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 {
 		primitives,
-		viewBox: require_view_box.computeViewBox(allPoints, viewBoxPadding, round)
+		layout: require_layout.computeLayout(allPoints, layoutPadding, round)
 	};
 };
 //#endregion