@retikz/core 0.1.0 → 0.2.0-alpha.2

package/dist/es/compile/node.js

@@ -130,11 +130,16 @@ var labelCenter = (layout, label) => {
 };
 /**
 * 取节点 shape 在指定角度方向的边界点
-* @description 角度约定与 PolarPosition 一致（度数：0°=+x，90°=+y 即 screen 下方）；不应用 margin（同 anchorOf）；用于 `'A.30'` 落点
+* @description 角度是节点**局部坐标系**下的极角（度数：0°=局部 +x，90°=局部 +y）。layout.rect.rotate 把局部基绕中心旋转，得到世界系下的视觉方向；shape boundaryPoint 内部用 rotate-aware 投影，所以这里把局部 (cos, sin) 经 rect.rotate 旋转后加到中心当作世界系 toward 传入。不应用 margin（同 anchorOf）；用于 `'A.30'` 落点
 */
 var angleBoundaryOf = (layout, angleDeg) => {
 	const rad = angleDeg * Math.PI / 180;
-	const toward = [layout.rect.x + Math.cos(rad), layout.rect.y + Math.sin(rad)];
+	const lx = Math.cos(rad);
+	const ly = Math.sin(rad);
+	const rot = layout.rect.rotate ?? 0;
+	const cosR = Math.cos(rot);
+	const sinR = Math.sin(rot);
+	const toward = [layout.rect.x + lx * cosR - ly * sinR, layout.rect.y + lx * sinR + ly * cosR];
 	switch (layout.shape) {
 		case "rectangle": return rect.boundaryPoint(rectOf(layout, 0), toward);
 		case "circle": return circle.boundaryPoint(circleOf(layout, 0), toward);
@@ -144,9 +149,12 @@ var angleBoundaryOf = (layout, angleDeg) => {
 };
 /**
 * IR Node → 内部 NodeLayout
-* @description 文本度量 + padding 推内框半轴；按 shape 算外接边界（circle 取半对角线、ellipse ×√2、diamond ×2）；解析 position 为几何中心；rotate 度数转弧度
+* @description 文本度量 + padding 推内框半轴；按 shape 算外接边界（circle 取半对角线、ellipse ×√2、diamond ×2）；解析 position 为几何中心；rotate 度数转弧度。
+*   `scopeChain` 非空时 `resolvePosition` 返回**当前 scope 局部坐标**（relative position 在当前
+*   scope 局部度量），调用方负责后续 `projectLayoutToGlobal` / `applyTransformChain` 投回全局；
+*   笛卡尔字面量 `Position` 已在 scope 局部度量，行为延续 v0.1。
 */
-var layoutNode = (node, measureText, nodeIndex, nodeDistance) => {
+var layoutNode = (node, measureText, nameStack, nodeDistance, scopeChain = [], labelDefault) => {
 	const sx = node.xScale ?? node.scale ?? 1;
 	const sy = node.yScale ?? node.scale ?? 1;
 	const fontScale = Math.min(sx, sy);
@@ -217,7 +225,7 @@ var layoutNode = (node, measureText, nodeIndex, nodeDistance) => {
 			break;
 	}
 	const rotateDeg = node.rotate ?? 0;
-	const center = resolvePosition(node.position, nodeIndex, nodeDistance);
+	const center = resolvePosition(node.position, nameStack, nodeDistance, scopeChain);
 	if (!center) throw new Error(`Cannot resolve position for node ${node.id ?? "(unnamed)"}; polar.origin or at.of may reference an undefined node`);
 	const labels = (node.label === void 0 ? void 0 : Array.isArray(node.label) ? node.label : [node.label])?.map((lab) => {
 		const labFont = lab.font;
@@ -225,12 +233,12 @@ var layoutNode = (node, measureText, nodeIndex, nodeDistance) => {
 			text: lab.text,
 			position: lab.position ?? "above",
 			distance: lab.distance ?? DEFAULT_LABEL_DISTANCE,
-			textColor: lab.textColor ?? node.textColor,
-			opacity: lab.opacity,
-			fontSize: (labFont?.size ?? baseFontSize) * fontScale,
-			fontFamily: labFont?.family ?? fontFamily,
-			fontWeight: labFont?.weight ?? fontWeight,
-			fontStyle: labFont?.style ?? fontStyle
+			textColor: lab.textColor ?? labelDefault?.textColor ?? labelDefault?.color ?? node.textColor,
+			opacity: lab.opacity ?? labelDefault?.opacity,
+			fontSize: (labFont?.size ?? labelDefault?.font?.size ?? baseFontSize) * fontScale,
+			fontFamily: labFont?.family ?? labelDefault?.font?.family ?? fontFamily,
+			fontWeight: labFont?.weight ?? labelDefault?.font?.weight ?? fontWeight,
+			fontStyle: labFont?.style ?? labelDefault?.font?.style ?? fontStyle
 		};
 	});
 	return {

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

@@ -1,17 +1,23 @@
 import { IRPosition, IRTarget } from '../../ir';
-import { NodeLayout } from '../node';
+import { Transform } from '../../primitive';
+import { NameStack } from '../name-stack';
 /**
  * 求 step.to 的参考点（给 boundary clip 算方向 / 折角 corner 用）
- * @description 三态：`'A'`(auto) 节点中心；`'A.<anchor>'`/`'A.<deg>'` 显式锚点 refPoint=endpoint 位置不随邻居变。直接坐标/极坐标解析为笛卡尔
+ * @description 三态：`'A'`(auto) 节点中心；`'A.<anchor>'`/`'A.<deg>'` 显式锚点 refPoint=endpoint 位置不随邻居变。直接坐标/极坐标解析为笛卡尔。
+ *   string id lookup 拿到的 layout 已是全局坐标——不走 scopeChain 投影；Position / Polar /
+ *   At / Offset 字面量经 `resolvePosition(..., scopeChain)` 拿到当前 scope 局部坐标后
+ *   `applyTransformChain` 投回全局。`scopeChain=[]` 等价 v0.1（恒等）。
  */
-export declare const refPointOfTarget: (target: IRTarget, nodeIndex: Map<string, NodeLayout>) => IRPosition | null;
+export declare const refPointOfTarget: (target: IRTarget, nameStack: NameStack, scopeChain?: ReadonlyArray<Transform>) => IRPosition | null;
 /** 折角中间点：`-|` → (curr.x, prev.y)；`|-` → (prev.x, curr.y) */
 export declare const cornerOf: (prev: IRPosition, curr: IRPosition, via: "-|" | "|-") => IRPosition;
 /**
  * 在 toward 方向算 step.to 的实际绘制端点
- * @description 节点 auto `'A'`：按 shape 走 boundaryPointOf 求中心→toward 射线交点；命名 anchor/角度：位置已定不受 toward 影响；直接坐标/极坐标：解析后返回；失败返回 null
+ * @description 节点 auto `'A'`：按 shape 走 boundaryPointOf 求中心→toward 射线交点；命名 anchor/角度：位置已定不受 toward 影响；直接坐标/极坐标：解析后返回；失败返回 null。
+ *   string id lookup 拿到的 layout 已是全局坐标；Position / Polar / At / Offset 字面量经
+ *   `resolvePosition(..., scopeChain)` 拿到当前 scope 局部坐标后 `applyTransformChain` 投回全局。
  */
-export declare const clipForTarget: (target: IRTarget, toward: IRPosition, nodeIndex: Map<string, NodeLayout>) => IRPosition | null;
+export declare const clipForTarget: (target: IRTarget, toward: IRPosition, nameStack: NameStack, scopeChain?: ReadonlyArray<Transform>) => IRPosition | null;
 /** 两个 IRPosition 两分量精确相等（未 round） */
 export declare const samePoint: (a: IRPosition | null, b: IRPosition | null) => boolean;
 /** 把 p 朝 target 方向移动 dist */

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

@@ -1 +1 @@
-{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,KAAK,UAAU,EAA8C,MAAM,SAAS,CAAC;AAItF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,QAAQ,EAChB,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KACjC,UAAU,GAAG,IAmBf,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,GACnB,MAAM,UAAU,EAChB,MAAM,UAAU,EAChB,KAAK,IAAI,GAAG,IAAI,KACf,UACqD,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,QAAQ,EAChB,QAAQ,UAAU,EAClB,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KACjC,UAAU,GAAG,IAmBf,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,GAAG,IAAI,EAAE,GAAG,UAAU,GAAG,IAAI,KAAG,OACzB,CAAC;AAE/C,6BAA6B;AAC7B,eAAO,MAAM,WAAW,GAAI,GAAG,UAAU,EAAE,QAAQ,UAAU,EAAE,MAAM,MAAM,KAAG,UAM7E,CAAC"}
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/anchor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM/C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,QAAQ,EAChB,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,UAAU,GAAG,IAqBf,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,QAAQ,GACnB,MAAM,UAAU,EAChB,MAAM,UAAU,EAChB,KAAK,IAAI,GAAG,IAAI,KACf,UACqD,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,QAAQ,EAChB,QAAQ,UAAU,EAClB,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,UAAU,GAAG,IAqBf,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,GAAG,IAAI,EAAE,GAAG,UAAU,GAAG,IAAI,KAAG,OACzB,CAAC;AAE/C,6BAA6B;AAC7B,eAAO,MAAM,WAAW,GAAI,GAAG,UAAU,EAAE,QAAQ,UAAU,EAAE,MAAM,MAAM,KAAG,UAM7E,CAAC"}

package/dist/es/compile/path/anchor.js

@@ -1,44 +1,55 @@
+import { applyTransformChain } from "../scope.js";
 import { resolvePosition } from "../position.js";
-import { anchorOf, angleBoundaryOf, boundaryPointOf } from "../node.js";
+import { boundaryPointOf } from "../node.js";
+import { resolveAnchor } from "../anchor-cache.js";
 import { parseNodeRef } from "../parseTarget.js";
 //#region src/compile/path/anchor.ts
 /**
 * 求 step.to 的参考点（给 boundary clip 算方向 / 折角 corner 用）
-* @description 三态：`'A'`(auto) 节点中心；`'A.<anchor>'`/`'A.<deg>'` 显式锚点 refPoint=endpoint 位置不随邻居变。直接坐标/极坐标解析为笛卡尔
+* @description 三态：`'A'`(auto) 节点中心；`'A.<anchor>'`/`'A.<deg>'` 显式锚点 refPoint=endpoint 位置不随邻居变。直接坐标/极坐标解析为笛卡尔。
+*   string id lookup 拿到的 layout 已是全局坐标——不走 scopeChain 投影；Position / Polar /
+*   At / Offset 字面量经 `resolvePosition(..., scopeChain)` 拿到当前 scope 局部坐标后
+*   `applyTransformChain` 投回全局。`scopeChain=[]` 等价 v0.1（恒等）。
 */
-var refPointOfTarget = (target, nodeIndex) => {
+var refPointOfTarget = (target, nameStack, scopeChain = []) => {
 	if (typeof target === "string") {
 		const ref = parseNodeRef(target);
-		const node = nodeIndex.get(ref.id);
+		const node = nameStack.lookup(ref.id);
 		if (!node) return null;
 		switch (ref.kind) {
 			case "node": return [node.rect.x, node.rect.y];
-			case "anchor": return anchorOf(node, ref.anchor);
-			case "angle": return angleBoundaryOf(node, ref.angle);
+			case "anchor": return resolveAnchor(node, ref.anchor);
+			case "angle": return resolveAnchor(node, String(ref.angle));
 		}
 	}
 	if (typeof target === "object" && !Array.isArray(target) && ("relative" in target || "relativeAccumulate" in target)) return null;
-	return resolvePosition(target, nodeIndex);
+	const local = resolvePosition(target, nameStack, void 0, scopeChain);
+	if (!local) return null;
+	return scopeChain.length === 0 ? local : applyTransformChain(local, scopeChain);
 };
 /** 折角中间点：`-|` → (curr.x, prev.y)；`|-` → (prev.x, curr.y) */
 var cornerOf = (prev, curr, via) => via === "-|" ? [curr[0], prev[1]] : [prev[0], curr[1]];
 /**
 * 在 toward 方向算 step.to 的实际绘制端点
-* @description 节点 auto `'A'`：按 shape 走 boundaryPointOf 求中心→toward 射线交点；命名 anchor/角度：位置已定不受 toward 影响；直接坐标/极坐标：解析后返回；失败返回 null
+* @description 节点 auto `'A'`：按 shape 走 boundaryPointOf 求中心→toward 射线交点；命名 anchor/角度：位置已定不受 toward 影响；直接坐标/极坐标：解析后返回；失败返回 null。
+*   string id lookup 拿到的 layout 已是全局坐标；Position / Polar / At / Offset 字面量经
+*   `resolvePosition(..., scopeChain)` 拿到当前 scope 局部坐标后 `applyTransformChain` 投回全局。
 */
-var clipForTarget = (target, toward, nodeIndex) => {
+var clipForTarget = (target, toward, nameStack, scopeChain = []) => {
 	if (typeof target === "string") {
 		const ref = parseNodeRef(target);
-		const node = nodeIndex.get(ref.id);
+		const node = nameStack.lookup(ref.id);
 		if (!node) return null;
 		switch (ref.kind) {
 			case "node": return boundaryPointOf(node, toward);
-			case "anchor": return anchorOf(node, ref.anchor);
-			case "angle": return angleBoundaryOf(node, ref.angle);
+			case "anchor": return resolveAnchor(node, ref.anchor);
+			case "angle": return resolveAnchor(node, String(ref.angle));
 		}
 	}
 	if (typeof target === "object" && !Array.isArray(target) && ("relative" in target || "relativeAccumulate" in target)) return null;
-	return resolvePosition(target, nodeIndex);
+	const local = resolvePosition(target, nameStack, void 0, scopeChain);
+	if (!local) return null;
+	return scopeChain.length === 0 ? local : applyTransformChain(local, scopeChain);
 };
 /** 两个 IRPosition 两分量精确相等（未 round） */
 var samePoint = (a, b) => !!a && !!b && a[0] === b[0] && a[1] === b[1];

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

@@ -1,6 +1,6 @@
 import { IRPath, IRPosition } from '../../ir';
-import { ScenePrimitive } from '../../primitive';
-import { NodeLayout } from '../node';
+import { ScenePrimitive, Transform } from '../../primitive';
+import { NameStack } from '../name-stack';
 import { TextMeasurer } from '../text-metrics';
 /** emitPathPrimitive 可选 warn 钩子 */
 export type EmitPathWarnHook = {
@@ -12,12 +12,18 @@ export type EmitPathWarnHook = {
     }) => void;
     /** 当前 path 在 IR 中的 locator 前缀（如 `'children[3].path'`） */
     irPath?: string;
+    /**
+     * 该 path 所属 scope 的累积 Cartesian-only transform 链
+     * @description step.to 内的 polar/at/offset 字面量按"当前 scope 局部度量 + 末端 apply chain"
+     *   投影回全局；顶层 path / 无 scope chain 时为 `[]`（恒等，等价 v0.1 行为）
+     */
+    scopeChain?: ReadonlyArray<Transform>;
 };
 /**
  * IR Path → PathPrim
  * @description 每个绘制段独立用节点中心算两端 boundary clip——中段节点的入/出 boundary 点通常不同，path 在该节点可见"断开"（与 TikZ `\draw (A)--(B)--(C);` 段独立 clip 一致）。仍产一个 PathPrim：commands 用多组 move/line 表达 sub-path；段起点等于上段终点时复用 cursor 省 move。cycle 段闭回最近 move 起点，起点==lastEnd && 终点==subPathStart 时输出 close，否则显式画段 line。引用未定义节点/解析失败返回 null，并通过 `warnHook.onWarn` 同步触发 warning
  */
-export declare const emitPathPrimitive: (path: IRPath, nodeIndex: Map<string, NodeLayout>, round: (n: number) => number, measureText?: TextMeasurer, warnHook?: EmitPathWarnHook) => {
+export declare const emitPathPrimitive: (path: IRPath, nameStack: NameStack, round: (n: number) => number, measureText?: TextMeasurer, warnHook?: EmitPathWarnHook) => {
     primitives: Array<ScenePrimitive>;
     points: Array<IRPosition>;
 } | null;

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":"AAYA,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EAGX,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAEV,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AA8BtE,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;CACjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAClC,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,IA0XrE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/index.ts"],"names":[],"mappings":"AAYA,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;AA8BtE,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;CACvC,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,IA2XrE,CAAC"}

package/dist/es/compile/path/index.js

@@ -26,7 +26,7 @@ var THICKNESS_TO_WIDTH = {
 * IR Path → PathPrim
 * @description 每个绘制段独立用节点中心算两端 boundary clip——中段节点的入/出 boundary 点通常不同，path 在该节点可见"断开"（与 TikZ `\draw (A)--(B)--(C);` 段独立 clip 一致）。仍产一个 PathPrim：commands 用多组 move/line 表达 sub-path；段起点等于上段终点时复用 cursor 省 move。cycle 段闭回最近 move 起点，起点==lastEnd && 终点==subPathStart 时输出 close，否则显式画段 line。引用未定义节点/解析失败返回 null，并通过 `warnHook.onWarn` 同步触发 warning
 */
-var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer, warnHook = {}) => {
+var emitPathPrimitive = (path, nameStack, round, measureText = fallbackMeasurer, warnHook = {}) => {
 	const irPath = warnHook.irPath ?? "path";
 	const warn = (code, message, subPath = "") => {
 		warnHook.onWarn?.({
@@ -35,7 +35,8 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 			path: subPath ? `${irPath}.${subPath}` : irPath
 		});
 	};
-	const steps = normalizeRelativeTargets(path.children, nodeIndex);
+	const scopeChain = warnHook.scopeChain ?? [];
+	const steps = normalizeRelativeTargets(path.children, nameStack, scopeChain);
 	if (steps.length < 2) {
 		warn("PATH_TOO_SHORT", `Path requires at least 2 steps (got ${steps.length}); the entire path is skipped`, "children");
 		return null;
@@ -46,14 +47,14 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 	const collectLabel = (step, sampleAt) => {
 		if (step.kind === "move" || step.kind === "cycle" || !("label" in step) || !step.label) return;
 		const sample = sampleAt(tForLabelPosition(step.label.position));
-		const r = emitLabelPrimitive(step.label, sample, measureText, round);
+		const r = emitLabelPrimitive(step.label, sample, measureText, round, path.opacity);
 		labelPrims.push(r.primitive);
 		for (const p of r.points) points.push(p);
 	};
 	const hasTo = (s) => s.kind !== "cycle" && s.kind !== "arc" && s.kind !== "circlePath" && s.kind !== "ellipsePath";
 	const anchors = steps.map((s, idx) => {
 		if (!hasTo(s)) return null;
-		const ref = refPointOfTarget(s.to, nodeIndex);
+		const ref = refPointOfTarget(s.to, nameStack, scopeChain);
 		if (!ref && typeof s.to === "string") warn("UNRESOLVED_NODE_REFERENCE", `Step.to references undefined node id '${s.to}'; the entire path is skipped`, `children[${idx}].to`);
 		return ref;
 	});
@@ -179,10 +180,10 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 			const moveTo = lastMoveTo;
 			const prev = findPrev();
 			if (!moveTo || !prev) continue;
-			const moveAnchor = refPointOfTarget(moveTo, nodeIndex);
+			const moveAnchor = refPointOfTarget(moveTo, nameStack, scopeChain);
 			if (!moveAnchor) return null;
-			const fromClip = clipForTarget(prev.step.to, moveAnchor, nodeIndex);
-			const toClip = clipForTarget(moveTo, prev.anchor, nodeIndex);
+			const fromClip = clipForTarget(prev.step.to, moveAnchor, nameStack, scopeChain);
+			const toClip = clipForTarget(moveTo, prev.anchor, nameStack, scopeChain);
 			if (!fromClip || !toClip) return null;
 			if (samePoint(fromClip, lastEnd) && samePoint(toClip, subPathStart)) {
 				emitClose();
@@ -237,8 +238,8 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 		const usedOverride = penOverride;
 		penOverride = null;
 		if (step.kind === "line") {
-			const fromClip = usedOverride ?? clipForTarget(prev.step.to, currAnchor, nodeIndex);
-			const toClip = clipForTarget(step.to, prev.anchor, nodeIndex);
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, currAnchor, nameStack, scopeChain);
+			const toClip = clipForTarget(step.to, prev.anchor, nameStack, scopeChain);
 			if (!fromClip || !toClip) return null;
 			startSegment(fromClip);
 			emitLine(toClip);
@@ -246,8 +247,8 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 			continue;
 		}
 		if (step.kind === "curve") {
-			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control, nodeIndex);
-			const toClip = clipForTarget(step.to, step.control, nodeIndex);
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control, nameStack, scopeChain);
+			const toClip = clipForTarget(step.to, step.control, nameStack, scopeChain);
 			if (!fromClip || !toClip) return null;
 			startSegment(fromClip);
 			emitQuad(step.control, toClip);
@@ -255,8 +256,8 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 			continue;
 		}
 		if (step.kind === "cubic") {
-			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control1, nodeIndex);
-			const toClip = clipForTarget(step.to, step.control2, nodeIndex);
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, step.control1, nameStack, scopeChain);
+			const toClip = clipForTarget(step.to, step.control2, nameStack, scopeChain);
 			if (!fromClip || !toClip) return null;
 			startSegment(fromClip);
 			emitCubic(step.control1, step.control2, toClip);
@@ -266,8 +267,8 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 		if (step.kind === "bend") {
 			const angle = step.bendAngle ?? 30;
 			const [c1, c2] = bendControlPoints(prev.anchor, currAnchor, step.bendDirection, angle);
-			const fromClip = usedOverride ?? clipForTarget(prev.step.to, c1, nodeIndex);
-			const toClip = clipForTarget(step.to, c2, nodeIndex);
+			const fromClip = usedOverride ?? clipForTarget(prev.step.to, c1, nameStack, scopeChain);
+			const toClip = clipForTarget(step.to, c2, nameStack, scopeChain);
 			if (!fromClip || !toClip) return null;
 			startSegment(fromClip);
 			emitCubic(c1, c2, toClip);
@@ -275,8 +276,8 @@ var emitPathPrimitive = (path, nodeIndex, round, measureText = fallbackMeasurer,
 			continue;
 		}
 		const corner = cornerOf(prev.anchor, currAnchor, step.via);
-		const fromClip = usedOverride ?? clipForTarget(prev.step.to, corner, nodeIndex);
-		const toClip = clipForTarget(step.to, corner, nodeIndex);
+		const fromClip = usedOverride ?? clipForTarget(prev.step.to, corner, nameStack, scopeChain);
+		const toClip = clipForTarget(step.to, corner, nameStack, scopeChain);
 		if (!fromClip || !toClip) return null;
 		startSegment(fromClip);
 		emitLine(corner);

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

@@ -11,7 +11,7 @@ export declare const tForLabelPosition: (pos: IRStepLabel["position"]) => number
  * step.label + 段采样 → TextPrim（sloped 时裹一层 group 旋转）
  * @description 默认 side='above'/position='midway'：above/below 锚点 y±offset、align=middle、baseline=bottom/top；left/right x±offset、align=end/start、baseline=middle；sloped 不偏移裹 group rotate(angle, cx, cy) 由切线 atan2 算（SVG y-down CW 正）。返回 primitive + layout 外接点
  */
-export declare const emitLabelPrimitive: (label: IRStepLabel, sample: SegmentSample, measureText: TextMeasurer, round: (n: number) => number) => {
+export declare const emitLabelPrimitive: (label: IRStepLabel, sample: SegmentSample, measureText: TextMeasurer, round: (n: number) => number, hostOpacity?: number) => {
     primitive: ScenePrimitive;
     points: Array<IRPosition>;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/label.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAmBpD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,WAAW,CAAC,UAAU,CAAC,KAAG,MAIhE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,WAAW,EAClB,QAAQ,aAAa,EACrB,aAAa,YAAY,EACzB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,KAC3B;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CA8ExD,CAAC"}
+{"version":3,"file":"label.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/label.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAmBpD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,WAAW,CAAC,UAAU,CAAC,KAAG,MAIhE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,WAAW,EAClB,QAAQ,aAAa,EACrB,aAAa,YAAY,EACzB,OAAO,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,EAC5B,cAAc,MAAM,KACnB;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CAkGxD,CAAC"}

package/dist/es/compile/path/label.js

@@ -27,13 +27,22 @@ var tForLabelPosition = (pos) => {
 * step.label + 段采样 → TextPrim（sloped 时裹一层 group 旋转）
 * @description 默认 side='above'/position='midway'：above/below 锚点 y±offset、align=middle、baseline=bottom/top；left/right x±offset、align=end/start、baseline=middle；sloped 不偏移裹 group rotate(angle, cx, cy) 由切线 atan2 算（SVG y-down CW 正）。返回 primitive + layout 外接点
 */
-var emitLabelPrimitive = (label, sample, measureText, round) => {
-	const fontSize = LABEL_FONT_SIZE;
+var emitLabelPrimitive = (label, sample, measureText, round, hostOpacity) => {
+	const fontSize = label.font?.size ?? LABEL_FONT_SIZE;
+	const fontFamily = label.font?.family;
+	const fontWeight = label.font?.weight;
+	const fontStyle = label.font?.style;
 	const lineHeight = fontSize * LABEL_LINE_HEIGHT_FACTOR;
-	const m = measureText(label.text, { size: fontSize });
+	const m = measureText(label.text, {
+		size: fontSize,
+		family: fontFamily,
+		weight: fontWeight,
+		style: fontStyle
+	});
 	const measuredWidth = m.width;
 	const measuredHeight = m.height || lineHeight;
 	const side = label.side ?? "above";
+	const labelOpacity = label.opacity !== void 0 ? hostOpacity !== void 0 ? label.opacity * hostOpacity : label.opacity : hostOpacity;
 	let x = sample.point[0];
 	let y = sample.point[1];
 	let align = "middle";
@@ -62,8 +71,12 @@ var emitLabelPrimitive = (label, sample, measureText, round) => {
 		lineHeight: round(lineHeight),
 		measuredWidth: round(measuredWidth),
 		measuredHeight: round(measuredHeight),
-		fill: "currentColor"
+		fill: label.textColor ?? "currentColor"
 	};
+	if (fontFamily !== void 0) text.fontFamily = fontFamily;
+	if (fontWeight !== void 0) text.fontWeight = fontWeight;
+	if (fontStyle !== void 0) text.fontStyle = fontStyle;
+	if (labelOpacity !== void 0) text.opacity = labelOpacity;
 	if (side === "sloped") {
 		const groupPrim = {
 			type: "group",

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

@@ -1,8 +1,14 @@
 import { IRStep } from '../../ir';
-import { NodeLayout } from '../node';
+import { Transform } from '../../primitive';
+import { NameStack } from '../name-stack';
 /**
- * relative/relativeAccumulate 目标解析为绝对 Position（step kind 不变，to 全为绝对坐标）
- * @description relative 不更新 prevEnd（TikZ `+`），relativeAccumulate 更新（TikZ `++`）。prevEnd 推进：有 to 的 kind 用 refPointOfTarget(to)；arc 用 arcEndPoint；circlePath/ellipsePath/cycle 不变。首步 relative 时 prevEnd 回退 [0,0]；解析失败保持原 step
+ * relative/relativeAccumulate 目标解析为绝对 Position（step kind 不变，to 为局部坐标 tuple）
+ * @description relative 不更新 prevEnd（TikZ `+`），relativeAccumulate 更新（TikZ `++`）。prevEnd 推进：有 to 的 kind 用 refPointOfTarget(to)；arc 用 arcEndPoint；circlePath/ellipsePath/cycle 不变。首步 relative 时 prevEnd 回退 [0,0]；解析失败保持原 step。
+ *   prevEnd 始终是全局坐标系下的 cursor；relative 形态 `[dx, dy]` 在**当前 scope 局部度量**——
+ *   先反向投影 prevEnd 到 scope 局部 + 加 (dx, dy) 得局部 tuple，写回 step.to。下游
+ *   `refPointOfTarget` / `clipForTarget` 把 tuple 视作 scope 局部字面量，统一 `applyTransformChain` 投回全局——
+ *   relative 分支只负责"折算到局部"，不能在此处提前投影到全局，否则与下游 chain apply 形成 double-apply。
+ *   `scopeChain=[]` 时 inverse 恒等，等价 v0.1 行为。
  */
-export declare const normalizeRelativeTargets: (steps: ReadonlyArray<IRStep>, nodeIndex: Map<string, NodeLayout>) => Array<IRStep>;
+export declare const normalizeRelativeTargets: (steps: ReadonlyArray<IRStep>, nameStack: NameStack, scopeChain?: ReadonlyArray<Transform>) => Array<IRStep>;
 //# sourceMappingURL=relative.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"relative.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/relative.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAc,MAAM,EAAY,MAAM,UAAU,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG1C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,WAAW,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KACjC,KAAK,CAAC,MAAM,CA0Dd,CAAC"}
+{"version":3,"file":"relative.d.ts","sourceRoot":"","sources":["../../../../src/compile/path/relative.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAc,MAAM,EAAY,MAAM,UAAU,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,WAAW,SAAS,EACpB,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,KAAK,CAAC,MAAM,CAuEd,CAAC"}

package/dist/es/compile/path/relative.js

@@ -1,11 +1,17 @@
+import { inverseTransformChain } from "../scope.js";
 import { arcEndPoint } from "../../geometry/arc.js";
 import { refPointOfTarget } from "./anchor.js";
 //#region src/compile/path/relative.ts
 /**
-* relative/relativeAccumulate 目标解析为绝对 Position（step kind 不变，to 全为绝对坐标）
-* @description relative 不更新 prevEnd（TikZ `+`），relativeAccumulate 更新（TikZ `++`）。prevEnd 推进：有 to 的 kind 用 refPointOfTarget(to)；arc 用 arcEndPoint；circlePath/ellipsePath/cycle 不变。首步 relative 时 prevEnd 回退 [0,0]；解析失败保持原 step
+* relative/relativeAccumulate 目标解析为绝对 Position（step kind 不变，to 为局部坐标 tuple）
+* @description relative 不更新 prevEnd（TikZ `+`），relativeAccumulate 更新（TikZ `++`）。prevEnd 推进：有 to 的 kind 用 refPointOfTarget(to)；arc 用 arcEndPoint；circlePath/ellipsePath/cycle 不变。首步 relative 时 prevEnd 回退 [0,0]；解析失败保持原 step。
+*   prevEnd 始终是全局坐标系下的 cursor；relative 形态 `[dx, dy]` 在**当前 scope 局部度量**——
+*   先反向投影 prevEnd 到 scope 局部 + 加 (dx, dy) 得局部 tuple，写回 step.to。下游
+*   `refPointOfTarget` / `clipForTarget` 把 tuple 视作 scope 局部字面量，统一 `applyTransformChain` 投回全局——
+*   relative 分支只负责"折算到局部"，不能在此处提前投影到全局，否则与下游 chain apply 形成 double-apply。
+*   `scopeChain=[]` 时 inverse 恒等，等价 v0.1 行为。
 */
-var normalizeRelativeTargets = (steps, nodeIndex) => {
+var normalizeRelativeTargets = (steps, nameStack, scopeChain = []) => {
 	let prevEnd = null;
 	const out = [];
 	for (const step of steps) {
@@ -26,19 +32,21 @@ var normalizeRelativeTargets = (steps, nodeIndex) => {
 		let resolvedTo = original;
 		let updatePrevEnd = true;
 		if (typeof original === "object" && !Array.isArray(original) && "relative" in original) {
-			const ref = prevEnd ?? [0, 0];
-			resolvedTo = [ref[0] + original.relative[0], ref[1] + original.relative[1]];
+			const refGlobal = prevEnd ?? [0, 0];
+			const refLocal = scopeChain.length === 0 ? refGlobal : inverseTransformChain(refGlobal, scopeChain);
+			resolvedTo = [refLocal[0] + original.relative[0], refLocal[1] + original.relative[1]];
 			updatePrevEnd = false;
 		} else if (typeof original === "object" && !Array.isArray(original) && "relativeAccumulate" in original) {
-			const ref = prevEnd ?? [0, 0];
-			resolvedTo = [ref[0] + original.relativeAccumulate[0], ref[1] + original.relativeAccumulate[1]];
+			const refGlobal = prevEnd ?? [0, 0];
+			const refLocal = scopeChain.length === 0 ? refGlobal : inverseTransformChain(refGlobal, scopeChain);
+			resolvedTo = [refLocal[0] + original.relativeAccumulate[0], refLocal[1] + original.relativeAccumulate[1]];
 		}
 		out.push({
 			...step,
 			to: resolvedTo
 		});
 		if (updatePrevEnd) {
-			const pos = refPointOfTarget(resolvedTo, nodeIndex);
+			const pos = refPointOfTarget(resolvedTo, nameStack, scopeChain);
 			if (pos) prevEnd = pos;
 		}
 	}

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

@@ -1,8 +1,24 @@
 import { IRAtPosition, IROffsetPosition, IRPosition, PolarPosition } from '../ir';
-import { NodeLayout } from './node';
+import { Transform } from '../primitive';
+import { NameStack } from './name-stack';
 /**
  * IR 各种位置形态（笛卡尔/极坐标/相对定位/偏移定位/节点 id）→ 笛卡尔位置
- * @description 极坐标 origin / 偏移定位 of 均可递归引用节点 id 或字面坐标；relative `AtPosition` of 必须引用已定义节点/coordinate；解析失败返回 null。nodeDistance 为容器 prop 注入默认距离，AtPosition 自带 distance 优先
+ * @description
+ *   - **返回值语义**：当 `scopeChain` 非空时，返回**当前 scope 局部坐标系**下的笛卡尔位置；
+ *     调用方负责走 `applyTransformChain(local, scopeChain)` 投回全局。当 `scopeChain` 为空时
+ *     等价于 v0.1 行为（全局坐标）。
+ *   - **referent 处理**：node id lookup 拿到的 layout.rect 已是全局坐标；本函数内部用
+ *     `inverseTransformChain` 把全局 referent 反向投影到当前 scope 局部坐标系作为"在当前
+ *     scope 局部的固定点"基准。relative 部分（polar 的 angle/radius、at 的 direction/distance、
+ *     offset 的 dx/dy）在当前 scope 局部度量后加到 referent 局部坐标上。
+ *   - **嵌套**：PolarPosition.origin / OffsetPosition.of 是嵌套 polar 时，递归调用传同样
+ *     scopeChain——整条嵌套链都在当前 scope 局部度量。
+ *   - **笛卡尔字面量**：`Position` 形态直接返回（v0.1 行为延续：scope 内笛卡尔字面量在
+ *     当前 scope 局部度量；调用方走 applyTransformChain 投全局）。
+ *   - 极坐标 origin / 偏移定位 of 均可递归引用节点 id 或字面坐标；relative `AtPosition` of
+ *     必须引用已定义节点/coordinate；解析失败返回 null。
+ *   - 节点 id lookup 走 NameStack.lookup 进行 inside-out 搜索（内层 frame 可见外层 frame）；
+ *     nodeDistance 为容器 prop 注入默认距离，AtPosition 自带 distance 优先
  */
-export declare const resolvePosition: (pos: IRPosition | PolarPosition | IRAtPosition | IROffsetPosition | string, nodeMap: Map<string, NodeLayout>, nodeDistance?: number) => IRPosition | null;
+export declare const resolvePosition: (pos: IRPosition | PolarPosition | IRAtPosition | IROffsetPosition | string, nameStack: NameStack, nodeDistance?: number, scopeChain?: ReadonlyArray<Transform>) => IRPosition | null;
 //# sourceMappingURL=position.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/compile/position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACpG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAoBzC;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,gBAAgB,GAAG,MAAM,EAC1E,SAAS,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAChC,eAAc,MAA8B,KAC3C,UAAU,GAAG,IAkCf,CAAC"}
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/compile/position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAqB9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,gBAAgB,GAAG,MAAM,EAC1E,WAAW,SAAS,EACpB,eAAc,MAA8B,EAC5C,aAAY,aAAa,CAAC,SAAS,CAAM,KACxC,UAAU,GAAG,IAyCf,CAAC"}

package/dist/es/compile/position.js

@@ -1,3 +1,4 @@
+import { inverseTransformChain } from "./scope.js";
 //#region src/compile/position.ts
 /** 默认相对定位距离（CompileOptions.nodeDistance 未配时使用） */
 var DEFAULT_NODE_DISTANCE = 1;
@@ -17,30 +18,49 @@ var DIRECTION_VECTOR = {
 };
 /**
 * IR 各种位置形态（笛卡尔/极坐标/相对定位/偏移定位/节点 id）→ 笛卡尔位置
-* @description 极坐标 origin / 偏移定位 of 均可递归引用节点 id 或字面坐标；relative `AtPosition` of 必须引用已定义节点/coordinate；解析失败返回 null。nodeDistance 为容器 prop 注入默认距离，AtPosition 自带 distance 优先
+* @description
+*   - **返回值语义**：当 `scopeChain` 非空时，返回**当前 scope 局部坐标系**下的笛卡尔位置；
+*     调用方负责走 `applyTransformChain(local, scopeChain)` 投回全局。当 `scopeChain` 为空时
+*     等价于 v0.1 行为（全局坐标）。
+*   - **referent 处理**：node id lookup 拿到的 layout.rect 已是全局坐标；本函数内部用
+*     `inverseTransformChain` 把全局 referent 反向投影到当前 scope 局部坐标系作为"在当前
+*     scope 局部的固定点"基准。relative 部分（polar 的 angle/radius、at 的 direction/distance、
+*     offset 的 dx/dy）在当前 scope 局部度量后加到 referent 局部坐标上。
+*   - **嵌套**：PolarPosition.origin / OffsetPosition.of 是嵌套 polar 时，递归调用传同样
+*     scopeChain——整条嵌套链都在当前 scope 局部度量。
+*   - **笛卡尔字面量**：`Position` 形态直接返回（v0.1 行为延续：scope 内笛卡尔字面量在
+*     当前 scope 局部度量；调用方走 applyTransformChain 投全局）。
+*   - 极坐标 origin / 偏移定位 of 均可递归引用节点 id 或字面坐标；relative `AtPosition` of
+*     必须引用已定义节点/coordinate；解析失败返回 null。
+*   - 节点 id lookup 走 NameStack.lookup 进行 inside-out 搜索（内层 frame 可见外层 frame）；
+*     nodeDistance 为容器 prop 注入默认距离，AtPosition 自带 distance 优先
 */
-var resolvePosition = (pos, nodeMap, nodeDistance = DEFAULT_NODE_DISTANCE) => {
+var resolvePosition = (pos, nameStack, nodeDistance = DEFAULT_NODE_DISTANCE, scopeChain = []) => {
 	if (typeof pos === "string") {
-		const node = nodeMap.get(pos);
-		return node ? [node.rect.x, node.rect.y] : null;
+		const node = nameStack.lookup(pos);
+		if (!node) return null;
+		const global = [node.rect.x, node.rect.y];
+		return scopeChain.length === 0 ? global : inverseTransformChain(global, scopeChain);
 	}
 	if (Array.isArray(pos)) return pos;
 	if ("direction" in pos) {
-		const ref = nodeMap.get(pos.of);
+		const ref = nameStack.lookup(pos.of);
 		if (!ref) return null;
+		const refGlobal = [ref.rect.x, ref.rect.y];
+		const refLocal = scopeChain.length === 0 ? refGlobal : inverseTransformChain(refGlobal, scopeChain);
 		const distance = pos.distance ?? nodeDistance;
 		const [dx, dy] = DIRECTION_VECTOR[pos.direction];
-		return [ref.rect.x + dx * distance, ref.rect.y + dy * distance];
+		return [refLocal[0] + dx * distance, refLocal[1] + dy * distance];
 	}
 	if ("offset" in pos) {
-		const base = resolvePosition(pos.of, nodeMap, nodeDistance);
+		const base = resolvePosition(pos.of, nameStack, nodeDistance, scopeChain);
 		if (!base) return null;
 		return [base[0] + pos.offset[0], base[1] + pos.offset[1]];
 	}
 	let origin;
 	if (!pos.origin) origin = [0, 0];
 	else {
-		const resolved = resolvePosition(pos.origin, nodeMap, nodeDistance);
+		const resolved = resolvePosition(pos.origin, nameStack, nodeDistance, scopeChain);
 		if (!resolved) return null;
 		origin = resolved;
 	}

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

@@ -0,0 +1,66 @@
+import { IRPosition, IRTransform } from '../ir';
+import { Transform } from '../primitive';
+import { NameStack } from './name-stack';
+import { NodeLayout } from './node';
+/**
+ * 把 IR 6 变体 transforms 展平为 Scene 3 变体（Cartesian translate / rotate / scale）
+ * @description 4 个 translate 变体（translate / polar-translate / at-translate / offset-translate）
+ *   各自构造对应 Position 字面量并调用 `resolvePosition` 拿到 Cartesian (x, y)，再写成 Cartesian translate；
+ *   rotate / scale 直接透传。referent 未解析时返回 null（上游负责发 warn / throw）
+ */
+export declare const lowerScopeTransforms: (transforms: ReadonlyArray<IRTransform>, nameStack: NameStack, nodeDistance?: number) => Array<Transform> | null;
+/**
+ * 把局部坐标点 (x, y) 按 Cartesian-only transform 链 apply 到全局坐标
+ * @description 数组语义与 SVG `transform="t0 t1 t2"` / TikZ scope option 顺序一致：
+ *   array[0] 是最外层（最后 apply 到 local），array[last] 是最内层（最先 apply）；
+ *   即对局部点 P，结果 = t0(t1(t2(P)))。实现上从数组尾部往头部迭代依次 apply。
+ *   只接受已被 `lowerScopeTransforms` 展平后的 3 变体（translate / rotate / scale）
+ */
+export declare const applyTransformChain: (local: IRPosition, chain: ReadonlyArray<Transform>) => IRPosition;
+/**
+ * 把全局坐标点反向投影回 scope 局部坐标系（`applyTransformChain` 的逆）
+ * @description chain = [t0, t1, t2]（array[0] 最外层、最后 apply）的逆 =
+ *   按数组正序应用每个 transform 的逆：t0^-1 / t1^-1 / t2^-1。
+ *   translate(-x, -y) / rotate(-deg, cx, cy) / scale(1/x, 1/y)。
+ *   scale 分量为 0 时反向投影未定义——退化为返回原点 (0, 0) 当前层，避免 NaN 污染下游。
+ *   作用：referent 全局点 → 当前 scope 局部坐标系，配合 `applyTransformChain` 实现
+ *   "referent 全局 + relative 部分在当前 scope 局部度量 + 末端正向投影回全局" 的语义。
+ */
+export declare const inverseTransformChain: (global: IRPosition, chain: ReadonlyArray<Transform>) => IRPosition;
+/**
+ * 复制 NodeLayout 并把 rect 中心点 + rotate + 尺寸全部按 scope transform chain 投到全局
+ * @description rect 中心走 `applyTransformChain`；chain 里的 rotate 累加到 `rect.rotate`（弧度）、
+ *   scale 乘进 rect.width / height / margin——这样 path 端点的 boundary clip 取的是与 SVG `<g>`
+ *   实际渲染一致的视觉尺寸 / 朝向，跨 / 入 / 出 rotate / scale scope 的 path 都贴节点视觉边界。
+ *   非均匀 scale 与 rotate 在 chain 中混合时，按"累加 rotate + 分量相乘 scale"近似（uniform scale 精确，
+ *   anisotropic + rotate 的剪切耦合不展开——alpha 阶段限制）。
+ */
+export declare const projectLayoutToGlobal: (layout: NodeLayout, chain: ReadonlyArray<Transform>) => NodeLayout;
+/** scope bbox 计算结果：bbox 几何中心 + 尺寸（width/height ≥ 0；空 scope 退化为 0×0 占位时仍合法） */
+export type ScopeBoundingBox = {
+    /** bbox 几何中心 x（全局坐标） */
+    x: number;
+    /** bbox 几何中心 y（全局坐标） */
+    y: number;
+    /** bbox 宽度（≥ 0；空 scope / 单点退化为 0） */
+    width: number;
+    /** bbox 高度（≥ 0；空 scope / 单点退化为 0） */
+    height: number;
+};
+/**
+ * 收集一组 NodeLayout 的全局 axis-aligned bounding box
+ * @description 每个 layout 的 4 角点已是全局坐标系（Pass 1 累积 chain apply 后），
+ *   取每个 layout 的 rotate-aware `north-west` / `north-east` / `south-west` / `south-east`
+ *   4 角点（rect.anchor 已含 layout.rect.rotate 处理）并求 AABB；
+ *   layout 是 0×0（coordinate / 空 scope 占位）时退化为单点也合法；
+ *   空 layouts 数组返回 null（调用方按"empty scope + fallback origin"退化为 0×0 占位）
+ */
+export declare const computeScopeBoundingBox: (layouts: ReadonlyArray<NodeLayout>) => ScopeBoundingBox | null;
+/**
+ * 用 scope id + bbox 构造 synthetic rectangle NodeLayout
+ * @description bbox 为 null 时退化为 fallbackOrigin 的 0×0 占位（空 scope 仍要有可引用句柄）。
+ *   synthetic layout 完全复用 rectangle 路径：`scope.id.<keyword>` / `scope.id.<deg>` / `scope.id` 作为 referent
+ *   走与普通 rectangle Node 完全一致的 anchorOf / boundaryPointOf / 中心点取值
+ */
+export declare const registerScopeAsLayout: (id: string, bbox: ScopeBoundingBox | null, fallbackOrigin: IRPosition) => NodeLayout;
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/compile/scope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EAEZ,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGzC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,aAAa,CAAC,WAAW,CAAC,EACtC,WAAW,SAAS,EACpB,eAAe,MAAM,KACpB,KAAK,CAAC,SAAS,CAAC,GAAG,IAiDrB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,UAAU,EACjB,OAAO,aAAa,CAAC,SAAS,CAAC,KAC9B,UAyBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,UAAU,EAClB,OAAO,aAAa,CAAC,SAAS,CAAC,KAC9B,UAgCF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,UAAU,EAClB,OAAO,aAAa,CAAC,SAAS,CAAC,KAC9B,UAuBF,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,wBAAwB;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,aAAa,CAAC,UAAU,CAAC,KACjC,gBAAgB,GAAG,IA2BrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,IAAI,MAAM,EACV,MAAM,gBAAgB,GAAG,IAAI,EAC7B,gBAAgB,UAAU,KACzB,UAeF,CAAC"}