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

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

@@ -1,4 +1,5 @@
-import { ArrowShape } from '../ir/path/arrow';
+import { ArrowShapeName } from '../ir/path/arrow';
+import { MarkerPrimitive } from './marker';
 import { PaintValue } from './paint';
 /** Move command：移动游标到目标点，不绘制 */
 export type MovePathCommand = {
@@ -79,26 +80,29 @@ export type ClosePathCommand = {
  */
 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，保持向后兼容
+ * 端点级已解析的箭头 marker 描述（Scene primitive 层，renderer-agnostic）
+ * @description compile 把 IR `arrowDetail` 顶层 + start/end merge、查 effective arrow 表、调 `def.emit`
+ *   产几何，所有视觉输入（scale / length / width / color / fill / lineWidth）在 compile 解析阶段被消费、
+ *   **不**出现在本结构里。最终挂在 `PathPrim.arrowStart` / `arrowEnd` 上的是"已解析 marker 描述"：内部几何
+ *   `marker`（`MarkerPrimitive[]`，局部 baseSize 坐标系）+ wrapper 参数（`baseSize` / `refX` / `markerWidth` /
+ *   `markerHeight` / `opacity`）。adapter 只**物化**——把 `marker` 嵌进 `<marker viewBox refX refY markerWidth
+ *   markerHeight>`，不再 switch、不调 emit、不需要 arrows 注册表。纯 JSON 数据（无函数）。
  */
 export type ArrowEndSpec = {
-    /** 形状名 */
-    shape: ArrowShape;
-    /** 等比缩放因子（乘到 length/width 上）；缺省 1 */
-    scale?: number;
-    /** 尖长（user units）；缺省让 renderer 走默认 6 */
-    length?: number;
-    /** 尖宽（user units）；缺省让 renderer 走默认 6 */
-    width?: number;
-    /** 描边颜色 override；缺省走 context-stroke（继承 path stroke） */
-    color?: string;
-    /** 填充色 override（仅实心 shape 生效；空心 shape 已在 compile 阶段被丢） */
-    fill?: string;
-    /** 箭头不透明度 0..1；缺省继承 path opacity */
+    /** 形状名：内置 7 或经 `CompileOptions.arrows` 注册的扩展名；标识 / 调试用，已解析后渲染不依赖（保留） */
+    shape: ArrowShapeName;
+    /** marker viewBox 边长（`def.baseSize ?? 10`）；adapter 据此推 viewBox `0 0 baseSize baseSize` 与 refY = baseSize/2 */
+    baseSize: number;
+    /** 线接触点（marker refX）；hollow 已在 compile 解析阶段减 lineWidth/2（adapter 不再算） */
+    refX: number;
+    /** 已解析尖长 = `(length ?? def.defaultLength) * scale`（adapter 直接当 markerWidth 用） */
+    markerWidth: number;
+    /** 已解析尖宽 = `(width ?? def.defaultWidth) * scale`（adapter 直接当 markerHeight 用） */
+    markerHeight: number;
+    /** marker 元素级不透明度 0..1；缺省继承 path opacity */
     opacity?: number;
-    /** 空心 shape 描边粗细（user units）；缺省 1.5。实心 shape 忽略 */
-    lineWidth?: number;
+    /** `def.emit` 产物：局部 baseSize 坐标系下的内部几何（fill 限 `string | { kind:'contextStroke' }`） */
+    marker: Array<MarkerPrimitive>;
 };
 /** 路径原语：结构化 commands 数组；adapter 在 render 时翻译为各自原生 API */
 export type PathPrim = {

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

@@ -5,7 +5,8 @@ import { RectPrim } from './rect';
 import { TextPrim } from './text';
 import { Layout } from './layout';
 import { SceneResource } from './paint';
-export type { PaintValue, SceneResource } from './paint';
+export type { PaintValue, SceneResource, PaintResource, ResolvedPatternTile } from './paint';
+export type { ClipShape, ClipResource } from './clip';
 /**
  * Scene primitive：渲染目标无关的最大公约子集
  * @description 所有 adapter（SVG/Canvas/PDF/Skia）都应能消费；不允许出现 SVG-only 或 Canvas-only 特性（filter/marker/imageData）

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,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEzD;;;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;IACf,gEAAgE;IAChE,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CAClC,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;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC7F,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtD;;;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;IACf,gEAAgE;IAChE,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CAClC,CAAC"}

package/dist/lib/arrows/index.cjs

@@ -0,0 +1,118 @@
+//#region src/arrows/index.ts
+/** 实心闭合三角 / 菱形 / V 形的 path 工厂：填充走 ctx.fill（无 override = contextStroke） */
+var filledPath = (ctx, points) => ({
+	type: "path",
+	commands: [
+		{
+			kind: "move",
+			to: points[0]
+		},
+		...points.slice(1).map((p) => ({
+			kind: "line",
+			to: p
+		})),
+		{ kind: "close" }
+	],
+	fill: typeof ctx.fill === "string" ? ctx.fill : { kind: "contextStroke" }
+});
+/** 空心闭合 path 工厂：无 fill、描边走 ctx.stroke / ctx.lineWidth（contextStroke 由 adapter 映射） */
+var hollowPath = (ctx, points, strokeLinejoin) => ({
+	type: "path",
+	commands: [
+		{
+			kind: "move",
+			to: points[0]
+		},
+		...points.slice(1).map((p) => ({
+			kind: "line",
+			to: p
+		})),
+		{ kind: "close" }
+	],
+	stroke: typeof ctx.stroke === "string" ? ctx.stroke : "context-stroke",
+	strokeWidth: ctx.lineWidth,
+	...strokeLinejoin ? { strokeLinejoin } : {}
+});
+/**
+* 内置 7 arrow 注册项；与 `CompileOptions.arrows` 合并时被同名注入覆盖
+* @description 几何字段（lineContactX 静态 base / tipX / hollow）：
+*   实心 normal/diamond/circle lineContactX=0；stealth=3；open/openDiamond base=1 + tipX=9 + hollow；
+*   openCircle base=0.75 + hollow。baseSize / defaultLength / defaultWidth 走类型缺省（10 / 6 / 6）。
+*   framework 对 hollow def 统一把 lineContactX 减 lineWidth/2 得实际 refX / shrink 接触点。
+*   emit 几何在局部 baseSize=10 坐标系，等价历史 SVG。
+*/
+var BUILTIN_ARROWS = {
+	normal: {
+		lineContactX: 0,
+		emit: (ctx) => [filledPath(ctx, [
+			[0, 0],
+			[10, 5],
+			[0, 10]
+		])]
+	},
+	open: {
+		hollow: true,
+		lineContactX: 1,
+		tipX: 9,
+		emit: (ctx) => [hollowPath(ctx, [
+			[1, 1],
+			[9, 5],
+			[1, 9]
+		])]
+	},
+	stealth: {
+		lineContactX: 3,
+		emit: (ctx) => [filledPath(ctx, [
+			[0, 0],
+			[10, 5],
+			[0, 10],
+			[3, 5]
+		])]
+	},
+	diamond: {
+		lineContactX: 0,
+		emit: (ctx) => [filledPath(ctx, [
+			[0, 5],
+			[5, 0],
+			[10, 5],
+			[5, 10]
+		])]
+	},
+	openDiamond: {
+		hollow: true,
+		lineContactX: 1,
+		tipX: 9,
+		emit: (ctx) => [hollowPath(ctx, [
+			[1, 5],
+			[5, 1],
+			[9, 5],
+			[5, 9]
+		], "round")]
+	},
+	circle: {
+		lineContactX: 0,
+		emit: (ctx) => [{
+			type: "ellipse",
+			cx: 5,
+			cy: 5,
+			rx: 5,
+			ry: 5,
+			fill: typeof ctx.fill === "string" ? ctx.fill : { kind: "contextStroke" }
+		}]
+	},
+	openCircle: {
+		hollow: true,
+		lineContactX: .75,
+		emit: (ctx) => [{
+			type: "ellipse",
+			cx: 5,
+			cy: 5,
+			rx: 4.25,
+			ry: 4.25,
+			stroke: typeof ctx.stroke === "string" ? ctx.stroke : "context-stroke",
+			strokeWidth: ctx.lineWidth
+		}]
+	}
+};
+//#endregion
+exports.BUILTIN_ARROWS = BUILTIN_ARROWS;

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

@@ -0,0 +1,13 @@
+import { BuiltinArrowName } from '../ir/path/arrow';
+import { ArrowDefinition } from './types';
+/**
+ * 内置 7 arrow 注册项；与 `CompileOptions.arrows` 合并时被同名注入覆盖
+ * @description 几何字段（lineContactX 静态 base / tipX / hollow）：
+ *   实心 normal/diamond/circle lineContactX=0；stealth=3；open/openDiamond base=1 + tipX=9 + hollow；
+ *   openCircle base=0.75 + hollow。baseSize / defaultLength / defaultWidth 走类型缺省（10 / 6 / 6）。
+ *   framework 对 hollow def 统一把 lineContactX 减 lineWidth/2 得实际 refX / shrink 接触点。
+ *   emit 几何在局部 baseSize=10 坐标系，等价历史 SVG。
+ */
+export declare const BUILTIN_ARROWS: Record<BuiltinArrowName, ArrowDefinition>;
+export type { ArrowDefinition, ArrowEmitContext } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/arrows/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAiCjE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,gBAAgB,EAAE,eAAe,CAqDpE,CAAC;AAEF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/lib/arrows/types.d.ts

@@ -0,0 +1,43 @@
+import { MarkerFill, MarkerPrimitive } from '../primitive/marker';
+/**
+ * emit 拿到的运行时上下文
+ * @description framework 把宿主 path 已解析的颜色 / 描边粗细传进来；def 据此产 marker 几何。
+ *   `stroke` / `fill` 是 `MarkerFill`（纯色串或 `{ kind: 'contextStroke' }`，无 override 时取 contextStroke
+ *   继承 path stroke、主题反应不冻结）——可直接当 marker primitive 的 `fill` / `stroke` 用，无需收窄。
+ */
+export type ArrowEmitContext = {
+    /** 描边颜色（无 override 时 = `{ kind: 'contextStroke' }`，继承 path stroke） */
+    stroke: MarkerFill;
+    /** 填充颜色（实心箭头主导色；空心箭头由 framework 据 `hollow` 处理后传入） */
+    fill: MarkerFill;
+    /** 描边粗细（marker 局部坐标，user units）；空心箭头据此画外轮廓 */
+    lineWidth: number;
+    /** 精度取整函数（与 compile/render 同一 round，保几何一致） */
+    round: (n: number) => number;
+};
+/**
+ * 一个 arrow 的可注册定义：几何尺寸 + emit
+ * @description plain object（factory 友好），含函数、**不进 IR**，走 `CompileOptions.arrows` 运行时注入。
+ *   内置 7 箭头也是注册项（无内置特权，对齐 `ShapeDefinition` / `BUILTIN_SHAPES`）。
+ *
+ *   `lineContactX` 存**静态 base**（不含 lineWidth 调整）：实心 normal/diamond/circle = 0、stealth = 3、
+ *   open/openDiamond base = 1、openCircle base = 0.75。framework 对 `hollow: true` 的 def 统一减
+ *   `lineWidth/2` 得到实际 refX / shrink 接触点（这条调整由编译器 / adapter 落，def 只声明静态 base）。
+ */
+export type ArrowDefinition = {
+    /** marker 局部基准边长（viewBox `0 0 baseSize baseSize`，refY = baseSize/2）；缺省 10 */
+    baseSize?: number;
+    /** 空心标志：true 时 framework 丢 fill、color 主导描边、启用 lineWidth；并对 lineContactX 减 lineWidth/2 */
+    hollow?: boolean;
+    /** 线接触点静态 base（决定 path shrink + marker refX）；空心 def 由 framework 再减 lineWidth/2 */
+    lineContactX: number;
+    /** 尖端 x（shrink 用）；缺省 = baseSize */
+    tipX?: number;
+    /** 默认箭头长度（length fallback）；缺省 6 */
+    defaultLength?: number;
+    /** 默认箭头宽度（width fallback）；缺省 6 */
+    defaultWidth?: number;
+    /** 局部坐标 marker 几何（renderer-agnostic）；adapter 把产物嵌进 `<marker>` */
+    emit: (ctx: ArrowEmitContext) => Iterable<MarkerPrimitive>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/arrows/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/arrows/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sEAAsE;IACtE,MAAM,EAAE,UAAU,CAAC;IACnB,qDAAqD;IACrD,IAAI,EAAE,UAAU,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,IAAI,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,QAAQ,CAAC,eAAe,CAAC,CAAC;CAC5D,CAAC"}

package/dist/lib/compile/clip.cjs

@@ -0,0 +1,84 @@
+//#region src/compile/clip.ts
+/**
+* 裁剪区 finite 守卫 + round
+* @description schema 的 `.finite().positive()` 只在 IR parse 守门；compileToScene 直接收手搓 / LLM IR 会绕过，
+*   故 compile 是唯一真实关口——非 finite / 非正尺寸会污染 Scene round-trip（JSON.stringify(NaN/Infinity)=null）。
+*   在此抛清晰错（含 kind），对齐 arrow / pattern 的 finite 守卫。坐标 / 尺寸按 Scene precision round。
+*/
+var guardAndRound = (clip, round) => {
+	const bad = (field, v) => {
+		throw new Error(`Clip '${clip.kind}' has an invalid ${field} (${String(v)}); it must be a finite number${field === "x" || field === "y" || field === "cx" || field === "cy" ? "" : " greater than 0"}.`);
+	};
+	const fin = (field, v) => {
+		if (!Number.isFinite(v)) bad(field, v);
+		return round(v);
+	};
+	const pos = (field, v) => {
+		if (!Number.isFinite(v) || v <= 0) bad(field, v);
+		return round(v);
+	};
+	switch (clip.kind) {
+		case "rect": return {
+			kind: "rect",
+			x: fin("x", clip.x),
+			y: fin("y", clip.y),
+			width: pos("width", clip.width),
+			height: pos("height", clip.height)
+		};
+		case "circle": return {
+			kind: "circle",
+			cx: fin("cx", clip.cx),
+			cy: fin("cy", clip.cy),
+			r: pos("r", clip.r)
+		};
+		case "ellipse": return {
+			kind: "ellipse",
+			cx: fin("cx", clip.cx),
+			cy: fin("cy", clip.cy),
+			rx: pos("rx", clip.rx),
+			ry: pos("ry", clip.ry)
+		};
+		case "polygon":
+			if (clip.points.length < 3) throw new Error(`Clip 'polygon' needs at least 3 points; got ${clip.points.length}.`);
+			return {
+				kind: "polygon",
+				points: clip.points.map(([px, py], i) => {
+					if (!Number.isFinite(px) || !Number.isFinite(py)) throw new Error(`Clip 'polygon' point[${i}] is not finite (${String(px)}, ${String(py)}).`);
+					return [round(px), round(py)];
+				})
+			};
+	}
+};
+/**
+* 建一个 clip 登记表
+* @description resolve 对结构相同裁剪区（JSON 深比较）合并为一个资源、派稳定 id（`clip-1` / `clip-2`…，首见序）。
+*   同一份 IR 编译两次 → 同 id（快照稳定）。裁剪区坐标 / 尺寸经 finite 守卫 + round。
+* @param round 精度取整（与 compile / render 同一 round，保几何一致）
+*/
+var createClipRegistry = (round) => {
+	const idByKey = /* @__PURE__ */ new Map();
+	const list = [];
+	let counter = 0;
+	const resolve = (clip) => {
+		const shape = guardAndRound(clip, round);
+		const key = JSON.stringify(shape);
+		let id = idByKey.get(key);
+		if (id === void 0) {
+			counter += 1;
+			id = `clip-${counter}`;
+			idByKey.set(key, id);
+			list.push({
+				kind: "clip",
+				id,
+				shape
+			});
+		}
+		return id;
+	};
+	return {
+		resolve,
+		resources: () => list
+	};
+};
+//#endregion
+exports.createClipRegistry = createClipRegistry;

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

@@ -0,0 +1,17 @@
+import { IRClipSpec } from '../ir';
+import { ClipResource } from '../primitive';
+/** clip 登记表：编译期收集裁剪区、去重派稳定 id（`clip-1`…），最后产出 Scene clip 资源 */
+export type ClipRegistry = {
+    /** 把一个裁剪区去重派 id；返回资源 id（供 GroupPrim.clipRef） */
+    resolve: (clip: IRClipSpec) => string;
+    /** 产出收集到的全部 clip 资源 */
+    resources: () => Array<ClipResource>;
+};
+/**
+ * 建一个 clip 登记表
+ * @description resolve 对结构相同裁剪区（JSON 深比较）合并为一个资源、派稳定 id（`clip-1` / `clip-2`…，首见序）。
+ *   同一份 IR 编译两次 → 同 id（快照稳定）。裁剪区坐标 / 尺寸经 finite 守卫 + round。
+ * @param round 精度取整（与 compile / render 同一 round，保几何一致）
+ */
+export declare const createClipRegistry: (round: (n: number) => number) => ClipRegistry;
+//# sourceMappingURL=clip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clip.d.ts","sourceRoot":"","sources":["../../../src/compile/clip.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,cAAc,CAAC;AAE5D,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG;IACzB,gDAAgD;IAChD,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC;IACtC,uBAAuB;IACvB,SAAS,EAAE,MAAM,KAAK,CAAC,YAAY,CAAC,CAAC;CACtC,CAAC;AA4DF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAAG,YAiBjE,CAAC"}

package/dist/lib/compile/compile.cjs

@@ -1,12 +1,16 @@
 const require_rect = require("../geometry/rect.cjs");
 const require_index = require("../shapes/index.cjs");
+const require_index$1 = require("../arrows/index.cjs");
+const require_index$2 = require("../patterns/index.cjs");
 const require_name_stack = require("./name-stack.cjs");
 const require_scope = require("./scope.cjs");
 const require_position = require("./position.cjs");
 const require_node = require("./node.cjs");
 const require_paint = require("./paint.cjs");
+const require_clip = require("./clip.cjs");
 const require_text_metrics = require("./text-metrics.cjs");
-const require_index$1 = require("./path/index.cjs");
+const require_anchor = require("./path/anchor.cjs");
+const require_index$3 = require("./path/index.cjs");
 const require_precision = require("./precision.cjs");
 const require_style = require("./style.cjs");
 const require_layout = require("./layout.cjs");
@@ -50,6 +54,28 @@ var scopePlaceholderLayout = (id, chain) => {
 	return zeroSizeRectAt(id, chain.length === 0 ? [0, 0] : require_scope.applyTransformChain([0, 0], chain));
 };
 /**
+* 显式 viewBox → Scene.layout（finite 守卫 + round）
+* @description schema 的 `.finite().positive()` 只在 IR parse 守门；compileToScene 直接收手搓 / LLM IR 会绕过，
+*   故此处是唯一真实关口——非 finite / 非正尺寸会污染 Scene round-trip。非法即抛清晰错（不泄漏进 Scene）；
+*   四字段按 Scene precision round（与自动算 layout 同口径）。
+*/
+var viewBoxToLayout = (vb, round) => {
+	if (!Number.isFinite(vb.x) || !Number.isFinite(vb.y)) throw new Error(`viewBox has a non-finite origin (x=${String(vb.x)}, y=${String(vb.y)}); both must be finite.`);
+	if (!Number.isFinite(vb.width) || vb.width <= 0) throw new Error(`viewBox has an invalid width (${String(vb.width)}); it must be a finite number greater than 0.`);
+	if (!Number.isFinite(vb.height) || vb.height <= 0) throw new Error(`viewBox has an invalid height (${String(vb.height)}); it must be a finite number greater than 0.`);
+	const x = round(vb.x);
+	const y = round(vb.y);
+	const width = round(vb.width);
+	const height = round(vb.height);
+	if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) throw new Error(`viewBox rounds to an invalid layout (x=${String(x)}, y=${String(y)}, width=${String(width)}, height=${String(height)}); check precision and coordinate magnitude.`);
+	return {
+		x,
+		y,
+		width,
+		height
+	};
+};
+/**
 * 默认 warn dispatcher：dev 模式 console.warn、生产静默
 * @description 用户传 onWarn 时使用用户的；不传走此 fallback
 */
@@ -110,6 +136,29 @@ var compileToScene = (ir, options = {}) => {
 			path: `options.shapes.${name}`
 		});
 	}
+	const effectivePathGenerators = options.pathGenerators ?? {};
+	const effectiveArrows = options.arrows ? {
+		...require_index$1.BUILTIN_ARROWS,
+		...options.arrows
+	} : require_index$1.BUILTIN_ARROWS;
+	if (options.arrows) {
+		for (const name of Object.keys(options.arrows)) if (Object.prototype.hasOwnProperty.call(require_index$1.BUILTIN_ARROWS, name)) onWarn({
+			code: "ARROW_OVERRIDES_BUILTIN",
+			message: `Injected arrow '${name}' overrides the built-in arrow of the same name.`,
+			path: `options.arrows.${name}`
+		});
+	}
+	const effectivePatterns = options.patterns ? {
+		...require_index$2.BUILTIN_PATTERNS,
+		...options.patterns
+	} : require_index$2.BUILTIN_PATTERNS;
+	if (options.patterns) {
+		for (const name of Object.keys(options.patterns)) if (Object.prototype.hasOwnProperty.call(require_index$2.BUILTIN_PATTERNS, name)) onWarn({
+			code: "PATTERN_OVERRIDES_BUILTIN",
+			message: `Injected pattern '${name}' overrides the built-in pattern of the same name.`,
+			path: `options.patterns.${name}`
+		});
+	}
 	const primitives = [];
 	/** 已 push 但未回填的占位计数；compileToScene 返回前必须归零（无条件守 Scene 公开契约） */
 	let placeholderBalance = 0;
@@ -134,7 +183,8 @@ var compileToScene = (ir, options = {}) => {
 	};
 	const nameStack = new require_name_stack.NameStack({ onDuplicate: (info) => onWarn(formatDuplicateWarning(info)) });
 	const allPoints = [];
-	const paint = require_paint.createPaintRegistry();
+	const paint = require_paint.createPaintRegistry(effectivePatterns, round);
+	const clip = require_clip.createClipRegistry(round);
 	/**
 	* 解析一批本层收集的 pending paths（lookup-only 阶段）
 	* @description 两种落点：有 `slot`（scopeChain 为空）→ 原位 splice 回填该 path 在本层 sink 占的位（按引用定位免索引漂移），保住与同层 node 的 IR 声明序；无 `slot`（scopeChain 非空）→ hoist 到顶层 `primitives`，因端点已是全局坐标、进 transformed GroupPrim 会被 scope.transform 二次 apply。NameStack 切到 pass2 守门：path 解析中误调 register 抛 internal error；解析完切回 pass1 让上层 scope 子树继续 register 子节点。
@@ -146,11 +196,13 @@ var compileToScene = (ir, options = {}) => {
 		nameStack.enterLookupPhase();
 		try {
 			for (const item of pending) {
-				const result = require_index$1.emitPathPrimitive(item.path, nameStack, round, measureText, {
+				const result = require_index$3.emitPathPrimitive(item.path, nameStack, round, measureText, {
 					onWarn,
 					irPath: item.irPath,
 					scopeChain: item.scopeChain,
-					resolveFill: paint.resolve
+					resolveFill: paint.resolve,
+					effectiveArrows,
+					effectivePathGenerators
 				});
 				if (item.slot) {
 					const idx = item.slot.sink.indexOf(item.slot.placeholder);
@@ -184,7 +236,7 @@ var compileToScene = (ir, options = {}) => {
 		for (let i = 0; i < children.length; i++) {
 			const child = children[i];
 			if (child.type === "node") {
-				const layout = require_node.layoutNode(require_style.resolveNodeStyle(child, styleStack), measureText, nameStack, nodeDistance, chain, require_style.resolveLabelDefault(styleStack), effectiveShapes);
+				const layout = require_node.layoutNode(require_style.resolveNodeStyle(child, styleStack), measureText, nameStack, nodeDistance, chain, require_style.resolveLabelDefault(styleStack), effectiveShapes, require_anchor.refPointOfTarget);
 				const globalLayout = chain.length === 0 ? layout : require_scope.projectLayoutToGlobal(layout, chain);
 				if (child.id) nameStack.register(child.id, globalLayout, `${locatorPrefix}children[${i}].node.id`);
 				for (const prim of require_node.emitNodePrimitives(layout, round, paint.resolve)) {
@@ -195,7 +247,7 @@ var compileToScene = (ir, options = {}) => {
 				for (const p of require_node.labelExtentPoints(globalLayout)) allPoints.push(p);
 				layoutsAccumulator.push(globalLayout);
 			} else if (child.type === "coordinate") {
-				const localCenter = require_position.resolvePosition(child.position, nameStack, nodeDistance, chain);
+				const localCenter = require_position.resolvePosition(child.position, nameStack, nodeDistance, chain, require_anchor.refPointOfTarget);
 				if (!localCenter) {
 					onWarn({
 						code: "POLAR_ORIGIN_UNRESOLVED",
@@ -241,12 +293,13 @@ var compileToScene = (ir, options = {}) => {
 					if (pushedFrame) nameStack.popFrame();
 				}
 				const hasOwnTransforms = ownTransforms.length > 0;
-				if (innerSink.length === 0 && !hasOwnTransforms && child.id === void 0) continue;
+				if (innerSink.length === 0 && !hasOwnTransforms && child.id === void 0 && child.clip === void 0) continue;
 				const group = {
 					type: "group",
 					children: stableSortByZIndex(sealSink(innerSink))
 				};
 				if (hasOwnTransforms) group.transforms = [...ownTransforms];
+				if (child.clip !== void 0) group.clipRef = clip.resolve(child.clip);
 				sink.push(group);
 				if (child.zIndex !== void 0) zIndexOf.set(group, child.zIndex);
 			} else {
@@ -276,10 +329,10 @@ var compileToScene = (ir, options = {}) => {
 		const detail = typeof process !== "undefined" && process.env.NODE_ENV !== "production" ? ` at ${collectPlaceholderLocators(primitives).join(", ")}` : "";
 		throw new Error(`internal: ${placeholderBalance} unresolved path placeholder(s) leaked into Scene output${detail}`);
 	}
-	const resources = paint.resources();
+	const resources = [...paint.resources(), ...clip.resources()];
 	return {
 		primitives: stableSortByZIndex(sealSink(primitives)),
-		layout: require_layout.computeLayout(allPoints, layoutPadding, round),
+		layout: ir.viewBox !== void 0 ? viewBoxToLayout(ir.viewBox, round) : require_layout.computeLayout(allPoints, layoutPadding, round),
 		...resources.length > 0 ? { resources } : {}
 	};
 };

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

@@ -1,6 +1,9 @@
 import { IR } from '../ir';
 import { Scene } from '../primitive';
 import { ShapeDefinition } from '../shapes';
+import { ArrowDefinition } from '../arrows';
+import { PatternDefinition } from '../patterns';
+import { PathGeneratorDefinition } from '../pathGenerators';
 import { TextMeasurer } from './text-metrics';
 /** 编译期警告：path / position 解析失败时通过 `CompileOptions.onWarn` 发出，不影响编译产物 */
 export type CompileWarning = {
@@ -8,7 +11,7 @@ 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' | 'DUPLICATE_NODE_ID' | 'SHAPE_OVERRIDES_BUILTIN' | (string & {});
+    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' | 'DUPLICATE_NODE_ID' | 'SHAPE_OVERRIDES_BUILTIN' | 'ARROW_OVERRIDES_BUILTIN' | 'PATTERN_OVERRIDES_BUILTIN' | (string & {});
     /** 人类可读消息（英文） */
     message: string;
     /** IR locator 路径（jq-like，如 `'children[3].path.children[1].to'`） */
@@ -41,6 +44,28 @@ export type CompileOptions = {
      *   `SHAPE_OVERRIDES_BUILTIN`。IR 的 `node.shape` 仍是字符串；未注册名在编译期 throw。
      */
     shapes?: Record<string, ShapeDefinition>;
+    /**
+     * 运行时注入的第三方 arrow（不进 IR）
+     * @description 有效 arrow 表 = `{ ...BUILTIN_ARROWS, ...arrows }`——同名 key 覆盖内置，经 `onWarn` 发
+     *   `ARROW_OVERRIDES_BUILTIN`。IR 的 `arrowDetail.shape` 仍是字符串；未注册名在编译期 throw。
+     */
+    arrows?: Record<string, ArrowDefinition>;
+    /**
+     * 运行时注入的第三方 pattern motif（不进 IR）
+     * @description 有效 pattern 表 = `{ ...BUILTIN_PATTERNS, ...patterns }`——同名 key 覆盖内置，经 `onWarn` 发
+     *   `PATTERN_OVERRIDES_BUILTIN`。IR 的 `pattern.shape` 仍是字符串；未注册名在编译期 throw。
+     *   compile 对 pattern 资源查本表 + 调 `PatternDefinition.emit` 产 tile，写进 `SceneResource.tile`。
+     */
+    patterns?: Record<string, PatternDefinition>;
+    /**
+     * 运行时注入的第三方 path generator（不进 IR）
+     * @description generator step 编译时按 `name` 查本表；core 不内置任何曲线生成器，故无内置合并。
+     *   解析时序：查表（未注册 throw，错误列出可用名）→ `paramsSchema.parse(params)` →
+     *   对结果再跑 `JsonObjectSchema.parse` 二次确认 JSON-safe → `targetParams` 顶层 key 经 target lookup
+     *   resolve 成世界坐标 → 调 `generate(ctx)` → splice 产出的 `PathCommand[]` 进命令流。IR 的
+     *   `generator.name` 仍是字符串；generator 函数本身只在此运行时注入面、不进 IR。
+     */
+    pathGenerators?: Record<string, PathGeneratorDefinition>;
 };
 /**
  * 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,EAAwC,MAAM,OAAO,CAAC;AACtE,OAAO,KAAK,EAAa,KAAK,EAA6B,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAqBjD,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AA4CrE,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,mBAAmB,GACnB,yBAAyB,GACzB,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,qCAAqC;IACrC,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;IAC3C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC1C,CAAC;AA6FF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAoSrE,CAAC"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/compile/compile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAwC,MAAM,OAAO,CAAC;AACtE,OAAO,KAAK,EAAa,KAAK,EAA6B,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAuBjE,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,gBAAgB,CAAC;AA4CrE,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,mBAAmB,GACnB,yBAAyB,GACzB,yBAAyB,GACzB,2BAA2B,GAC3B,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,qCAAqC;IACrC,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;IAC3C;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CAC1D,CAAC;AA+HF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KAqVrE,CAAC"}