@fulate/core 1.0.12 → 1.0.13

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { ChangeImpact, NodeProperties, resolveOrigin, TransformProperties } from
 export type { OriginX, OriginY, PropertyChanges, PropertyUpdates, TransformableOptions } from "./node/properties";
 export { Element, ElementProperties } from "./node/element";
 export type { AnyElement, BaseElementOption, ElementJSON, ElementOptionPatch, AnimateOptions, AnimateTarget } from "./node/element";
-export { isReparentTransformIntent, resolveAuthoredGeometryFramePatch, resolveReferenceTransform, resolveReferenceTransformTarget } from "./node/reference-transform";
+export { isReparentTransformIntent, resolveAuthoredGeometryFramePatch, resolveReferenceBoundsTranslation, resolveReferenceTransform, resolveReferenceTransformTarget } from "./node/reference-transform";
 export type { ElementTransformBaseline, ReferenceTransformBaseline, ReferenceTransformFrame, ReferenceTransformResolution, ReferenceTransformTarget, ReparentTransformIntent, TransformIntent } from "./node/reference-transform";
 export { DEFAULT_CONNECTION_PORT_SCHEMA, getElementConnectionPort, getElementConnectionPortPoint, getElementConnectionPortPoints, projectConnectionPortPoint } from "./utils/connection-port";
 export type { ConnectionPortId, ConnectionPortConfiguration, ConnectionPortDefinition, ConnectionPortLabelStyle, ConnectionPortDirection, ConnectionPortLimit, ConnectionPortLimits, ConnectionPortRef, DerivedConnectionPort, EdgeConnectionPortPosition, ResolvedConnectionPort, ResolvedConnectionPortSlot } from "./utils/connection-port";
@@ -25,6 +25,7 @@ export { FrameStabilizationError, RootFrameRuntime } from "./root/frame-runtime"
 export type { RootFrameCompletionWork, RootFrameLayoutOwner, RootFrameParticipant } from "./root/frame-runtime";
 export { SceneRegistry } from "./root/scene-registry";
 export type { NodeKeyObserver, NodeRegistrationObserver, SceneChangeObserver } from "./root/scene-registry";
+export { mergeOwnerPropertyChanges } from "./mutation/change-batch";
 export type { ChangeHistorySink, OwnerPropertyChange, StructureChange } from "./mutation/change-batch";
 export { Layer, LayerProperties, LayerTransform } from "./layer/index";
 export type { LayerFrameWork, LayerOption, LayerOptionPatch } from "./layer/index";

package/dist/index.js

@@ -3277,6 +3277,11 @@ var Element = class Element extends Node {
 	/** @internal 在全部 owner/tree 安装及 lifecycle 后运行 owner hook。 */
 	runPropertyCommitHook(commit) {
 		if (commit.update.changes.size) this.onPropertiesChanged(this.propertyState, commit.update.changes);
+		if (commit.update.source === "configured" && this.onConfiguredPropertiesChanged) {
+			const keys = [];
+			for (const field of commit.update.fields) if (field.sourceChanged) keys.push(field.key);
+			if (keys.length) this.onConfiguredPropertiesChanged(keys);
+		}
 	}
 	/** @internal 在 owner hook 后通知依赖实际 Ports commit 的框架消费者。 */
 	notifyPortsCommit(commit) {
@@ -3494,22 +3499,13 @@ var Element = class Element extends Node {
 			origin: "builtin"
 		};
 	}
-	/** @internal 按给定 whole-value 解析 Port replacement 的最终投影。 */
-	resolveConnectionPorts(ports) {
-		if (ports === false) return EMPTY_CONNECTION_PORTS;
-		if (ports !== true) return resolveConnectionPortSlots(this, ports);
-		return (this.getDefaultConnectionPortSchema() ?? DEFAULT_CONNECTION_PORT_SCHEMA).map((port) => ({
-			ref: {
-				elementKey: this.key,
-				portId: port.id
-			},
-			kind: "endpoint-binding",
-			localPosition: port.localPosition(this),
-			origin: "builtin"
-		}));
+	/** @internal 只解释显式 Port replacement 的 IDs；patch 是同批最终 owner fields。 */
+	resolveConnectionPortIds(ports, patch) {
+		if (ports === false) return [];
+		return (ports === true ? this.getDefaultConnectionPortSchema(patch) ?? DEFAULT_CONNECTION_PORT_SCHEMA : ports).map(({ id }) => id);
 	}
 	/** 返回元素类型自有的默认 Port；`null` 使用通用四边 Ports。 */
-	getDefaultConnectionPortSchema() {
+	getDefaultConnectionPortSchema(_patch) {
 		return null;
 	}
 	/** 返回 custom Ports 的当前 decoration slots。 @internal */
@@ -3552,11 +3548,18 @@ var Element = class Element extends Node {
 			edgeLength: edge === "top" || edge === "bottom" ? Math.abs(this.width ?? 0) : Math.abs(this.height ?? 0)
 		};
 	}
-	/** @internal 一次借用 owner 当前 configured source 的指定字段。 */
+	/**
+	* 将当前配置值填入 caller 提供的 value cells，保留结构化值的原引用。
+	* 读取包含默认值的 configured 结果，不读取 runtime 覆盖；保留 null/undefined。
+	* cells 可复用；借用值不得原地修改并期待自动提交，需要独立值时由 caller 复制。
+	*/
 	static readConfiguredPropertyValues(owner, targets) {
 		readConfiguredPropertyValues(owner.propertyState, targets);
 	}
-	/** @internal 借用 owner 当前 configured source 的单个字段。 */
+	/**
+	* 借用当前字段的 configured/default 值，忽略 runtime 覆盖，保留 null/undefined。
+	* 返回结构化原引用，不表示该字段是否曾被显式配置；需要独立值时由 caller 复制。
+	*/
 	static getConfiguredPropertyValue(owner, key) {
 		return getConfiguredPropertyValue(owner.propertyState, key);
 	}
@@ -3804,19 +3807,31 @@ function resolveBakedAuthoredGeometryTransform(baseline, target) {
 function resolveAuthoredGeometryFramePatch(baseline, resolution, authoredBounds) {
 	if (isIdentityMatrix(resolution.authoredLocalDelta)) return resolution.framePatch;
 	const approximateBounds = transformReferenceBounds(baseline.referenceBounds, resolution.authoredLocalDelta);
-	const originX = resolveOrigin(baseline.frame.originX) + .5;
-	const originY = resolveOrigin(baseline.frame.originY) + .5;
-	const approximateOffsetX = approximateBounds.left + originX * approximateBounds.width;
-	const approximateOffsetY = approximateBounds.top + originY * approximateBounds.height;
-	const authoredOffsetX = authoredBounds.left + originX * authoredBounds.width;
-	const authoredOffsetY = authoredBounds.top + originY * authoredBounds.height;
-	const deltaX = authoredOffsetX - approximateOffsetX;
-	const deltaY = authoredOffsetY - approximateOffsetY;
-	const frameLinear = createFrameLinearMatrix(baseline.frame);
 	return {
 		...resolution.framePatch,
-		left: (resolution.framePatch.left ?? baseline.frame.left) + -deltaX + frameLinear.a * deltaX + frameLinear.c * deltaY,
-		top: (resolution.framePatch.top ?? baseline.frame.top) + -deltaY + frameLinear.b * deltaX + frameLinear.d * deltaY
+		...resolveReferenceBoundsTranslation({
+			...baseline.frame,
+			...resolution.framePatch
+		}, approximateBounds, authoredBounds)
+	};
+}
+/** @internal reference bounds 改变时修正 origin 位移，保留给定最终 frame 的仿射。 */
+function resolveReferenceBoundsTranslation(frame, before, after) {
+	const { left = 0, top = 0, angle = 0, skewX = 0, skewY = 0, scaleX = 1, scaleY = 1, originX = "center", originY = "center" } = frame;
+	const x = resolveOrigin(originX) + .5;
+	const y = resolveOrigin(originY) + .5;
+	const deltaX = after.left + x * after.width - before.left - x * before.width;
+	const deltaY = after.top + y * after.height - before.top - y * before.height;
+	const linear = createFrameLinearMatrix({
+		angle,
+		skewX,
+		skewY,
+		scaleX,
+		scaleY
+	});
+	return {
+		left: left - deltaX + linear.a * deltaX + linear.c * deltaY,
+		top: top - deltaY + linear.b * deltaX + linear.d * deltaY
 	};
 }
 /** 判断变换意图是否包含跨父级重挂载所需的目标父级矩阵。 */
@@ -4496,14 +4511,14 @@ var RootInputController = class {
 	isPanning = false;
 	/** @internal 是否应在连续指针操作期间暂停 hover 重算。 */
 	hasLockPoint = false;
-	/** @internal 最近一次 DOM 指针的 clientX/clientY，不是 world 坐标。 */
-	lastPointerPos = {
+	/** Input 原地更新的唯一 client 坐标。 */
+	pointerPosition = {
 		x: 0,
 		y: 0
 	};
 	/** 最近一次记录的指针是否位于 Root 容器内。 */
 	pointerInside = false;
-	/** 当前允许接收元素级输入的工具子树根节点。 */
+	/** 当前允许接收元素级指针输入的子树根节点。 */
 	interactionScopes = /* @__PURE__ */ new Set();
 	/** 一次 Root 激活周期内全部 DOM listener 的统一清理器。 */
 	abortController = null;
@@ -4517,7 +4532,11 @@ var RootInputController = class {
 	constructor(root) {
 		this.root = root;
 	}
-	/** @internal Root 当前是否认为指针位于容器内。 */
+	/** 最近一次 DOM 指针的 clientX/clientY 只读借用；后续输入原地更新同一对象。 */
+	get lastPointerPos() {
+		return this.pointerPosition;
+	}
+	/** Root 当前是否认为指针位于容器内。 */
 	get isPointerInside() {
 		return this.pointerInside;
 	}
@@ -4563,7 +4582,16 @@ var RootInputController = class {
 		this.deactivate();
 		this.interactionScopes.clear();
 	}
-	/** @internal 取消全部指针会话，或仅取消目标位于指定节点子树的场景会话。 */
+	/**
+	* 取消当前指针操作，释放指针捕获与 hover 锁定，并清除连续点击记录。
+	*
+	* 省略 node 时取消当前场景或空格平移操作。传入所属 Root 内的节点时，
+	* 仅取消按下目标为该节点或其后代的场景操作；空白处以 Root 为目标的操作、
+	* 空格平移和其他子树的操作不受影响。
+	*
+	* 场景操作按当前交互范围派发一次 pointercancel，不产生 pointerup 或 click；
+	* 平移操作只释放输入状态，保留已经发生的 Viewport 平移。
+	*/
 	cancelSession(node) {
 		if (!node) {
 			this.cancelPointerSession();
@@ -4584,7 +4612,17 @@ var RootInputController = class {
 	setPointerInside(inside) {
 		this.pointerInside = inside;
 	}
-	/** @internal 注册工具交互范围，只让其子树接收元素级输入，并返回注销函数。 */
+	/**
+	* 允许所属 Root 内的 scope 及其后代接收元素级指针输入，返回注销函数。
+	*
+	* 多个范围取并集；没有范围时恢复普通派发。范围外的命中仍作为事件 target
+	* 派给 Root，但不进入命中元素的指针、点击、悬停或右键处理器。
+	* wheel 仍派给命中元素；范围内事件保留正常冒泡，范围不改变命中查询结果。
+	*
+	* 调用方负责每个 scope 同时只保留一次注册，并在退出交互或停用时注销；
+	* 再次进入时重新注册。注册和注销通过现有帧队列刷新 hover 与 cursor，
+	* 不自动取消进行中的指针操作；需要取消时调用 cancelSession(scope)。
+	*/
 	registerInteractionScope(scope) {
 		this.interactionScopes.add(scope);
 		this.root.scheduleHoverRefresh();
@@ -4593,7 +4631,7 @@ var RootInputController = class {
 			this.root.scheduleHoverRefresh();
 		};
 	}
-	/** @internal 判断命中元素是否属于当前任一 interaction scope。 */
+	/** 判断元素是否属于当前允许交互的子树；无范围限制时为 true，不执行命中或焦点查询。 */
 	isInteractionTarget(element) {
 		if (this.interactionScopes.size === 0) return true;
 		for (let node = element; node; node = node.parent) if (node instanceof Element && this.interactionScopes.has(node)) return true;
@@ -4613,8 +4651,8 @@ var RootInputController = class {
 	}
 	/** 保存 DOM client 坐标，供无显式事件的 hover 重算使用。 */
 	updatePointer(event) {
-		this.lastPointerPos.x = event.clientX;
-		this.lastPointerPos.y = event.clientY;
+		this.pointerPosition.x = event.clientX;
+		this.pointerPosition.y = event.clientY;
 	}
 	/** 将一个 DOM 输入转换为 Fulate world 事件并派给当前场景目标。 */
 	dispatchDomEvent(event, eventName, target = this.root.currentElement, point = this.root.viewport.getLogicalPosition(event.clientX, event.clientY)) {
@@ -5565,11 +5603,21 @@ var SceneRegistry = class {
 	sceneChangeObservers = /* @__PURE__ */ new Set();
 	/** 监听 active registration 的轻量观察器。 */
 	nodeRegistrationObservers = /* @__PURE__ */ new Set();
-	/** 创建注册表；可注入已有 Map 以共享或测试已经成立的 key 索引。 */
-	constructor(keyElements = /* @__PURE__ */ new Map()) {
-		this.keyElements = keyElements;
+	/** @internal 由 Root 创建，拥有当前场景唯一 key 索引。 */
+	constructor(nodes = /* @__PURE__ */ new Map()) {
+		this.nodes = nodes;
 	}
-	/** 订阅场景变化并返回注销函数。 */
+	/**
+	* 当前 active 节点的只读 live 索引；与内部 Map 为同一引用，不创建快照。
+	* 初始枚举后可订阅增量变化，后续注册/注销会直接更新此视图。
+	*/
+	get keyElements() {
+		return this.nodes;
+	}
+	/**
+	* 订阅后续场景查询/结构变化，返回退订函数；不补发当前状态。
+	* 此通知不代表完整属性变化或帧已稳定；Root 销毁时清除订阅。
+	*/
 	observeSceneChanges(observer) {
 		this.sceneChangeObservers.add(observer);
 		return () => this.sceneChangeObservers.delete(observer);
@@ -5578,7 +5626,11 @@ var SceneRegistry = class {
 	get hasSceneChangeObservers() {
 		return this.sceneChangeObservers.size > 0;
 	}
-	/** 订阅节点 active registration 并返回注销函数。 */
+	/**
+	* 订阅后续节点进入/离开 active 生命周期，返回退订函数；不补发已有节点。
+	* 回调时索引与 active 状态已安装；detach/reinsert 分别通知 false/true。
+	* Root 销毁时清除订阅。
+	*/
 	observeNodeRegistrations(observer) {
 		this.nodeRegistrationObservers.add(observer);
 		return () => this.nodeRegistrationObservers.delete(observer);
@@ -5621,13 +5673,13 @@ var SceneRegistry = class {
 		const key = node.key;
 		const existing = this.keyElements.get(key);
 		if (existing && existing !== node) console.warn(`Duplicate node key: "${key}"`);
-		this.keyElements.set(key, node);
+		this.nodes.set(key, node);
 	}
 	/** @internal 从索引移除停用节点并通知 key 观察器。 */
 	unregisterNodeKey(node) {
 		const key = node.key;
 		if (this.keyElements.get(key) === node) {
-			this.keyElements.delete(key);
+			this.nodes.delete(key);
 			this.notifyNodeKeyObservers(key, node, false);
 		}
 		this.notifyNodeRegistrationObservers(node, false);
@@ -5645,7 +5697,7 @@ var SceneRegistry = class {
 	}
 	/** @internal 清空 key 索引和全部观察器。 */
 	clear() {
-		this.keyElements.clear();
+		this.nodes.clear();
 		this.nodeKeyObservers.clear();
 		this.nodeRegistrationObservers.clear();
 		this.sceneChangeObservers.clear();
@@ -5745,15 +5797,8 @@ function syncStructureLifecycles(nodes) {
 }
 //#endregion
 //#region packages/core/src/mutation/change-batch.ts
-/**
-* 同步应用一份 trusted change batch。
-*
-* owner effects 先按对象身份合并最终 patch；所有 fields/raw links 安装完成后才运行
-* History、lifecycle、hooks、dirty 和一次 scene delivery。本函数不提供 rollback、
-* retry、receipt 或 rejected 结果。
-*/
-function applyChangeBatch(root, ownerEffects, structureEffects = [], history) {
-	if (ownerEffects.length === 0 && structureEffects.length === 0) return;
+/** @internal 合并 raw owner effects；单个 patch 直接借用，仅合并同 owner 字段时分配。 */
+function mergeOwnerPropertyChanges(ownerEffects) {
 	const slots = /* @__PURE__ */ new Map();
 	let mergedOwners = null;
 	for (const { owner, patch } of ownerEffects) {
@@ -5772,6 +5817,18 @@ function applyChangeBatch(root, ownerEffects, structureEffects = [], history) {
 		}
 		for (const key of Object.keys(patch)) finalPatch[key] = patch[key];
 	}
+	return slots;
+}
+/**
+* 同步应用一份 trusted change batch。
+*
+* owner effects 先按对象身份合并最终 patch；所有 fields/raw links 安装完成后才运行
+* History、lifecycle、hooks、dirty 和一次 scene delivery。本函数不提供 rollback、
+* retry、receipt 或 rejected 结果。返回本批次是否实际安装属性或结构变化。
+*/
+function applyChangeBatch(root, ownerEffects, structureEffects = [], history) {
+	if (ownerEffects.length === 0 && structureEffects.length === 0) return false;
+	const slots = mergeOwnerPropertyChanges(ownerEffects);
 	const properties = [];
 	for (const [owner, patch] of slots) {
 		const commit = owner.preparePropertyCommit(patch);
@@ -5782,7 +5839,7 @@ function applyChangeBatch(root, ownerEffects, structureEffects = [], history) {
 	}
 	const structureBatch = prepareStructureBatch(structureEffects);
 	const structure = structureBatch.changes;
-	if (properties.length === 0 && structure.length === 0) return;
+	if (properties.length === 0 && structure.length === 0) return false;
 	const placements = history ? preparePlacementChanges(structure) : null;
 	for (const { owner, commit } of properties) owner.installPropertyCommit(commit);
 	const lifecycleRoots = installStructureLinks(structureBatch);
@@ -5811,6 +5868,7 @@ function applyChangeBatch(root, ownerEffects, structureEffects = [], history) {
 	else if (hoverChanged) root.scheduleHoverRefresh();
 	if (root.sceneRegistry.hasSceneChangeObservers) root.sceneRegistry.notifySceneChange(void 0, [...properties.map(({ owner }) => owner), ...structure.flatMap(({ owner, changed }) => [owner, ...changed])]);
 	for (const { owner, commit } of properties) owner.dispatchPortsChange(commit);
+	return true;
 }
 //#endregion
 //#region packages/core/src/root/index.ts
@@ -5826,9 +5884,9 @@ var Root = class extends Node {
 	skinTextCommitObservers;
 	/** Root 的平移、缩放、DPR 和坐标换算对象。 */
 	viewport;
-	/** @internal Root 拥有的 DOM 输入和指针会话控制器。 */
+	/** Root 拥有的输入控制器，提供只读查询、交互范围注册和指针操作取消。 */
 	input;
-	/** @internal 活动节点 key 索引和场景变化观察器。 */
+	/** 当前活动节点的只读索引及增量场景订阅。 */
 	sceneRegistry;
 	/** @internal 跨 Layer 帧队列、动画时钟和 nextTick 状态。 */
 	frameRuntime;
@@ -6057,7 +6115,7 @@ var Root = class extends Node {
 	* 同 owner 只 finalize/install 一次，全部 fields/raw links 安装后统一发布。
 	*/
 	applyChangeBatch(owners, structure = [], history) {
-		applyChangeBatch(this, owners, structure, history);
+		return applyChangeBatch(this, owners, structure, history);
 	}
 	/** 按活动场景中的唯一 key 查询节点；key 来自 `node.key`。 */
 	getByKey(key) {
@@ -6940,4 +6998,4 @@ var Layer = class Layer extends Element {
 	}
 };
 //#endregion
-export { ChangeImpact, CustomEvent, DEFAULT_CONNECTION_PORT_SCHEMA, EVENT_NAMES, Element, ElementProperties, ElementTransform, EventEmitter, FrameStabilizationError, Layer, LayerProperties, LayerTransform, Node, NodeLifecycleEvent, NodeProperties, Root, RootFrameRuntime, RootInputController, SKIN_DEFAULTS, SceneRegistry, Shape, ShapeProperties, ShapeTransform, Skin, TransformProperties, Viewport, createAuthoredLineSubpath, createGeometryQuery, createGeometrySnapshot, createLineSubpath, createPathLocalId, evaluatePathSegmentPoint, getElementConnectionPort, getElementConnectionPortPoint, getElementConnectionPortPoints, isFormControlTarget, isReparentTransformIntent, projectConnectionPortPoint, resolveAuthoredGeometryFramePatch, resolveAuthoredSubpath, resolveOrigin, resolveReferenceTransform, resolveReferenceTransformTarget, splitPathSegment };
+export { ChangeImpact, CustomEvent, DEFAULT_CONNECTION_PORT_SCHEMA, EVENT_NAMES, Element, ElementProperties, ElementTransform, EventEmitter, FrameStabilizationError, Layer, LayerProperties, LayerTransform, Node, NodeLifecycleEvent, NodeProperties, Root, RootFrameRuntime, RootInputController, SKIN_DEFAULTS, SceneRegistry, Shape, ShapeProperties, ShapeTransform, Skin, TransformProperties, Viewport, createAuthoredLineSubpath, createGeometryQuery, createGeometrySnapshot, createLineSubpath, createPathLocalId, evaluatePathSegmentPoint, getElementConnectionPort, getElementConnectionPortPoint, getElementConnectionPortPoints, isFormControlTarget, isReparentTransformIntent, mergeOwnerPropertyChanges, projectConnectionPortPoint, resolveAuthoredGeometryFramePatch, resolveAuthoredSubpath, resolveOrigin, resolveReferenceBoundsTranslation, resolveReferenceTransform, resolveReferenceTransformTarget, splitPathSegment };

package/dist/mutation/change-batch.d.ts

@@ -18,12 +18,14 @@ export interface ChangeHistorySink {
     /** 记录一个节点首次触及批次提供的 before placement。 */
     recordPlacementChange(node: Node, beforeOwner: Node | null, beforeIndex: number): void;
 }
+/** @internal 合并 raw owner effects；单个 patch 直接借用，仅合并同 owner 字段时分配。 */
+export declare function mergeOwnerPropertyChanges(ownerEffects: readonly OwnerPropertyChange[]): Map<Element<import("..").ElementProperties, import("..").BaseElementOption<any>, Partial<Omit<import("..").BaseElementOption<any>, "key" | "children">>>, Readonly<Record<string, unknown>>>;
 /**
  * 同步应用一份 trusted change batch。
  *
  * owner effects 先按对象身份合并最终 patch；所有 fields/raw links 安装完成后才运行
  * History、lifecycle、hooks、dirty 和一次 scene delivery。本函数不提供 rollback、
- * retry、receipt 或 rejected 结果。
+ * retry、receipt 或 rejected 结果。返回本批次是否实际安装属性或结构变化。
  */
-export declare function applyChangeBatch(root: Root, ownerEffects: readonly OwnerPropertyChange[], structureEffects?: readonly StructureChange[], history?: ChangeHistorySink): void;
+export declare function applyChangeBatch(root: Root, ownerEffects: readonly OwnerPropertyChange[], structureEffects?: readonly StructureChange[], history?: ChangeHistorySink): boolean;
 export type { StructureChange } from "./structure-change";

package/dist/node/element.d.ts

@@ -218,6 +218,13 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
     private syncOptionEvents;
     /** 属性提交后的派生类扩展点。 */
     protected onPropertiesChanged(_current: P, _changes: PropertyChanges): void;
+    /**
+     * 作者配置实际变化后的扩展点，在 effective 属性 hook 之后运行。
+     * runtime 遮罩不阻止此通知；runtime-only 更新和相同配置不触发。
+     * changedKeys 只包含本次实际改变的 configured 字段；通过 configured reader 读取当前值。
+     * direct、batch 和 History replay 使用同一阶段；可在此更新当前数据的 runtime 显示。
+     */
+    protected onConfiguredPropertiesChanged?(changedKeys: readonly string[]): void;
     /** 把非 geometry impact 路由到绘制、Layer 顺序和 hover 队列。 */
     private invalidate;
     /** 返回在当前元素 local 坐标系中对 children 生效的裁剪区域。 */
@@ -239,10 +246,10 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
     private resolveCurrentConnectionPortProjection;
     /** 直接解析一个当前 Port，不 materialize 其余 Ports。 */
     getConnectionPort(portId: string): ResolvedConnectionPort | undefined;
-    /** @internal 按给定 whole-value 解析 Port replacement 的最终投影。 */
-    resolveConnectionPorts(ports: ConnectionPortConfiguration): readonly ResolvedConnectionPort[];
+    /** @internal 只解释显式 Port replacement 的 IDs；patch 是同批最终 owner fields。 */
+    resolveConnectionPortIds(ports: ConnectionPortConfiguration, patch?: Readonly<Record<string, unknown>>): readonly string[];
     /** 返回元素类型自有的默认 Port；`null` 使用通用四边 Ports。 */
-    protected getDefaultConnectionPortSchema(): readonly DerivedConnectionPort[] | null;
+    protected getDefaultConnectionPortSchema(_patch?: Readonly<Record<string, unknown>>): readonly DerivedConnectionPort[] | null;
     /** 返回 custom Ports 的当前 decoration slots。 @internal */
     getResolvedConnectionPortSlots(): readonly ResolvedConnectionPortSlot[];
     /**
@@ -253,12 +260,19 @@ export declare class Element<P extends ElementProperties = ElementProperties, O
     getConnectionPortPosition(edge: Edge, ratio: number): PointView;
     /** @internal 一次产出 custom Port position、法线与 label edge 长度。 */
     getConnectionPortGeometry(edge: Edge, ratio: number): ConnectionPortGeometry;
-    /** @internal 一次借用 owner 当前 configured source 的指定字段。 */
+    /**
+     * 将当前配置值填入 caller 提供的 value cells，保留结构化值的原引用。
+     * 读取包含默认值的 configured 结果，不读取 runtime 覆盖；保留 null/undefined。
+     * cells 可复用；借用值不得原地修改并期待自动提交，需要独立值时由 caller 复制。
+     */
     static readConfiguredPropertyValues(owner: Element, targets: ReadonlyMap<string, {
         value: unknown;
     }>): void;
-    /** @internal 借用 owner 当前 configured source 的单个字段。 */
-    protected static getConfiguredPropertyValue(owner: Element, key: string): any;
+    /**
+     * 借用当前字段的 configured/default 值，忽略 runtime 覆盖，保留 null/undefined。
+     * 返回结构化原引用，不表示该字段是否曾被显式配置；需要独立值时由 caller 复制。
+     */
+    static getConfiguredPropertyValue(owner: Element, key: string): unknown;
     /**
      * 提交需要持久化的配置属性补丁。
      * @param options 要修改的属性；省略时不修改，字段为 `undefined` 时恢复默认值。

package/dist/node/reference-transform.d.ts

@@ -61,6 +61,8 @@ export interface ReferenceTransformResolution {
  * 新几何后把真实 bounds 交回这里，保持 frame world matrix 与目标一致。
  */
 export declare function resolveAuthoredGeometryFramePatch(baseline: Readonly<Pick<ReferenceTransformBaseline, "referenceBounds" | "frame">>, resolution: Readonly<ReferenceTransformResolution>, authoredBounds: Readonly<Rect>): Readonly<ElementOptionPatch>;
+/** @internal reference bounds 改变时修正 origin 位移，保留给定最终 frame 的仿射。 */
+export declare function resolveReferenceBoundsTranslation(frame: Readonly<ElementOptionPatch>, before: Readonly<Rect>, after: Readonly<Rect>): Readonly<Pick<ElementOptionPatch, "left" | "top">>;
 /** 判断变换意图是否包含跨父级重挂载所需的目标父级矩阵。 */
 export declare function isReparentTransformIntent(intent: Readonly<TransformIntent | ReparentTransformIntent>): intent is Readonly<ReparentTransformIntent>;
 /**

package/dist/root/index.d.ts

@@ -30,9 +30,9 @@ export declare class Root extends Node<NodeProperties, Layer> {
     private skinTextCommitObservers?;
     /** Root 的平移、缩放、DPR 和坐标换算对象。 */
     readonly viewport: Viewport;
-    /** @internal Root 拥有的 DOM 输入和指针会话控制器。 */
+    /** Root 拥有的输入控制器，提供只读查询、交互范围注册和指针操作取消。 */
     readonly input: RootInputController;
-    /** @internal 活动节点 key 索引和场景变化观察器。 */
+    /** 当前活动节点的只读索引及增量场景订阅。 */
     readonly sceneRegistry: SceneRegistry;
     /** @internal 跨 Layer 帧队列、动画时钟和 nextTick 状态。 */
     readonly frameRuntime: RootFrameRuntime;
@@ -133,7 +133,7 @@ export declare class Root extends Node<NodeProperties, Layer> {
      * 同步应用领域已经决定的 owner/structure effects。
      * 同 owner 只 finalize/install 一次，全部 fields/raw links 安装后统一发布。
      */
-    applyChangeBatch(owners: readonly OwnerPropertyChange[], structure?: readonly StructureChange[], history?: ChangeHistorySink): void;
+    applyChangeBatch(owners: readonly OwnerPropertyChange[], structure?: readonly StructureChange[], history?: ChangeHistorySink): boolean;
     /** 按活动场景中的唯一 key 查询节点；key 来自 `node.key`。 */
     getByKey(key: string): Node | undefined;
     /**

package/dist/root/input-controller.d.ts

@@ -1,7 +1,7 @@
 import { Element } from "../node/element";
 import type { Node as SceneNode } from "../node/node";
 import type { Root } from "./index";
-import type { MutablePointView } from "@fulate/share";
+import type { PointView } from "@fulate/share";
 /** 判断键盘事件目标是否应保留浏览器原生空格输入。 */
 export declare function isFormControlTarget(target: EventTarget | null): boolean;
 /** Root 拥有的 DOM 输入监听、指针会话和交互范围控制器。 */
@@ -13,11 +13,11 @@ export declare class RootInputController {
     isPanning: boolean;
     /** @internal 是否应在连续指针操作期间暂停 hover 重算。 */
     hasLockPoint: boolean;
-    /** @internal 最近一次 DOM 指针的 clientX/clientY，不是 world 坐标。 */
-    lastPointerPos: MutablePointView;
+    /** Input 原地更新的唯一 client 坐标。 */
+    private readonly pointerPosition;
     /** 最近一次记录的指针是否位于 Root 容器内。 */
     private pointerInside;
-    /** 当前允许接收元素级输入的工具子树根节点。 */
+    /** 当前允许接收元素级指针输入的子树根节点。 */
     private readonly interactionScopes;
     /** 一次 Root 激活周期内全部 DOM listener 的统一清理器。 */
     private abortController;
@@ -29,7 +29,9 @@ export declare class RootInputController {
     private lastClick;
     /** @internal 由 Root 构造；单独实例化不会接入 Root 生命周期。 */
     constructor(root: Root);
-    /** @internal Root 当前是否认为指针位于容器内。 */
+    /** 最近一次 DOM 指针的 clientX/clientY 只读借用；后续输入原地更新同一对象。 */
+    get lastPointerPos(): PointView;
+    /** Root 当前是否认为指针位于容器内。 */
     get isPointerInside(): boolean;
     /** @internal 安装当前 Root 的键盘、指针、滚轮和焦点监听。 */
     activate(): void;
@@ -37,13 +39,32 @@ export declare class RootInputController {
     deactivate(): void;
     /** @internal 停用控制器并释放全部 interaction scope。 */
     dispose(): void;
-    /** @internal 取消全部指针会话，或仅取消目标位于指定节点子树的场景会话。 */
+    /**
+     * 取消当前指针操作，释放指针捕获与 hover 锁定，并清除连续点击记录。
+     *
+     * 省略 node 时取消当前场景或空格平移操作。传入所属 Root 内的节点时，
+     * 仅取消按下目标为该节点或其后代的场景操作；空白处以 Root 为目标的操作、
+     * 空格平移和其他子树的操作不受影响。
+     *
+     * 场景操作按当前交互范围派发一次 pointercancel，不产生 pointerup 或 click；
+     * 平移操作只释放输入状态，保留已经发生的 Viewport 平移。
+     */
     cancelSession(node?: SceneNode): void;
     /** @internal 更新容器内外状态。 */
     setPointerInside(inside: boolean): void;
-    /** @internal 注册工具交互范围，只让其子树接收元素级输入，并返回注销函数。 */
+    /**
+     * 允许所属 Root 内的 scope 及其后代接收元素级指针输入，返回注销函数。
+     *
+     * 多个范围取并集；没有范围时恢复普通派发。范围外的命中仍作为事件 target
+     * 派给 Root，但不进入命中元素的指针、点击、悬停或右键处理器。
+     * wheel 仍派给命中元素；范围内事件保留正常冒泡，范围不改变命中查询结果。
+     *
+     * 调用方负责每个 scope 同时只保留一次注册，并在退出交互或停用时注销；
+     * 再次进入时重新注册。注册和注销通过现有帧队列刷新 hover 与 cursor，
+     * 不自动取消进行中的指针操作；需要取消时调用 cancelSession(scope)。
+     */
     registerInteractionScope(scope: Element): () => void;
-    /** @internal 判断命中元素是否属于当前任一 interaction scope。 */
+    /** 判断元素是否属于当前允许交互的子树；无范围限制时为 true，不执行命中或焦点查询。 */
     isInteractionTarget(element: Element): boolean;
     /** Root 容器所属的 Document。 */
     private get ownerDocument();

package/dist/root/scene-registry.d.ts

@@ -7,23 +7,32 @@ export type NodeRegistrationObserver = (node: Node, registered: boolean) => void
 export type SceneChangeObserver = (node?: Node, affected?: readonly Node[]) => void;
 /** 管理活动场景的节点 key 索引和轻量变化观察器。 */
 export declare class SceneRegistry {
-    /** 活动节点的 key 索引。 */
-    readonly keyElements: Map<string, Node<import("..").NodeProperties, Node<any, any>>>;
+    private readonly nodes;
     /** 按 key 保存观察注册和注销的回调。 */
     private readonly nodeKeyObservers;
     /** 监听结构、geometry 和命中策略变化的回调。 */
     private readonly sceneChangeObservers;
     /** 监听 active registration 的轻量观察器。 */
     private readonly nodeRegistrationObservers;
-    /** 创建注册表；可注入已有 Map 以共享或测试已经成立的 key 索引。 */
-    constructor(
-    /** 活动节点的 key 索引。 */
-    keyElements?: Map<string, Node<import("..").NodeProperties, Node<any, any>>>);
-    /** 订阅场景变化并返回注销函数。 */
+    /** @internal 由 Root 创建，拥有当前场景唯一 key 索引。 */
+    constructor(nodes?: Map<string, Node<import("..").NodeProperties, Node<any, any>>>);
+    /**
+     * 当前 active 节点的只读 live 索引；与内部 Map 为同一引用，不创建快照。
+     * 初始枚举后可订阅增量变化，后续注册/注销会直接更新此视图。
+     */
+    get keyElements(): ReadonlyMap<string, Node>;
+    /**
+     * 订阅后续场景查询/结构变化，返回退订函数；不补发当前状态。
+     * 此通知不代表完整属性变化或帧已稳定；Root 销毁时清除订阅。
+     */
     observeSceneChanges(observer: SceneChangeObserver): () => boolean;
     /** @internal 当前是否存在真实 scene change consumer。 */
     get hasSceneChangeObservers(): boolean;
-    /** 订阅节点 active registration 并返回注销函数。 */
+    /**
+     * 订阅后续节点进入/离开 active 生命周期，返回退订函数；不补发已有节点。
+     * 回调时索引与 active 状态已安装；detach/reinsert 分别通知 false/true。
+     * Root 销毁时清除订阅。
+     */
     observeNodeRegistrations(observer: NodeRegistrationObserver): () => boolean;
     /** @internal 通知场景观察器；node 省略时表示整批变化。 */
     notifySceneChange(node?: Node, affected?: readonly Node[]): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulate/core",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",