@fulate/tools 1.0.11 → 1.0.13

package/README.md

@@ -1,4 +1,6 @@
-# @fulate/tools Editor integration
+# @fulate/tools Editor integration
+
+> 文档角色：`GUIDE`。说明当前 Tools 用法；Editor 时序的唯一合同见 [Editor 规范](../../docs/specs/editor-interaction.md)。
 
 每个活动 Root 只有一个 `EditorInteractionController`。它拥有 selection、输入仲裁、Transform/Point
 gesture、Content session、Line/LineTree branch draft 与 semantic History 边界；`Select` 只保留 command/paint
@@ -130,7 +132,51 @@ History 安装后排队一次 `select:configured-change` 通知；标量 noop
 width/height/x/y 仍使用 `Select.resize()` 或其他 Transform 命令，不能用普通 authored patch 绕过
 父级矩阵反算。
 
-`Select.resize()` 是属性面板使用的公开尺寸命令：
+### 应用组合命令
+
+不同 owner 的属性和结构组合使用 `select.applyCommand(createCommand)`。构造函数在旧交互结束、
+pending 几何稳定后同步运行，参数是当时的 live selection，返回公开的 `SelectCommand`：
+
+```ts
+const changed = select.applyCommand(() => ({
+  ownerChanges: [{ owner: workspace, patch: { backgroundColor: "#ffffff" } }],
+  recordHistory: false
+}));
+
+select.applyCommand(() => ({
+  structureChanges: [{ owner: layer, children: [...layer.children, newShape] }],
+  selectionAfter: [newShape],
+  afterInstall: () => attachApplicationData(newShape)
+}));
+```
+
+`recordHistory: false` 只关闭本命令的记录；默认仍服从 `select.history.enabled`。返回值只表示本命令
+Canvas configured 属性或结构的实际净变化，与 History、监听器是否开启无关。已有拖拽完成和随后命令
+是两个操作，各自有适用的 History/配置通知；本命令 noop 不撤销前一个操作。
+
+`selectionAfter` 省略时保留当前选择意图；结构提交后过滤已移除节点和被选中祖先覆盖的元素，成员未变
+时保留当前 Point 等选择状态。`[]` 清空。显式选择结果或实际选择修复排队一次 `select:end`；
+仅选择变化返回 false，不生成 History/配置通知。构造返回 undefined、空命令、相同值
+和同 owner 最终覆盖回原值都是普通 noop，`afterInstall` 不运行。
+
+`afterInstall` 位于 Core 字段/结构、lifecycle、hook、scene observers 及选择安装之后，frame drain、
+History finish 和排队配置完成通知之前。它只在实际 Scene 安装后同步调用一次，不随 undo/redo 重放；
+应用自己的数据对应关系仍由自己的注册/清理链维护。回调异常直接传播，已安装的正常变化保留。
+构造阶段销毁 Select/Root 时停止本命令；安装后销毁则保留已安装变化并停止旧 controller 的后续完成。
+
+命令 caller 不需要 prepare 属性、操作 History scope 或驱动帧。只需单独结束当前交互时使用
+`select.finishCurrentInteraction()`：完成已接受交互，取消尚未提交的画线草稿，无活动交互时无操作。
+
+需要当前 Workspace 作为对齐参考范围时，延迟到内置 align 的稳定阶段读取：
+
+```ts
+select.align(AlignType.JustifyEnd, () => workspace.transform.getRenderCoverageBounds());
+```
+
+参考函数最多同步调用一次，几何稳定后读取；静态 world Rect 仍直接传入。矩阵/children 的构造同样应
+放入 `applyCommand` 的同步构造函数。完整参数与时序见 [Editor 规范](../../docs/specs/editor-interaction.md#64-应用公开命令边界)。
+
+`Select.resize()` 是属性面板使用的公开尺寸命令：
 
 ```ts
 const bounds = element.transform.getWorldVisualBoundsView();

package/dist/editor/interaction-controller/controller.d.ts

@@ -3,7 +3,7 @@ import { LineTree, type LineTreeBranchTailSource, type LineDecoration } from "@f
 import { type PointView, type Rect } from "@fulate/share";
 import type { HistoryManager, HistoryScope } from "../../history";
 import type { LineTool } from "../../line";
-import type { Select, SelectedPropertyPatch } from "../../select";
+import type { Select, SelectCommand, SelectedPropertyPatch } from "../../select";
 import { type SelectionOverlayProjection, type SelectionOverlayTarget } from "../../select/projection";
 import { type FlipDirection, type ResizeOptions } from "../../select/transform";
 import type { Snap } from "../../select/snap";
@@ -159,7 +159,9 @@ export declare class EditorInteractionController {
         snap: import("../../select/snap").PortSnapResult | null;
     };
     hasLineToolSession(tool: LineTool): boolean;
-    applyCommand(ownerEffects: readonly OwnerPropertyChange[], structureEffects: readonly StructureChange[], scope: HistoryScope | undefined, selectionAfter: readonly Element[], options?: ApplyCommandOptions): void;
+    /** 同一命令 owner 的公开入口，构造只在当前交互和几何稳定后运行。 */
+    executeCommand(createCommand: (selection: readonly Element[]) => SelectCommand | undefined): boolean;
+    applyCommand(ownerEffects: readonly OwnerPropertyChange[], structureEffects: readonly StructureChange[], scope: HistoryScope | undefined, selectionAfter: readonly Element[] | undefined, options?: ApplyCommandOptions): boolean;
     finishCurrentInteraction(): void;
     destroy(): void;
 }

package/dist/editor/interaction-controller/types.d.ts

@@ -25,7 +25,7 @@ export interface PointerGesture {
     finish(intent?: PointerIntent, cancelled?: boolean): void;
 }
 export interface ApplyCommandOptions {
-    readonly beforeDrain?: () => void;
+    readonly afterInstall?: () => void;
     readonly afterHistory?: () => void;
     readonly installSelection?: () => boolean;
 }

package/dist/history/index.d.ts

@@ -65,7 +65,10 @@ export declare class HistoryManager {
     get undoCount(): number;
     get redoCount(): number;
     bindSelection(adapter: HistorySelectionAdapter | null): void;
-    openScope(selectionBefore?: readonly Element<import("@fulate/core").ElementProperties, import("@fulate/core").BaseElementOption<any>, Partial<Omit<import("@fulate/core").BaseElementOption<any>, "key" | "children">>>[]): HistoryScope | undefined;
+    openScope(selectionBefore?: readonly Element<import("@fulate/core").ElementProperties, import("@fulate/core").BaseElementOption<any>, Partial<Omit<import("@fulate/core").BaseElementOption<any>, "key" | "children">>>[], options?: {
+        readonly recordHistory?: boolean;
+        readonly trackChanges?: boolean;
+    }): HistoryScope | undefined;
     /** @internal Publishes one completed actual configured semantic change. */
     publishConfiguredChange(changed: boolean | undefined): void;
     /** @internal 只由存在Canvas净变化或外部change的scope完成时写入。 */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Select } from "./select/index";
-export type { ConnectionGesture, CopyContext, ClipboardDataProducer, DeleteContext, FlipDirection, PasteContext, PasteOptions, PasteParentResolver, ResizeAnchor, ResizeOptions, SelectedPropertyPatch, SelectKeyboardCommands, SelectOption, ToolsConnectionIntent } from "./select/index";
+export type { ConnectionGesture, CopyContext, ClipboardDataProducer, DeleteContext, FlipDirection, PasteContext, PasteOptions, PasteParentResolver, ResizeAnchor, ResizeOptions, SelectedPropertyPatch, SelectCommand, SelectKeyboardCommands, SelectOption, ToolsConnectionIntent } from "./select/index";
 export { Snap } from "./select/snap";
 export { HistoryManager } from "./history/index";
 export type { EditorHistoryEntry, HistoryChange, HistoryPlacementChange, HistoryPropertyChange, HistoryScope } from "./history/index";
@@ -9,6 +9,7 @@ export { Rule } from "./rule/index";
 export type { RuleOption } from "./rule/index";
 export { EditorLayer } from "./editor-layer";
 export { alignElements } from "./select/align";
-export type { AlignType } from "./select/align";
+export { AlignType } from "./select/align";
+export type { AlignReference } from "./select/align";
 export { ArrangeType } from "./select/arrange";
 export type { ClipboardPlugin } from "./select/clipboard";

package/dist/index.js

@@ -1,6 +1,6 @@
 import { Element, ElementProperties, ElementTransform, Layer, isFormControlTarget, projectConnectionPortPoint, resolveOrigin, resolveReferenceTransform } from "@fulate/core";
 import { BaseLine, ContentEditingCapabilityToken, DEFAULT_LINE_TREE_BRANCH_STYLE, Group, Line, LineTree, PointEditingCapabilityToken, SelectionBehaviorCapabilityToken, SelectionBehaviorMode, SelectionDiveMode, SelectionSnapMode, SnapSourceCapabilityToken, TransformInteractionCapabilityToken, addLineTreeBranchAtTail, applyLineTreeTopologyDelta, connectionPortAccepts, createLineTreeTopology, createLineTreeTopologyDelta, getEditorCapability, getEditorFrameFlush, getEndpointRelationIndex, hasConnectionPortCapacity, isEndpointRelationSource, moveLineTreePoint, remapLineTreeRelations, resolveConnectEndpointChange, resolveConnectionPortChanges, resolveDisconnectEndpointChanges, resolveSelectionFrameBounds, workspaceFocusInsetsKey } from "@fulate/ui";
-import { Bound, Intersection, isIdentityMatrix, qrDecompose, transformPoint } from "@fulate/share";
+import { Bound, Intersection, isIdentityMatrix, makeBoundingBoxFromRects, qrDecompose, transformPoint } from "@fulate/share";
 import { cloneDeep, has, isNull, isString, isUndefined, last } from "lodash-es";
 import { deserializeElement } from "@fulate/import";
 import RBush from "rbush";
@@ -114,11 +114,15 @@ function rectCorners$1(rect) {
 * capability is authoritative (for example Text/KeyValue authored bounds);
 * owners without one use the shared local visual/layout fallback.
 */
-function worldSelectionFramePoints(owner) {
-	const localFrame = resolveSelectionFrameBounds(owner.element, owner.transform);
-	const matrix = owner.element.transform.getWorldMatrixView();
+function worldSelectionFramePoints(element, transform) {
+	const localFrame = resolveSelectionFrameBounds(element, transform);
+	const matrix = element.transform.getWorldMatrixView();
 	return rectCorners$1(localFrame).map((point) => transformPoint(matrix, point));
 }
+/** @internal Resolve the world AABB used by the selection frame. */
+function getWorldSelectionBounds(element, transform) {
+	return Bound.fromPoints(worldSelectionFramePoints(element, transform));
+}
 var ROTATED_RESIZE_CURSORS = [
 	"ns-resize",
 	"nesw-resize",
@@ -178,9 +182,7 @@ function createWorldSelectionFrame(owners, fallback) {
 			if (fallback) return fallback;
 			return frameFromSingleOwner(owners[0], ownerFrame);
 		}
-		const bounds = resolveSelectionFrameBounds(owners[0].element, owners[0].transform);
-		const matrix = owners[0].element.transform.getWorldMatrixView();
-		const worldBounds = Bound.fromPoints(rectCorners$1(bounds).map((point) => transformPoint(matrix, point)));
+		const worldBounds = getWorldSelectionBounds(owners[0].element, owners[0].transform);
 		if ((worldBounds.width === 0 || worldBounds.height === 0) && fallback) return fallback;
 		return createSelectionFrameProjection({
 			left: worldBounds.minX,
@@ -190,19 +192,9 @@ function createWorldSelectionFrame(owners, fallback) {
 			angle: 0
 		});
 	}
-	let left = Infinity;
-	let top = Infinity;
-	let right = -Infinity;
-	let bottom = -Infinity;
-	for (const owner of owners) for (const point of worldSelectionFramePoints(owner)) {
-		if (point.x < left) left = point.x;
-		if (point.y < top) top = point.y;
-		if (point.x > right) right = point.x;
-		if (point.y > bottom) bottom = point.y;
-	}
-	if (!Number.isFinite(left) || !Number.isFinite(top) || !Number.isFinite(right) || !Number.isFinite(bottom)) return fallback ?? null;
-	const width = right - left;
-	const height = bottom - top;
+	const bounds = makeBoundingBoxFromRects(owners.map(({ element, transform }) => getWorldSelectionBounds(element, transform)));
+	if (!Number.isFinite(bounds.left) || !Number.isFinite(bounds.top) || !Number.isFinite(bounds.width) || !Number.isFinite(bounds.height)) return fallback ?? null;
+	const { left, top, width, height } = bounds;
 	if ((width === 0 || height === 0) && fallback) return fallback;
 	return createSelectionFrameProjection({
 		left,
@@ -1290,18 +1282,19 @@ var EditorInteractionController = class {
 	restoreSelectionForHistory(elements) {
 		this.replaceSelection(elements);
 	}
-	replaceSelection(elements) {
+	replaceSelection(elements, onlyIfChanged = false) {
 		this.pendingSelectionRepair = null;
-		if (this.selectState?.kind !== "content") this.installSelectState({
-			kind: "idle",
-			gesture: null
-		});
 		const selected = /* @__PURE__ */ new Set();
 		for (const element of elements) if (element.activeRoot === this.root) selected.add(element);
 		const topLevel = [...selected].filter((element) => {
 			for (let parent = element.parent; parent; parent = parent.parent) if (selected.has(parent)) return false;
 			return true;
 		});
+		if (onlyIfChanged && topLevel.length === this.selection.length && topLevel.every((element, index) => element === this.selection[index])) return;
+		if (this.selectState?.kind !== "content") this.installSelectState({
+			kind: "idle",
+			gesture: null
+		});
 		const owners = [];
 		for (const element of topLevel) {
 			const behavior = getEditorCapability(element, SelectionBehaviorCapabilityToken);
@@ -1527,7 +1520,7 @@ var EditorInteractionController = class {
 		this.select.transform.markPaintDirty();
 	}
 	applyAuthoredBatch(ownerEffects, structureEffects, scope) {
-		this.root.applyChangeBatch(ownerEffects, structureEffects, scope);
+		return this.root.applyChangeBatch(ownerEffects, structureEffects, scope);
 	}
 	onPointerDown(event) {
 		if (this.activeGesture) return;
@@ -2558,26 +2551,53 @@ var EditorInteractionController = class {
 	hasLineToolSession(tool) {
 		return this.lineSession?.tool === tool || this.lineTreeSession?.tool === tool;
 	}
+	/** 同一命令 owner 的公开入口，构造只在当前交互和几何稳定后运行。 */
+	executeCommand(createCommand) {
+		this.finishCurrentInteraction();
+		if (this.select.interactionController !== this) return false;
+		this.root.frameRuntime.drain();
+		if (this.select.interactionController !== this) return false;
+		const command = createCommand(this.selection);
+		if (this.select.interactionController !== this || !command) return false;
+		const scope = this.history.openScope(this.selection, {
+			recordHistory: command.recordHistory,
+			trackChanges: true
+		});
+		return this.applyCommand(resolveConnectionPortChanges(this.root, command.ownerChanges ?? []), command.structureChanges ?? [], scope, command.selectionAfter, command);
+	}
 	applyCommand(ownerEffects, structureEffects, scope, selectionAfter, options) {
 		const selectionOwners = this.owners;
+		const selectionBefore = this.selection;
 		let installedSelection;
-		this.applyAuthoredBatch(ownerEffects, structureEffects, scope);
-		if (options?.installSelection ? options.installSelection() : this.owners === selectionOwners || this.pendingSelectionRepair === this.owners) {
-			this.replaceSelection(selectionAfter);
+		const installed = this.applyAuthoredBatch(ownerEffects, structureEffects, scope);
+		if (this.select.interactionController !== this) {
+			scope?.discard();
+			return installed;
+		}
+		const canInstallSelection = (selectionAfter !== void 0 || installed && structureEffects.length > 0) && (options?.installSelection ? options.installSelection() : this.owners === selectionOwners || this.pendingSelectionRepair === this.owners);
+		if (canInstallSelection) {
+			this.replaceSelection(selectionAfter ?? this.selection, selectionAfter === void 0);
 			if (options?.installSelection) installedSelection = {
 				owners: this.owners,
 				interaction: this.controllerState
 			};
 		}
-		options?.beforeDrain?.();
+		const selectionRepaired = canInstallSelection && this.selection.length !== selectionBefore.length;
+		if (installed) options?.afterInstall?.();
 		if (this.select.interactionController !== this) {
 			scope?.discard();
-			return;
+			return installed;
 		}
 		this.root.frameRuntime.drain();
-		this.publishConfiguredChange(scope?.finish(this.selection));
+		if (this.select.interactionController !== this) {
+			scope?.discard();
+			return installed;
+		}
+		const changed = scope?.finish(this.selection) ?? installed;
+		this.publishConfiguredChange(changed);
 		options?.afterHistory?.();
-		if (!options?.installSelection || installedSelection?.owners === this.owners && installedSelection.interaction === this.controllerState) this.notifySelect("select:end");
+		if ((selectionAfter !== void 0 || selectionRepaired) && (!options?.installSelection || installedSelection?.owners === this.owners && installedSelection.interaction === this.controllerState)) this.notifySelect("select:end");
+		return changed;
 	}
 	finishCurrentInteraction() {
 		if (this.contentSession) {
@@ -2749,9 +2769,9 @@ var HistoryManager = class {
 	bindSelection(adapter) {
 		this.selectionAdapter = adapter;
 	}
-	openScope(selectionBefore = this.selectionAdapter?.getSelection() ?? []) {
-		const recordHistory = this.enabled;
-		if (!recordHistory && !this.selectionAdapter?.hasConfiguredChangeListener()) return void 0;
+	openScope(selectionBefore = this.selectionAdapter?.getSelection() ?? [], options) {
+		const recordHistory = this.enabled && options?.recordHistory !== false;
+		if (!recordHistory && !options?.trackChanges && !this.selectionAdapter?.hasConfiguredChangeListener()) return void 0;
 		return new ActiveHistoryScope(this, recordHistory ? selectionKeys(selectionBefore) : null, recordHistory);
 	}
 	/** @internal Publishes one completed actual configured semantic change. */
@@ -2887,86 +2907,142 @@ var HistoryManager = class {
 };
 //#endregion
 //#region packages/tools/src/select/align.ts
-function resolveOffsets(rects, type) {
-	if (type === "justify-start") {
-		const target = Math.min(...rects.map(({ left }) => left));
+/** Select 支持的对齐与分布方向。 */
+var AlignType = /* @__PURE__ */ function(AlignType) {
+	AlignType["JustifyStart"] = "justify-start";
+	AlignType["JustifyCenter"] = "justify-center";
+	AlignType["JustifyEnd"] = "justify-end";
+	AlignType["JustifyBetween"] = "justify-between";
+	AlignType["AlignStart"] = "align-start";
+	AlignType["AlignCenter"] = "align-center";
+	AlignType["AlignEnd"] = "align-end";
+	AlignType["AlignBetween"] = "align-between";
+	return AlignType;
+}({});
+function compareElementKeys(left, right) {
+	if (left.element.key < right.element.key) return -1;
+	if (left.element.key > right.element.key) return 1;
+	return 0;
+}
+function compareDistributionRects(left, right, axis) {
+	const primary = left[axis.position] - right[axis.position];
+	if (primary !== 0) return primary;
+	const secondary = left[axis.crossPosition] - right[axis.crossPosition];
+	if (secondary !== 0) return secondary;
+	return compareElementKeys(left, right);
+}
+function resolveDistributionOffsets(rects, reference, axis) {
+	const { position, size, offset } = axis;
+	const start = reference[position];
+	const referenceEnd = start + reference[size];
+	let totalSize = 0;
+	for (const rect of rects) totalSize += rect[size];
+	const roundoff = Math.max(1, Math.abs(start), Math.abs(referenceEnd), Math.abs(totalSize)) * Number.EPSILON * rects.length * 4;
+	const orderStep = roundoff * 8;
+	const freeSpace = reference[size] - totalSize;
+	const fittedFreeSpace = Math.abs(freeSpace) <= roundoff ? 0 : freeSpace;
+	const gap = fittedFreeSpace / (rects.length - 1);
+	const distributionEnd = start + totalSize + fittedFreeSpace;
+	rects.sort((left, right) => compareDistributionRects(left, right, axis));
+	const lastIndex = rects.length - 1;
+	const latestStarts = new Array(rects.length);
+	latestStarts[lastIndex] = distributionEnd - rects[lastIndex][size];
+	for (let index = lastIndex - 1; index >= 0; index--) latestStarts[index] = Math.min(distributionEnd - rects[index][size], latestStarts[index + 1] - orderStep);
+	if (latestStarts[0] < start) return;
+	let idealTarget = start;
+	let previousTarget = start;
+	for (let index = 0; index <= lastIndex; index++) {
+		let target;
+		if (index === 0) target = start;
+		else if (index === lastIndex) target = latestStarts[lastIndex];
+		else {
+			idealTarget += rects[index - 1][size] + gap;
+			target = Math.min(latestStarts[index], Math.max(previousTarget + orderStep, idealTarget));
+		}
+		const delta = target - rects[index][position];
+		rects[index][offset] = Math.abs(delta) <= roundoff ? 0 : delta;
+		previousTarget = target;
+	}
+}
+function resolveOffsets(rects, type, reference) {
+	if (type === AlignType.JustifyStart) {
+		const target = reference.left;
 		rects.forEach((rect) => {
 			rect.dx = target - rect.left;
 		});
 		return;
 	}
-	if (type === "justify-center") {
-		const target = (Math.min(...rects.map((rect) => rect.left)) + Math.max(...rects.map((rect) => rect.left + rect.width))) / 2;
+	if (type === AlignType.JustifyCenter) {
+		const target = reference.left + reference.width / 2;
 		rects.forEach((rect) => {
 			rect.dx = target - (rect.left + rect.width / 2);
 		});
 		return;
 	}
-	if (type === "justify-end") {
-		const target = Math.max(...rects.map((rect) => rect.left + rect.width));
+	if (type === AlignType.JustifyEnd) {
+		const target = reference.left + reference.width;
 		rects.forEach((rect) => {
 			rect.dx = target - (rect.left + rect.width);
 		});
 		return;
 	}
-	if (type === "justify-between") {
-		rects.sort((left, right) => left.left - right.left);
-		const start = rects[0].left;
-		const end = last(rects);
-		const total = rects.reduce((sum, rect) => sum + rect.width, 0);
-		const gap = (end.left + end.width - start - total) / (rects.length - 1);
-		let x = start;
-		for (const rect of rects) {
-			rect.dx = x - rect.left;
-			x += rect.width + gap;
-		}
+	if (type === AlignType.JustifyBetween) {
+		resolveDistributionOffsets(rects, reference, {
+			position: "left",
+			crossPosition: "top",
+			size: "width",
+			offset: "dx"
+		});
 		return;
 	}
-	if (type === "align-start") {
-		const target = Math.min(...rects.map(({ top }) => top));
+	if (type === AlignType.AlignStart) {
+		const target = reference.top;
 		rects.forEach((rect) => {
 			rect.dy = target - rect.top;
 		});
 		return;
 	}
-	if (type === "align-center") {
-		const target = (Math.min(...rects.map((rect) => rect.top)) + Math.max(...rects.map((rect) => rect.top + rect.height))) / 2;
+	if (type === AlignType.AlignCenter) {
+		const target = reference.top + reference.height / 2;
 		rects.forEach((rect) => {
 			rect.dy = target - (rect.top + rect.height / 2);
 		});
 		return;
 	}
-	if (type === "align-end") {
-		const target = Math.max(...rects.map((rect) => rect.top + rect.height));
+	if (type === AlignType.AlignEnd) {
+		const target = reference.top + reference.height;
 		rects.forEach((rect) => {
 			rect.dy = target - (rect.top + rect.height);
 		});
 		return;
 	}
-	rects.sort((left, right) => left.top - right.top);
-	const start = rects[0].top;
-	const end = last(rects);
-	const total = rects.reduce((sum, rect) => sum + rect.height, 0);
-	const gap = (end.top + end.height - start - total) / (rects.length - 1);
-	let y = start;
-	for (const rect of rects) {
-		rect.dy = y - rect.top;
-		y += rect.height + gap;
-	}
+	resolveDistributionOffsets(rects, reference, {
+		position: "top",
+		crossPosition: "left",
+		size: "height",
+		offset: "dy"
+	});
 }
-function alignElements(select, type) {
+function alignElements(select, type, referenceRect) {
 	const controller = select.interactionController;
 	let elements = controller.selection;
-	if (elements.length < 2 || type.endsWith("between") && elements.length < 3) return;
+	const between = type === AlignType.JustifyBetween || type === AlignType.AlignBetween;
+	const minimum = referenceRect ? between ? 2 : 1 : between ? 3 : 2;
+	if (elements.length < minimum) return;
 	controller.finishCurrentInteraction();
+	if (select.interactionController !== controller) return;
 	controller.root.frameRuntime.drain();
 	if (select.interactionController !== controller) return;
 	elements = controller.selection;
-	if (elements.length < 2 || type.endsWith("between") && elements.length < 3) return;
+	if (elements.length < minimum) return;
+	const reference = typeof referenceRect === "function" ? referenceRect() : referenceRect;
+	if (select.interactionController !== controller) return;
 	const rects = elements.map((element) => {
-		const bounds = element.transform.getWorldVisualBoundsView();
+		const transform = getEditorCapability(element, TransformInteractionCapabilityToken);
+		const bounds = getWorldSelectionBounds(element, transform);
 		return {
 			element,
+			transform,
 			left: bounds.left,
 			top: bounds.top,
 			width: bounds.width,
@@ -2975,14 +3051,21 @@ function alignElements(select, type) {
 			dy: 0
 		};
 	});
-	resolveOffsets(rects, type);
+	resolveOffsets(rects, type, reference ?? makeBoundingBoxFromRects(rects));
 	const changes = [];
 	for (const rect of rects) {
 		if (rect.dx === 0 && rect.dy === 0) continue;
-		const capability = getEditorCapability(rect.element, TransformInteractionCapabilityToken);
-		if (!capability) continue;
-		const baseline = capability.captureTransformBaseline();
-		changes.push(...capability.resolveTransformChange(baseline, { worldDelta: new DOMMatrix().translate(rect.dx, rect.dy) }));
+		const { transform } = rect;
+		if (!transform) continue;
+		const baseline = transform.captureTransformBaseline();
+		changes.push(...transform.resolveTransformChange(baseline, { worldDelta: new DOMMatrix([
+			1,
+			0,
+			0,
+			1,
+			rect.dx,
+			rect.dy
+		]) }));
 	}
 	if (changes.length === 0) return;
 	const scope = select.history.openScope(elements);
@@ -3357,7 +3440,7 @@ function pasteData(select, controller, pasteSelection, task, data, deserializers
 	const scope = controller.history.openScope(controller.selection);
 	const installSelection = () => controller.ownsPasteSelection(pasteSelection, task);
 	controller.applyCommand(changes, appendStructure(placements), scope, elements, options?.afterInstall ? {
-		beforeDrain: () => options.afterInstall({
+		afterInstall: () => options.afterInstall({
 			applicationData: data.applicationData,
 			keyMap,
 			history: recordHistory ? scope : void 0
@@ -3432,7 +3515,7 @@ function deleteElements(select, afterInstall) {
 	const recordsHistory = select.history.enabled;
 	const scope = select.history.openScope(selected);
 	controller.applyCommand([], structure, scope, [], {
-		beforeDrain: afterInstall ? () => afterInstall({
+		afterInstall: afterInstall ? () => afterInstall({
 			elements: subjects,
 			history: recordsHistory ? scope : void 0
 		}) : void 0,
@@ -3847,6 +3930,19 @@ var Select = class extends Element {
 	select(elements) {
 		this.controller?.setSelection(elements);
 	}
+	/** 完成已接受的当前交互，取消未提交的画线草稿；无活动交互时无操作。 */
+	finishCurrentInteraction() {
+		this.controller?.finishCurrentInteraction();
+	}
+	/**
+	* 先结束旧交互并稳定几何，再同步调用 createCommand，传入 live selection。
+	* 返回本命令 Canvas configured 的净变化，与 History/监听器是否开启无关；不包含旧交互。
+	* 返回 undefined 的构造或空/相同值命令是普通 noop。未激活的 Select 不调用构造。
+	* 普通选区同一 patch 使用 setProperties；此入口用于 owner-specific 与结构组合操作。
+	*/
+	applyCommand(createCommand) {
+		return this.controller?.executeCommand(createCommand) ?? false;
+	}
 	/**
 	* Groups the live multi-selection. Accepted active Transform work finishes
 	* before the independent Group command; stale pointer continuation is ignored.
@@ -3863,8 +3959,20 @@ var Select = class extends Element {
 	unGroup() {
 		return unGroup(this);
 	}
-	align(type) {
-		return alignElements(this, type);
+	/**
+	* Aligns the live selection in world space. Without `referenceRect`, the
+	* current selection-frame AABB is the reference. A supplied world Rect is
+	* used directly; a reference callback runs once after the previous interaction
+	* and pending geometry finish. Distribution keeps strict edge gaps when they are numerically
+	* possible and uses bounded overlap when the selected sizes exceed the reference,
+	* while keeping every selection-frame AABB inside it and preserving order. The
+	* current axis is a noop only when an element cannot fit or no ordered layout is
+	* representable. A successful non-noop creates one Transform batch and one Select
+	* History entry; a noop creates neither a transform, History entry, nor configured
+	* change.
+	*/
+	align(type, referenceRect) {
+		return alignElements(this, type, referenceRect);
 	}
 	/** 按当前 Layer 与 sibling 顺序排列 live selection。 */
 	arrange(type) {
@@ -5066,4 +5174,4 @@ var EditorLayer = class extends Layer {
 	}
 };
 //#endregion
-export { ArrangeType, EditorLayer, HistoryManager, LineTool, Rule, Select, Snap, alignElements };
+export { AlignType, ArrangeType, EditorLayer, HistoryManager, LineTool, Rule, Select, Snap, alignElements };

package/dist/select/align.d.ts

@@ -1,3 +1,16 @@
+import { type Rect } from "@fulate/share";
 import type { Select } from "./index";
-export type AlignType = "justify-start" | "justify-center" | "justify-end" | "justify-between" | "align-start" | "align-center" | "align-end" | "align-between";
-export declare function alignElements(select: Select, type: AlignType): void;
+/** Select 支持的对齐与分布方向。 */
+export declare enum AlignType {
+    JustifyStart = "justify-start",
+    JustifyCenter = "justify-center",
+    JustifyEnd = "justify-end",
+    JustifyBetween = "justify-between",
+    AlignStart = "align-start",
+    AlignCenter = "align-center",
+    AlignEnd = "align-end",
+    AlignBetween = "align-between"
+}
+/** World reference Rect, or a synchronous read after interaction and geometry completion. */
+export type AlignReference = Readonly<Rect> | (() => Readonly<Rect>);
+export declare function alignElements(select: Select, type: AlignType, referenceRect?: AlignReference): void;

package/dist/select/index.d.ts

@@ -1,7 +1,7 @@
-import { Element, ElementProperties, type BaseElementOption, type ConnectionPortRef, type Layer, type Root } from "@fulate/core";
+import { Element, ElementProperties, type BaseElementOption, type ConnectionPortRef, type Layer, type Root, type OwnerPropertyChange, type StructureChange } from "@fulate/core";
 import { EditorInteractionController } from "../editor/interaction-controller";
 import { HistoryManager } from "../history";
-import { type AlignType } from "./align";
+import { type AlignType, type AlignReference } from "./align";
 import { type ArrangeType } from "./arrange";
 import { type ClipboardDataProducer, type ClipboardPlugin, type DeleteContext, type PasteOptions } from "./clipboard";
 import { Snap } from "./snap";
@@ -31,6 +31,23 @@ export interface SelectOption extends BaseElementOption {
 }
 /** 一次 selection property intent；同一 canonical reference 直接交给各 owner。 */
 export type SelectedPropertyPatch = Readonly<Record<string, unknown>>;
+/** 应用同步构造的 owner-specific 属性与结构命令；值按原引用交给对应 owner。 */
+export interface SelectCommand {
+    readonly ownerChanges?: readonly OwnerPropertyChange[];
+    readonly structureChanges?: readonly StructureChange[];
+    /**
+     * 省略保留当前选择意图；结构提交后过滤已移除或被选中祖先覆盖的元素。
+     * 空数组清空选择；仅选择变化不进入 History 或配置通知。
+     */
+    readonly selectionAfter?: readonly Element[];
+    /** false 只关闭本命令的 History；true/省略仍服从 history.enabled。 */
+    readonly recordHistory?: boolean;
+    /**
+     * 有实际 Scene 安装时同步调用一次，位于 Core lifecycle/hooks/observers 及选择安装之后，
+     * frame drain、History finish 与配置完成通知之前。不会随 undo/redo 重放；异常直接传播。
+     */
+    readonly afterInstall?: () => void;
+}
 /**
  * 轻量 Editor command/paint surface；交互状态由唯一 controller 拥有。
  *
@@ -63,6 +80,15 @@ export declare class Select extends Element {
     get interactionController(): EditorInteractionController;
     /** 以一次独立操作选择给定元素，并在完成后异步通知 `select:end`。 */
     select(elements: readonly Element[]): void;
+    /** 完成已接受的当前交互，取消未提交的画线草稿；无活动交互时无操作。 */
+    finishCurrentInteraction(): void;
+    /**
+     * 先结束旧交互并稳定几何，再同步调用 createCommand，传入 live selection。
+     * 返回本命令 Canvas configured 的净变化，与 History/监听器是否开启无关；不包含旧交互。
+     * 返回 undefined 的构造或空/相同值命令是普通 noop。未激活的 Select 不调用构造。
+     * 普通选区同一 patch 使用 setProperties；此入口用于 owner-specific 与结构组合操作。
+     */
+    applyCommand(createCommand: (selection: readonly Element[]) => SelectCommand | undefined): boolean;
     /**
      * Groups the live multi-selection. Accepted active Transform work finishes
      * before the independent Group command; stale pointer continuation is ignored.
@@ -75,7 +101,19 @@ export declare class Select extends Element {
      * An obvious non-Group noop does not drain the frame runtime.
      */
     unGroup(): Element<ElementProperties, BaseElementOption<any>, Partial<Omit<BaseElementOption<any>, "key" | "children">>>[];
-    align(type: AlignType): void;
+    /**
+     * Aligns the live selection in world space. Without `referenceRect`, the
+     * current selection-frame AABB is the reference. A supplied world Rect is
+     * used directly; a reference callback runs once after the previous interaction
+     * and pending geometry finish. Distribution keeps strict edge gaps when they are numerically
+     * possible and uses bounded overlap when the selected sizes exceed the reference,
+     * while keeping every selection-frame AABB inside it and preserving order. The
+     * current axis is a noop only when an element cannot fit or no ordered layout is
+     * representable. A successful non-noop creates one Transform batch and one Select
+     * History entry; a noop creates neither a transform, History entry, nor configured
+     * change.
+     */
+    align(type: AlignType, referenceRect?: AlignReference): void;
     /** 按当前 Layer 与 sibling 顺序排列 live selection。 */
     arrange(type: ArrangeType): void;
     /**

package/dist/select/projection.d.ts

@@ -1,6 +1,6 @@
 import { Element } from "@fulate/core";
 import { type PointEditTarget, type PointEditingScope, type SnapSourceCapability, type TransformInteractionCapability, type TransformInteractionPolicy } from "@fulate/ui";
-import { type PointView, type Rect } from "@fulate/share";
+import { Bound, type PointView, type Rect } from "@fulate/share";
 export type ResizeHandle = "tl" | "tr" | "br" | "bl" | "mt" | "mr" | "mb" | "ml";
 export type SelectionRotationPivot = {
     readonly kind: "selection-center";
@@ -109,14 +109,16 @@ export interface SelectionProjectionTopology {
     readonly pointScopeOutline: readonly PointView[] | null;
     readonly pointScopeValid: boolean;
 }
-export declare function createSelectionFrameProjection({ left, top, width, height, angle }: Pick<SelectionFrameProjection, "left" | "top" | "width" | "height" | "angle">): SelectionFrameProjection;
+/** @internal Resolve the world AABB used by the selection frame. */
+export declare function getWorldSelectionBounds(element: Element, transform: TransformInteractionCapability | undefined): Bound;
+export declare function createSelectionFrameProjection({ left, top, width, height, angle, }: Pick<SelectionFrameProjection, "left" | "top" | "width" | "height" | "angle">): SelectionFrameProjection;
 /** @internal Build a command frame from the current owner bounds. */
 export declare function createWorldSelectionFrame(owners: readonly ProjectionOwner[], fallback?: SelectionFrameProjection | null): SelectionFrameProjection;
 export declare function createSelectionRotationPivotSnapMarkers(frame: SelectionFrameProjection): readonly SelectionRotationPivotSnapMarker[];
 export declare function createSelectionProjectionMembership(owners: readonly ProjectionOwner[], policy: ProjectionPolicy): SelectionProjectionMembership;
 export declare function createSelectionProjectionTopology(owners: readonly ProjectionOwner[], isCurrent?: (owner: ProjectionOwner) => boolean): SelectionProjectionTopology;
 export declare function createProjectionOwner(element: Element, frameVisible?: boolean, pointScope?: PointEditingScope | null, pointEnabled?: boolean): ProjectionOwner;
-export declare function buildSelectionOverlayProjection({ owners, membership, topology, frame: frameOverride, policy, pivot, showPivot, pivotSnapMarkers, activePointTarget, marquee }: {
+export declare function buildSelectionOverlayProjection({ owners, membership, topology, frame: frameOverride, policy, pivot, showPivot, pivotSnapMarkers, activePointTarget, marquee, }: {
     readonly owners: readonly ProjectionOwner[];
     readonly membership: SelectionProjectionMembership;
     readonly topology: SelectionProjectionTopology;

package/package.json

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