@fulate/tools 1.0.12 → 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";
@@ -10,5 +10,6 @@ export type { RuleOption } from "./rule/index";
 export { EditorLayer } from "./editor-layer";
 export { alignElements } 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

@@ -1282,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);
@@ -1519,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;
@@ -2550,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) {
@@ -2741,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. */
@@ -3002,10 +3030,13 @@ function alignElements(select, type, referenceRect) {
 	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 < minimum) return;
+	const reference = typeof referenceRect === "function" ? referenceRect() : referenceRect;
+	if (select.interactionController !== controller) return;
 	const rects = elements.map((element) => {
 		const transform = getEditorCapability(element, TransformInteractionCapabilityToken);
 		const bounds = getWorldSelectionBounds(element, transform);
@@ -3020,7 +3051,7 @@ function alignElements(select, type, referenceRect) {
 			dy: 0
 		};
 	});
-	resolveOffsets(rects, type, referenceRect ?? makeBoundingBoxFromRects(rects));
+	resolveOffsets(rects, type, reference ?? makeBoundingBoxFromRects(rects));
 	const changes = [];
 	for (const rect of rects) {
 		if (rect.dx === 0 && rect.dy === 0) continue;
@@ -3409,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
@@ -3484,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,
@@ -3899,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.
@@ -3918,7 +3962,8 @@ var Select = class extends Element {
 	/**
 	* Aligns the live selection in world space. Without `referenceRect`, the
 	* current selection-frame AABB is the reference. A supplied world Rect is
-	* used directly. Distribution keeps strict edge gaps when they are numerically
+	* 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

package/dist/select/align.d.ts

@@ -11,4 +11,6 @@ export declare enum AlignType {
     AlignEnd = "align-end",
     AlignBetween = "align-between"
 }
-export declare function alignElements(select: Select, type: AlignType, referenceRect?: Readonly<Rect>): void;
+/** 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,8 +1,7 @@
-import { Element, ElementProperties, type BaseElementOption, type ConnectionPortRef, type Layer, type Root } from "@fulate/core";
-import type { Rect } from "@fulate/share";
+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";
@@ -32,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 拥有。
  *
@@ -64,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.
@@ -79,7 +104,8 @@ export declare class Select extends Element {
     /**
      * Aligns the live selection in world space. Without `referenceRect`, the
      * current selection-frame AABB is the reference. A supplied world Rect is
-     * used directly. Distribution keeps strict edge gaps when they are numerically
+     * 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
@@ -87,7 +113,7 @@ export declare class Select extends Element {
      * History entry; a noop creates neither a transform, History entry, nor configured
      * change.
      */
-    align(type: AlignType, referenceRect?: Readonly<Rect>): void;
+    align(type: AlignType, referenceRect?: AlignReference): void;
     /** 按当前 Layer 与 sibling 顺序排列 live selection。 */
     arrange(type: ArrangeType): void;
     /**

package/package.json

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