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

package/dist/es/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/es/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/es/arrows/index.js

@@ -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
+export { BUILTIN_ARROWS };

package/dist/es/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/es/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/es/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/es/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;AAqBjE,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;AA6FF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,EAAE,EAAE,UAAS,cAAmB,KAAG,KA4UrE,CAAC"}

package/dist/es/compile/compile.js

@@ -1,5 +1,7 @@
 import { rect } from "../geometry/rect.js";
 import { BUILTIN_SHAPES } from "../shapes/index.js";
+import { BUILTIN_ARROWS } from "../arrows/index.js";
+import { BUILTIN_PATTERNS } from "../patterns/index.js";
 import { NameStack } from "./name-stack.js";
 import { applyTransformChain, computeScopeBoundingBox, lowerScopeTransforms, projectLayoutToGlobal, registerScopeAsLayout } from "./scope.js";
 import { resolvePosition } from "./position.js";
@@ -110,6 +112,29 @@ var compileToScene = (ir, options = {}) => {
 			path: `options.shapes.${name}`
 		});
 	}
+	const effectivePathGenerators = options.pathGenerators ?? {};
+	const effectiveArrows = options.arrows ? {
+		...BUILTIN_ARROWS,
+		...options.arrows
+	} : BUILTIN_ARROWS;
+	if (options.arrows) {
+		for (const name of Object.keys(options.arrows)) if (Object.prototype.hasOwnProperty.call(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 ? {
+		...BUILTIN_PATTERNS,
+		...options.patterns
+	} : BUILTIN_PATTERNS;
+	if (options.patterns) {
+		for (const name of Object.keys(options.patterns)) if (Object.prototype.hasOwnProperty.call(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 +159,7 @@ var compileToScene = (ir, options = {}) => {
 	};
 	const nameStack = new NameStack({ onDuplicate: (info) => onWarn(formatDuplicateWarning(info)) });
 	const allPoints = [];
-	const paint = createPaintRegistry();
+	const paint = createPaintRegistry(effectivePatterns, 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 子节点。
@@ -150,7 +175,9 @@ var compileToScene = (ir, options = {}) => {
 					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);

package/dist/es/compile/marker-prim.d.ts

@@ -0,0 +1,22 @@
+import { MarkerPrimitive } from '../primitive/marker';
+/** 深度查 emit 产物里有没有函数（守 Scene 100% JSON 可序列化） */
+export declare const assertNoFunction: (owner: string, value: unknown) => void;
+/**
+ * 深度查 emit 产物里有没有非 finite 数（NaN / Infinity）
+ * @description 第三方 / LLM 的 emit 算错坐标（除零 / 溢出）会产 NaN / Infinity；`JSON.stringify` 把它们变成
+ *   `null`，破坏 Scene round-trip 等价。故在此抛含 owner 的清晰错，不放任非 finite 流入 Scene（与 arrow
+ *   geometry / path generator 的 finite 守卫同源）。
+ */
+export declare const assertFiniteNumbers: (owner: string, value: unknown) => void;
+/**
+ * 递归校验单个 emit 产物符合 `MarkerPrimitive` 窄子集（运行时栅栏，TS 只能编译期守门）
+ * @description type 限 path/ellipse/rect/group（拒 text 等）；fill 限 string | contextStroke（拒 resourceRef
+ *   等外部资源引用）；group 递归 children。守"marker 内无文本布局 / 无外部资源 / 无递归 marker"契约。
+ */
+export declare const assertValidMarkerPrim: (owner: string, prim: unknown) => void;
+/**
+ * 跑完整窄子集 + JSON-safe 校验（产物逐个过 `assertValidMarkerPrim` + 深度无函数检查）
+ * @description arrow / pattern 调 emit 收齐 `MarkerPrimitive[]` 后调用；任一原语违窄子集即抛含 owner 的清晰错。
+ */
+export declare const validateMarkerPrimitives: (owner: string, marker: ReadonlyArray<MarkerPrimitive>) => void;
+//# sourceMappingURL=marker-prim.d.ts.map

package/dist/es/compile/marker-prim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker-prim.d.ts","sourceRoot":"","sources":["../../../src/compile/marker-prim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAa3D,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,EAAE,OAAO,OAAO,KAAG,IAWhE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,EAAE,OAAO,OAAO,KAAG,IAcnE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,EAAE,MAAM,OAAO,KAAG,IA2BpE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,MAAM,EACb,QAAQ,aAAa,CAAC,eAAe,CAAC,KACrC,IAIF,CAAC"}

package/dist/es/compile/marker-prim.js

@@ -0,0 +1,63 @@
+//#region src/compile/marker-prim.ts
+/**
+* marker 窄子集运行时栅栏（arrow + pattern 共用）
+* @description `MarkerPrimitive` 的窄子集（type 限 path/ellipse/rect/group、fill 限 string | contextStroke、
+*   无外部 resourceRef / text / 函数）TS 只能编译期守门；第三方 / LLM 写出的 emit 会在运行时绕过类型，
+*   故这里做运行时校验。arrow（marker 几何）与 pattern（motif 几何）emit 产物同契约，复用本组校验。
+*   `owner` 是错误消息里的归属串（如 `Arrow 'normal'` / `Pattern 'lines'`），便于第三方 / LLM 自修。
+*/
+/** marker 子集允许的 primitive type（窄子集运行时栅栏） */
+var MARKER_PRIM_TYPES = new Set([
+	"path",
+	"ellipse",
+	"rect",
+	"group"
+]);
+/** 深度查 emit 产物里有没有函数（守 Scene 100% JSON 可序列化） */
+var assertNoFunction = (owner, value) => {
+	if (typeof value === "function") throw new Error(`${owner} emit produced a marker containing a function; markers must be plain JSON data.`);
+	if (Array.isArray(value)) for (const v of value) assertNoFunction(owner, v);
+	else if (value !== null && typeof value === "object") for (const v of Object.values(value)) assertNoFunction(owner, v);
+};
+/**
+* 深度查 emit 产物里有没有非 finite 数（NaN / Infinity）
+* @description 第三方 / LLM 的 emit 算错坐标（除零 / 溢出）会产 NaN / Infinity；`JSON.stringify` 把它们变成
+*   `null`，破坏 Scene round-trip 等价。故在此抛含 owner 的清晰错，不放任非 finite 流入 Scene（与 arrow
+*   geometry / path generator 的 finite 守卫同源）。
+*/
+var assertFiniteNumbers = (owner, value) => {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${owner} emit produced a marker with a non-finite number (${String(value)}); marker coordinates must be finite.`);
+		return;
+	}
+	if (Array.isArray(value)) for (const v of value) assertFiniteNumbers(owner, v);
+	else if (value !== null && typeof value === "object") for (const v of Object.values(value)) assertFiniteNumbers(owner, v);
+};
+/**
+* 递归校验单个 emit 产物符合 `MarkerPrimitive` 窄子集（运行时栅栏，TS 只能编译期守门）
+* @description type 限 path/ellipse/rect/group（拒 text 等）；fill 限 string | contextStroke（拒 resourceRef
+*   等外部资源引用）；group 递归 children。守"marker 内无文本布局 / 无外部资源 / 无递归 marker"契约。
+*/
+var assertValidMarkerPrim = (owner, prim) => {
+	if (prim === null || typeof prim !== "object") throw new Error(`${owner} emit produced a non-object marker primitive.`);
+	const type = prim.type;
+	if (typeof type !== "string" || !MARKER_PRIM_TYPES.has(type)) throw new Error(`${owner} emit produced an invalid marker primitive type '${String(type)}'; allowed: group, path, ellipse, rect.`);
+	const fill = prim.fill;
+	if (fill !== void 0 && typeof fill !== "string" && !(typeof fill === "object" && fill !== null && fill.kind === "contextStroke")) throw new Error(`${owner} marker fill must be a color string or { kind: 'contextStroke' }; external paint references are not allowed inside markers.`);
+	if (type === "group") {
+		const children = prim.children;
+		if (!Array.isArray(children)) throw new Error(`${owner} marker group must have a children array.`);
+		for (const child of children) assertValidMarkerPrim(owner, child);
+	}
+};
+/**
+* 跑完整窄子集 + JSON-safe 校验（产物逐个过 `assertValidMarkerPrim` + 深度无函数检查）
+* @description arrow / pattern 调 emit 收齐 `MarkerPrimitive[]` 后调用；任一原语违窄子集即抛含 owner 的清晰错。
+*/
+var validateMarkerPrimitives = (owner, marker) => {
+	for (const prim of marker) assertValidMarkerPrim(owner, prim);
+	assertNoFunction(owner, marker);
+	assertFiniteNumbers(owner, marker);
+};
+//#endregion
+export { validateMarkerPrimitives };

package/dist/es/compile/paint.d.ts

@@ -1,4 +1,5 @@
 import { IRPaintSpec } from '../ir';
+import { PatternDefinition } from '../patterns';
 import { PaintValue, SceneResource } from '../primitive';
 /** fill 解析器：纯色 string 原样返回；PaintSpec 去重 + 派稳定 id → `{ kind:'resourceRef', id }`；undefined 透传 */
 export type PaintResolver = (fill: string | IRPaintSpec | undefined) => PaintValue | undefined;
@@ -11,6 +12,10 @@ export type PaintRegistry = {
  * 建一个 paint 登记表
  * @description resolve 对相同 PaintSpec（结构化 JSON 深比较）合并为一个资源、派稳定 id（`paint-1` / `paint-2`…，首见序）。
  *   同一份 IR 编译两次 → 同 id（快照稳定、SSR / CSR 一致）。SVG id 跨实例唯一性由 react adapter 加 useId 前缀解决。
+ *   pattern 资源额外查 `effectivePatterns` + 调 `PatternDefinition.emit` 产 tile 写进 `SceneResource.tile`
+ *   （未注册名 throw、含可用名）；gradient / image 资源只 spec。
+ * @param effectivePatterns 有效 pattern 表（内置 + 注入），供 pattern 资源查表 + emit
+ * @param round 精度取整（与 compile / render 同一 round，保 tile 几何一致）
  */
-export declare const createPaintRegistry: () => PaintRegistry;
+export declare const createPaintRegistry: (effectivePatterns: Record<string, PatternDefinition>, round: (n: number) => number) => PaintRegistry;
 //# sourceMappingURL=paint.d.ts.map

package/dist/es/compile/paint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../../src/compile/paint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9D,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,KAAK,UAAU,GAAG,SAAS,CAAC;AAE/F,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,aAAa,CAAC;IACvB,SAAS,EAAE,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;CACvC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAO,aAkBtC,CAAC"}
+{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../../src/compile/paint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAmB,UAAU,EAAuB,aAAa,EAAE,MAAM,cAAc,CAAC;AAGpG,gGAAgG;AAChG,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,KAAK,UAAU,GAAG,SAAS,CAAC;AAE/F,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,aAAa,CAAC;IACvB,SAAS,EAAE,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;CACvC,CAAC;AA+EF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC9B,mBAAmB,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACpD,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B,aAuBF,CAAC"}

package/dist/es/compile/paint.js

@@ -1,10 +1,65 @@
+import { validateMarkerPrimitives } from "./marker-prim.js";
 //#region src/compile/paint.ts
+/** 内置 / 注入都缺 defaultSize 时的 tile 周期兜底（user units） */
+var FALLBACK_PATTERN_SIZE = 8;
+/** motif 缺省主色：CSS `currentColor`（继承 svg color，主题反应天然） */
+var DEFAULT_MOTIF_COLOR = "currentColor";
+/**
+* 查有效 pattern 表取 def；未注册名编译期 throw（消息含字母序可用名列表）
+* @description 仿 arrow / shape 的未注册 throw 风格——错误带可用名便于第三方 / LLM 自修。
+*/
+var lookupPatternDef = (shape, effective) => {
+	if (Object.prototype.hasOwnProperty.call(effective, shape)) return effective[shape];
+	const available = Object.keys(effective).sort().join(", ");
+	throw new Error(`Unknown pattern shape '${shape}'; available: ${available}`);
+};
+/**
+* 对一个 pattern spec 查表 + 调 `def.emit` 产已解析 tile
+* @description 构 `PatternEmitContext`（size = spec.size ?? def.defaultSize ?? 8；color = spec.color ??
+*   currentColor；background 透传；lineWidth 仅 spec 显式给值时存在——让 dots 缺省半径 size/5、lines/grid
+*   缺省描边 1）→ 调 emit 收 `MarkerPrimitive[]` → 跑共享窄子集 + JSON-safe 校验 → 组装 `ResolvedPatternTile`。
+*   emit 抛错 / 产非法原语都包成含 shape 名的清晰错（带 cause）。
+*/
+var resolvePatternTile = (spec, effectivePatterns, round) => {
+	const def = lookupPatternDef(spec.shape, effectivePatterns);
+	const rawSize = spec.size ?? def.defaultSize ?? FALLBACK_PATTERN_SIZE;
+	if (!Number.isFinite(rawSize) || rawSize <= 0) throw new Error(`Pattern '${spec.shape}' has an invalid size (${String(rawSize)}); it must be a finite number greater than 0.`);
+	if (spec.lineWidth !== void 0 && (!Number.isFinite(spec.lineWidth) || spec.lineWidth <= 0)) throw new Error(`Pattern '${spec.shape}' has an invalid lineWidth (${String(spec.lineWidth)}); it must be a finite number greater than 0.`);
+	if (spec.rotation !== void 0 && !Number.isFinite(spec.rotation)) throw new Error(`Pattern '${spec.shape}' has a non-finite rotation (${String(spec.rotation)}); it must be a finite number.`);
+	const size = round(rawSize);
+	const ctx = {
+		size,
+		color: spec.color ?? DEFAULT_MOTIF_COLOR,
+		round
+	};
+	if (spec.background !== void 0) ctx.background = spec.background;
+	if (spec.lineWidth !== void 0) ctx.lineWidth = spec.lineWidth;
+	if (typeof def.emit !== "function") throw new Error(`Pattern '${spec.shape}' is missing an emit function (PatternDefinition.emit is required).`);
+	let motif;
+	try {
+		motif = [...def.emit(ctx)];
+	} catch (e) {
+		throw new Error(`Pattern '${spec.shape}' emit failed: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+	}
+	validateMarkerPrimitives(`Pattern '${spec.shape}'`, motif);
+	const tile = {
+		size,
+		motif
+	};
+	if (spec.background !== void 0) tile.background = spec.background;
+	if (spec.rotation !== void 0) tile.rotation = spec.rotation;
+	return tile;
+};
 /**
 * 建一个 paint 登记表
 * @description resolve 对相同 PaintSpec（结构化 JSON 深比较）合并为一个资源、派稳定 id（`paint-1` / `paint-2`…，首见序）。
 *   同一份 IR 编译两次 → 同 id（快照稳定、SSR / CSR 一致）。SVG id 跨实例唯一性由 react adapter 加 useId 前缀解决。
+*   pattern 资源额外查 `effectivePatterns` + 调 `PatternDefinition.emit` 产 tile 写进 `SceneResource.tile`
+*   （未注册名 throw、含可用名）；gradient / image 资源只 spec。
+* @param effectivePatterns 有效 pattern 表（内置 + 注入），供 pattern 资源查表 + emit
+* @param round 精度取整（与 compile / render 同一 round，保 tile 几何一致）
 */
-var createPaintRegistry = () => {
+var createPaintRegistry = (effectivePatterns, round) => {
 	const idByKey = /* @__PURE__ */ new Map();
 	const list = [];
 	let counter = 0;
@@ -17,11 +72,13 @@ var createPaintRegistry = () => {
 			counter += 1;
 			id = `paint-${counter}`;
 			idByKey.set(key, id);
-			list.push({
+			const resource = {
 				kind: "paint",
 				id,
 				spec: fill
-			});
+			};
+			if (fill.type === "pattern") resource.tile = resolvePatternTile(fill, effectivePatterns, round);
+			list.push(resource);
 		}
 		return {
 			kind: "resourceRef",

package/dist/es/compile/path/index.d.ts

@@ -1,8 +1,10 @@
 import { PaintResolver } from '../paint';
 import { IRPath, IRPosition } from '../../ir';
 import { ScenePrimitive, Transform } from '../../primitive';
+import { PathGeneratorDefinition } from '../../pathGenerators';
 import { NameStack } from '../name-stack';
 import { TextMeasurer } from '../text-metrics';
+import { EffectiveArrows } from './shrink';
 /** emitPathPrimitive 可选 warn 钩子 */
 export type EmitPathWarnHook = {
     /** 警告收集器（由 compileToScene 传入） */
@@ -21,6 +23,19 @@ export type EmitPathWarnHook = {
     scopeChain?: ReadonlyArray<Transform>;
     /** fill 解析器（PaintSpec → resourceRef + 登记资源）；缺省时纯色透传、PaintSpec 退化为无填充 */
     resolveFill?: PaintResolver;
+    /**
+     * 有效 arrow 表（内置 7 + 注入）；缺省 = 仅内置 7
+     * @description compileToScene 合并 `{ ...BUILTIN_ARROWS, ...options.arrows }` 传入；
+     *   endpointArrows 据此查表算 shrink / 调 def.emit；未注册名编译期 throw
+     */
+    effectiveArrows?: EffectiveArrows;
+    /**
+     * 有效 path generator 表（注入即全部，core 无内置）；缺省 = 空表
+     * @description compileToScene 传 `options.pathGenerators ?? {}`；generator step 据此查表（未注册名
+     *   编译期 throw，错误列出可用名）→ 双 parse 护栏 → targetParams resolve → 调 generate splice 命令。
+     *   解析逻辑由后续实现落地（此处仅声明 hook 入口）。
+     */
+    effectivePathGenerators?: Record<string, PathGeneratorDefinition>;
 };
 /**
  * IR Path → PathPrim

package/dist/es/compile/path/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAY9C,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EAGX,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAEV,cAAc,EACd,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AAkCtE,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iCAAiC;IACjC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,KAAK,IAAI,CAAC;IACX,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC,wEAAwE;IACxE,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,SAAS,EACpB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC5B,cAAa,YAA+B,EAC5C,WAAU,gBAAqB,KAC9B;IAAE,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CAAE,GAAG,IAqhBrE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAY9C,OAAO,KAAK,EACV,MAAM,EAEN,UAAU,EAGX,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAIV,cAAc,EACd,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AAKtE,OAAO,EAAE,KAAK,eAAe,EAA2D,MAAM,UAAU,CAAC;AAsFzG,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iCAAiC;IACjC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,KAAK,IAAI,CAAC;IACX,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtC,wEAAwE;IACxE,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CACnE,CAAC;AA0EF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,SAAS,EACpB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC5B,cAAa,YAA+B,EAC5C,WAAU,gBAAqB,KAC9B;IAAE,UAAU,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CAAE,GAAG,IA0tBrE,CAAC"}