@tmagic/editor 1.8.0-beta.3 → 1.8.0-beta.5

package/dist/es/services/editor.js

@@ -3,44 +3,24 @@ import BaseService from "./BaseService.js";
 import props_default from "./props.js";
 import history_default from "./history.js";
 import storage_default, { Protocol } from "./storage.js";
-import { COPY_STORAGE_KEY, calcAlignCenterStyle, calcLayerTargetIndex, calcMoveStyle, classifyDragSources, collectRelatedNodes, editorNodeMergeCustomizer, fixNodePosition, getInitPositionStyle, getNodeIndex, getPageFragmentList, getPageList, moveItemsInContainer, resolveSelectedNode, setChildrenLayout, setLayout, toggleFixedPosition } from "../utils/editor.js";
+import { COPY_STORAGE_KEY, calcAlignCenterStyle, calcLayerTargetIndex, calcMoveStyle, classifyDragSources, collectRelatedNodes, describeStepForRevert, editorNodeMergeCustomizer, fixNodePosition, getInitPositionStyle, getNodeIndex, getPageFragmentList, getPageList, moveItemsInContainer, resolveSelectedNode, setChildrenLayout, setLayout, toggleFixedPosition } from "../utils/editor.js";
 import { beforePaste, getAddParent } from "../utils/operator.js";
 import { isFixed } from "@tmagic/stage";
-import { getNodeInfo, getNodePath, getValueByKeyPath, isPage, isPageFragment, setValueByKeyPath } from "@tmagic/utils";
+import { getNodeInfo, getNodePath, getValueByKeyPath, guid, isPage, isPageFragment, setValueByKeyPath } from "@tmagic/utils";
 import { NodeType } from "@tmagic/core";
 import { reactive, toRaw } from "vue";
-import { cloneDeep as cloneDeep$1, isObject, mergeWith, uniq } from "lodash-es";
+import { cloneDeep as cloneDeep$1, isEmpty, isEqual, isObject, mergeWith, uniq } from "lodash-es";
 //#region packages/editor/src/services/editor.ts
 /**
-* 给「回滚」生成的新 step 用的简短描述生成器。
-* 与 UI 层 `describePageStep` 同义，但避免 service 反向依赖 layouts/，故在此本地实现。
+* 把「变更前后节点快照」列表归一成 update 类型的 {@link StepDiffItem} 列表，供 {@link StepValue.diff} 使用。
+* `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
+* 缺省（未传 / 空数组）才退化为整节点替换。
 */
-var describeStepForRevert = (step) => {
-	switch (step.opType) {
-		case "add": {
-			const count = step.nodes?.length ?? 0;
-			const node = step.nodes?.[0];
-			const label = node?.name || node?.type || (node?.id !== void 0 ? `${node.id}` : "");
-			return `撤回新增 ${count} 个节点${count === 1 && label ? `（${label}）` : ""}`;
-		}
-		case "remove": {
-			const count = step.removedItems?.length ?? 0;
-			const node = step.removedItems?.[0]?.node;
-			const label = node?.name || node?.type || (node?.id !== void 0 ? `${node.id}` : "");
-			return `还原已删除的 ${count} 个节点${count === 1 && label ? `（${label}）` : ""}`;
-		}
-		default: {
-			const items = step.updatedItems ?? [];
-			if (items.length === 1) {
-				const { newNode, oldNode, changeRecords } = items[0];
-				const target = newNode?.name || newNode?.type || oldNode?.name || oldNode?.type || `${newNode?.id ?? ""}`;
-				const propPath = changeRecords?.[0]?.propPath;
-				return propPath ? `还原 ${target} · ${propPath}` : `还原 ${target}`;
-			}
-			return `还原 ${items.length} 个节点的修改`;
-		}
-	}
-};
+var buildUpdateDiff = (items) => items.map(({ oldNode, newNode, changeRecords }) => ({
+	oldSchema: oldNode,
+	newSchema: newNode,
+	...changeRecords?.length ? { changeRecords } : {}
+}));
 var Editor = class extends BaseService {
 	state = reactive({
 		root: null,
@@ -58,6 +38,12 @@ var Editor = class extends BaseService {
 		alwaysMultiSelect: false
 	});
 	selectionBeforeOp = null;
+	/**
+	* 最近一次 pushOpHistory 写入的历史记录 uuid。
+	* 供 *AndGetHistoryId 系列方法在调用普通操作后取回本次产生的历史记录 id；
+	* 普通操作不会读取它，调用前由 *AndGetHistoryId 重置为 null。
+	*/
+	lastPushedHistoryId = null;
 	constructor() {
 		super(canUsePluginMethods.async.map((methodName) => ({
 			name: methodName,
@@ -72,8 +58,9 @@ var Editor = class extends BaseService {
 	* 设置当前指点节点配置
 	* @param name 'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength
 	* @param value MNode
+	* @param options.historySource 设置 root 时，本次变更写入历史记录的「操作来源」（仅 name === 'root' 时生效）
 	*/
-	set(name, value) {
+	set(name, value, options = {}) {
 		const preValue = this.state[name];
 		this.state[name] = value;
 		if (name === "nodes" && Array.isArray(value)) this.set("node", value[0]);
@@ -84,6 +71,13 @@ var Editor = class extends BaseService {
 				this.state.pageLength = getPageList(app).length || 0;
 				this.state.pageFragmentLength = getPageFragmentList(app).length || 0;
 				this.state.stageLoading = this.state.pageLength !== 0;
+				if (preValue && !isEmpty(preValue)) this.pushRootDiffHistory(preValue, app, options.historySource);
+				else app.items?.forEach((pageNode) => {
+					if (pageNode?.id !== void 0 && !history_default.getPageMarker(pageNode.id)) history_default.setPageMarker(pageNode.id, {
+						name: pageNode.name,
+						source: options.historySource
+					});
+				});
 			} else {
 				this.state.pageLength = 0;
 				this.state.pageFragmentLength = 0;
@@ -109,7 +103,23 @@ var Editor = class extends BaseService {
 	getNodeInfo(id, raw = true) {
 		let root = this.get("root");
 		if (raw) root = toRaw(root);
-		return getNodeInfo(id, root);
+		if (!root) return {
+			node: null,
+			parent: null,
+			page: null
+		};
+		if (id === root.id) return {
+			node: root,
+			parent: null,
+			page: null
+		};
+		const pageIdStr = `${this.get("page")?.id || ""}`;
+		const currentPageNode = root.items?.find((item) => `${item.id}` === pageIdStr);
+		if (currentPageNode && `${id}` !== pageIdStr) {
+			const info = getNodeInfo(id, currentPageNode);
+			if (info.node) return info;
+		}
+		return getNodeInfo(id, root, currentPageNode);
 	}
 	/**
 	* 根据ID获取指点节点配置
@@ -269,7 +279,7 @@ var Editor = class extends BaseService {
 	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns 添加后的节点
 	*/
-	async add(addNode, parent, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription } = {}) {
+	async add(addNode, parent, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const stage = this.get("stage");
 		const addNodes = [];
@@ -302,18 +312,26 @@ var Editor = class extends BaseService {
 		}
 		if (!(isPage(newNodes[0]) || isPageFragment(newNodes[0]))) {
 			const pageForOp = this.getNodeInfo(newNodes[0].id, false).page;
-			if (!doNotPushHistory) this.pushOpHistory("add", {
-				nodes: newNodes.map((n) => cloneDeep$1(toRaw(n))),
-				parentId: (this.getParentById(newNodes[0].id, false) ?? this.get("root")).id,
-				indexMap: Object.fromEntries(newNodes.map((n) => {
-					const p = this.getParentById(n.id, false);
-					return [n.id, p ? getNodeIndex(n.id, p) : -1];
-				}))
-			}, {
-				name: pageForOp?.name || "",
-				id: pageForOp.id
-			}, historyDescription);
-			else this.selectionBeforeOp = null;
+			if (!doNotPushHistory) {
+				const parentId = (this.getParentById(newNodes[0].id, false) ?? this.get("root")).id;
+				this.pushOpHistory("add", {
+					diff: newNodes.map((n) => {
+						const p = this.getParentById(n.id, false);
+						const idx = p ? getNodeIndex(n.id, p) : -1;
+						return {
+							newSchema: cloneDeep$1(toRaw(n)),
+							parentId,
+							index: typeof idx === "number" ? idx : -1
+						};
+					}),
+					pageData: {
+						name: pageForOp?.name || "",
+						id: pageForOp.id
+					},
+					historyDescription,
+					source: historySource
+				});
+			} else this.selectionBeforeOp = null;
 		}
 		this.emit("add", newNodes);
 		return Array.isArray(addNode) ? newNodes : newNodes[0];
@@ -379,7 +397,7 @@ var Editor = class extends BaseService {
 	* @param options.doNotSwitchPage 删除后是否不切换当前页面（默认 false；删除页面 / 页面片段时为 true 会跳过自动切换到首个剩余页面）
 	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	*/
-	async remove(nodeOrNodeList, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription } = {}) {
+	async remove(nodeOrNodeList, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const nodes = Array.isArray(nodeOrNodeList) ? nodeOrNodeList : [nodeOrNodeList];
 		const removedItems = [];
@@ -393,7 +411,7 @@ var Editor = class extends BaseService {
 				};
 				const idx = getNodeIndex(curNode.id, parent);
 				removedItems.push({
-					node: cloneDeep$1(toRaw(curNode)),
+					oldSchema: cloneDeep$1(toRaw(curNode)),
 					parentId: parent.id,
 					index: typeof idx === "number" ? idx : -1
 				});
@@ -403,11 +421,16 @@ var Editor = class extends BaseService {
 			doNotSelect,
 			doNotSwitchPage
 		})));
-		if (removedItems.length > 0 && pageForOp) if (!doNotPushHistory) this.pushOpHistory("remove", { removedItems }, pageForOp, historyDescription);
+		if (removedItems.length > 0 && pageForOp) if (!doNotPushHistory) this.pushOpHistory("remove", {
+			diff: removedItems,
+			pageData: pageForOp,
+			historyDescription,
+			source: historySource
+		});
 		else this.selectionBeforeOp = null;
 		this.emit("remove", nodes);
 	}
-	async doUpdate(config, { changeRecords = [] } = {}) {
+	async doUpdate(config, { changeRecords = [], historySource } = {}) {
 		const root = this.get("root");
 		if (!root) throw new Error("root为空");
 		if (!config?.id) throw new Error("没有配置或者配置缺少id值");
@@ -418,7 +441,7 @@ var Editor = class extends BaseService {
 		newConfig = mergeWith(cloneDeep$1(node), newConfig, editorNodeMergeCustomizer);
 		if (!newConfig.type) throw new Error("配置缺少type值");
 		if (newConfig.type === NodeType.ROOT) {
-			this.set("root", newConfig);
+			this.set("root", newConfig, { historySource });
 			return {
 				oldNode: node,
 				newNode: newConfig,
@@ -464,23 +487,31 @@ var Editor = class extends BaseService {
 	*/
 	async update(config, data = {}) {
 		this.captureSelectionBeforeOp();
-		const { doNotPushHistory = false, changeRecordList, changeRecords, historyDescription } = data;
+		const { doNotPushHistory = false, changeRecordList, changeRecords, historyDescription, historySource } = data;
 		const nodes = Array.isArray(config) ? config : [config];
 		const updateData = await Promise.all(nodes.map((node, index) => {
 			const recordsForNode = changeRecordList ? changeRecordList[index] ?? [] : changeRecords ?? [];
-			return this.doUpdate(node, { changeRecords: recordsForNode });
+			return this.doUpdate(node, {
+				changeRecords: recordsForNode,
+				historySource
+			});
 		}));
 		if (updateData[0].oldNode?.type !== NodeType.ROOT) {
 			if (this.get("nodes").length) if (!doNotPushHistory) {
 				const pageForOp = this.getNodeInfo(nodes[0].id, false).page;
-				this.pushOpHistory("update", { updatedItems: updateData.map((d) => ({
-					oldNode: cloneDeep$1(d.oldNode),
-					newNode: cloneDeep$1(toRaw(d.newNode)),
-					changeRecords: d.changeRecords?.length ? cloneDeep$1(d.changeRecords) : void 0
-				})) }, {
-					name: pageForOp?.name || "",
-					id: pageForOp.id
-				}, historyDescription);
+				this.pushOpHistory("update", {
+					diff: buildUpdateDiff(updateData.map((d) => ({
+						oldNode: cloneDeep$1(d.oldNode),
+						newNode: cloneDeep$1(d.newNode),
+						changeRecords: d.changeRecords?.length ? cloneDeep$1(d.changeRecords) : void 0
+					}))),
+					pageData: {
+						name: pageForOp?.name || "",
+						id: pageForOp.id
+					},
+					historyDescription,
+					source: historySource
+				});
 			} else this.selectionBeforeOp = null;
 		}
 		this.emit("update", updateData);
@@ -496,7 +527,7 @@ var Editor = class extends BaseService {
 	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns void
 	*/
-	async sort(id1, id2, { doNotSelect = false, doNotPushHistory = false } = {}) {
+	async sort(id1, id2, { doNotSelect = false, doNotPushHistory = false, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const root = this.get("root");
 		if (!root) throw new Error("root为空");
@@ -508,7 +539,10 @@ var Editor = class extends BaseService {
 		if (index2 < 0) return;
 		const index1 = parent.items.findIndex((node) => `${node.id}` === `${id1}`);
 		parent.items.splice(index2, 0, ...parent.items.splice(index1, 1));
-		await this.update(parent, { doNotPushHistory });
+		await this.update(parent, {
+			doNotPushHistory,
+			historySource
+		});
 		if (!doNotSelect) await this.select(node);
 		this.get("stage")?.update({
 			config: cloneDeep$1(node),
@@ -544,7 +578,7 @@ var Editor = class extends BaseService {
 	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns 添加后的组件节点配置
 	*/
-	async paste(position = {}, collectorOptions, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false } = {}) {
+	async paste(position = {}, collectorOptions, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription, historySource } = {}) {
 		const config = storage_default.getItem(COPY_STORAGE_KEY);
 		if (!Array.isArray(config)) return;
 		const node = this.get("node");
@@ -558,7 +592,9 @@ var Editor = class extends BaseService {
 		return this.add(pasteConfigs, parent, {
 			doNotSelect,
 			doNotSwitchPage,
-			doNotPushHistory
+			doNotPushHistory,
+			historyDescription,
+			historySource
 		});
 	}
 	async doPaste(config, position = {}) {
@@ -586,11 +622,15 @@ var Editor = class extends BaseService {
 	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns 当前组件节点配置
 	*/
-	async alignCenter(config, { doNotSelect = false, doNotPushHistory = false } = {}) {
+	async alignCenter(config, { doNotSelect = false, doNotPushHistory = false, historyDescription, historySource } = {}) {
 		const nodes = Array.isArray(config) ? config : [config];
 		const stage = this.get("stage");
 		const newNodes = await Promise.all(nodes.map((node) => this.doAlignCenter(node)));
-		const newNode = await this.update(newNodes, { doNotPushHistory });
+		const newNode = await this.update(newNodes, {
+			doNotPushHistory,
+			historyDescription,
+			historySource
+		});
 		if (!doNotSelect) if (newNodes.length > 1) await stage?.multiSelect(newNodes.map((node) => node.id));
 		else await stage?.select(newNodes[0].id);
 		return newNode;
@@ -601,7 +641,7 @@ var Editor = class extends BaseService {
 	* @param options 可选配置
 	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	*/
-	async moveLayer(offset, { doNotPushHistory = false } = {}) {
+	async moveLayer(offset, { doNotPushHistory = false, historyDescription, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const root = this.get("root");
 		if (!root) throw new Error("root为空");
@@ -626,12 +666,17 @@ var Editor = class extends BaseService {
 		this.addModifiedNodeId(parent.id);
 		if (!doNotPushHistory) {
 			const pageForOp = this.getNodeInfo(node.id, false).page;
-			this.pushOpHistory("update", { updatedItems: [{
-				oldNode: oldParent,
-				newNode: cloneDeep$1(toRaw(parent))
-			}] }, {
-				name: pageForOp?.name || "",
-				id: pageForOp.id
+			this.pushOpHistory("update", {
+				diff: buildUpdateDiff([{
+					oldNode: oldParent,
+					newNode: cloneDeep$1(toRaw(parent))
+				}]),
+				pageData: {
+					name: pageForOp?.name || "",
+					id: pageForOp.id
+				},
+				historyDescription,
+				source: historySource
 			});
 		} else this.selectionBeforeOp = null;
 		this.emit("move-layer", offset);
@@ -650,7 +695,7 @@ var Editor = class extends BaseService {
 	* @param options.doNotSwitchPage 移动后是否不切换当前页面（默认 false；目标容器位于其它页面时为 true 会跳过自动选中以避免页面切换）
 	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	*/
-	async moveToContainer(config, targetId, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false } = {}) {
+	async moveToContainer(config, targetId, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription, historySource } = {}) {
 		const isBatch = Array.isArray(config);
 		const configs = (isBatch ? config : [config]).filter((item) => !(isPage(item) || isPageFragment(item)));
 		if (configs.length === 0) throw new Error("没有可移动的节点");
@@ -698,11 +743,16 @@ var Editor = class extends BaseService {
 				name: "",
 				id: target.id
 			};
-			this.pushOpHistory("update", { updatedItems }, historyPage);
+			this.pushOpHistory("update", {
+				diff: buildUpdateDiff(updatedItems),
+				pageData: historyPage,
+				historyDescription,
+				source: historySource
+			});
 		} else this.selectionBeforeOp = null;
 		return isBatch ? newConfigs : newConfigs[0];
 	}
-	async dragTo(config, targetParent, targetIndex, { doNotPushHistory = false } = {}) {
+	async dragTo(config, targetParent, targetIndex, { doNotPushHistory = false, historyDescription, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		if (!targetParent || !Array.isArray(targetParent.items)) return;
 		const configs = Array.isArray(config) ? config : [config];
@@ -744,9 +794,14 @@ var Editor = class extends BaseService {
 		}
 		if (!doNotPushHistory) {
 			const pageForOp = this.getNodeInfo(configs[0].id, false).page;
-			this.pushOpHistory("update", { updatedItems }, {
-				name: pageForOp?.name || "",
-				id: pageForOp.id
+			this.pushOpHistory("update", {
+				diff: buildUpdateDiff(updatedItems),
+				pageData: {
+					name: pageForOp?.name || "",
+					id: pageForOp.id
+				},
+				historyDescription,
+				source: historySource
 			});
 		} else this.selectionBeforeOp = null;
 		this.emit("drag-to", {
@@ -756,6 +811,49 @@ var Editor = class extends BaseService {
 		});
 	}
 	/**
+	* 下列 *AndGetHistoryId 方法与对应的普通操作（add / remove / update ...）行为完全一致，
+	* 唯一区别是返回值为本次写入历史栈的历史记录 uuid（{@link StepValue.uuid}），
+	* 而非节点 / 节点数组。可用于精确引用 / 定位该条历史记录（埋点、revert、跨端同步等）。
+	*
+	* 当本次操作未写入历史（doNotPushHistory 为 true、或操作无实际变更 / 提前返回）时返回 null。
+	*/
+	/** 等价于 {@link add}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+	async addAndGetHistoryId(addNode, parent, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.add(addNode, parent, options);
+		return this.lastPushedHistoryId;
+	}
+	/** 等价于 {@link remove}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+	async removeAndGetHistoryId(nodeOrNodeList, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.remove(nodeOrNodeList, options);
+		return this.lastPushedHistoryId;
+	}
+	/** 等价于 {@link update}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+	async updateAndGetHistoryId(config, data = {}) {
+		this.lastPushedHistoryId = null;
+		await this.update(config, data);
+		return this.lastPushedHistoryId;
+	}
+	/** 等价于 {@link moveLayer}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+	async moveLayerAndGetHistoryId(offset, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.moveLayer(offset, options);
+		return this.lastPushedHistoryId;
+	}
+	/** 等价于 {@link moveToContainer}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+	async moveToContainerAndGetHistoryId(config, targetId, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.moveToContainer(config, targetId, options);
+		return this.lastPushedHistoryId;
+	}
+	/** 等价于 {@link dragTo}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+	async dragToAndGetHistoryId(config, targetParent, targetIndex, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.dragTo(config, targetParent, targetIndex, options);
+		return this.lastPushedHistoryId;
+	}
+	/**
 	* 撤销当前操作
 	* @returns 被撤销的操作
 	*/
@@ -793,7 +891,12 @@ var Editor = class extends BaseService {
 		const entry = history_default.getPageStepList()[index];
 		if (!entry?.applied) return null;
 		const { step } = entry;
+		if (step.opType === "initial") return null;
 		if (!this.get("root")) return null;
+		if (step.opType === "update") {
+			const items = step.diff ?? [];
+			if (!items.length || !items.every((item) => item.changeRecords?.length)) return null;
+		}
 		let revertedStep = null;
 		const captureRevert = (s) => {
 			revertedStep = s;
@@ -803,28 +906,31 @@ var Editor = class extends BaseService {
 		const opts = {
 			doNotSelect: true,
 			doNotSwitchPage: true,
-			historyDescription
+			historyDescription,
+			historySource: "rollback"
 		};
 		try {
 			switch (step.opType) {
-				case "add": {
-					const nodes = step.nodes ?? [];
-					for (const n of nodes) {
-						const existing = this.getNodeById(n.id, false);
+				case "add":
+					for (const { newSchema } of step.diff ?? []) {
+						if (!newSchema) continue;
+						const existing = this.getNodeById(newSchema.id, false);
 						if (existing) await this.remove(existing, opts);
 					}
 					break;
-				}
 				case "remove": {
-					const sorted = [...step.removedItems ?? []].sort((a, b) => a.index - b.index);
-					for (const { node, parentId } of sorted) {
+					const sorted = [...step.diff ?? []].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+					for (const { oldSchema, parentId } of sorted) {
+						if (!oldSchema || parentId === void 0) continue;
 						const parent = this.getNodeById(parentId, false);
-						if (parent) await this.add([cloneDeep$1(node)], parent, opts);
+						if (parent) await this.add([cloneDeep$1(oldSchema)], parent, opts);
 					}
 					break;
 				}
 				case "update": {
-					const configs = (step.updatedItems ?? []).map(({ oldNode, newNode, changeRecords }) => {
+					const configs = (step.diff ?? []).filter((item) => item.oldSchema && item.newSchema).map(({ oldSchema, newSchema, changeRecords }) => {
+						const oldNode = oldSchema;
+						const newNode = newSchema;
 						if (changeRecords?.length) {
 							const patch = {
 								id: newNode.id,
@@ -839,7 +945,10 @@ var Editor = class extends BaseService {
 						}
 						return cloneDeep$1(oldNode);
 					});
-					if (configs.length) await this.update(configs, { historyDescription });
+					if (configs.length) await this.update(configs, {
+						historyDescription,
+						historySource: "rollback"
+					});
 					break;
 				}
 			}
@@ -851,6 +960,19 @@ var Editor = class extends BaseService {
 		return revertedStep;
 	}
 	/**
+	* 通过历史记录 uuid 回滚当前页面的某条历史步骤，语义与 {@link revertPageStep} 完全一致，
+	* 仅入参从 index 改为 uuid（{@link StepValue.uuid}）。uuid 不随栈内步骤增删而变化，
+	* 更适合业务侧持有引用后再回滚（埋点、跨端同步等场景）。
+	*
+	* @param uuid 目标历史记录的 uuid，通常由 *AndGetHistoryId 方法返回
+	* @returns 反向后产生的新 step；找不到对应 uuid / 未应用 / 反向失败时返回 null
+	*/
+	async revertPageStepById(uuid) {
+		const index = history_default.getPageStepIndexByUuid(uuid);
+		if (index < 0) return null;
+		return this.revertPageStep(index);
+	}
+	/**
 	* 跳转当前页面历史栈到指定游标位置。
 	*
 	* `targetCursor` 与 `UndoRedo.getCursor()` 同义：表示"已应用步骤数量"，
@@ -873,7 +995,7 @@ var Editor = class extends BaseService {
 		}
 		return cursor;
 	}
-	async move(left, top, { doNotPushHistory = false } = {}) {
+	async move(left, top, { doNotPushHistory = false, historyDescription, historySource } = {}) {
 		const node = toRaw(this.get("node"));
 		if (!node || isPage(node)) return;
 		const newStyle = calcMoveStyle(node.style || {}, left, top);
@@ -882,7 +1004,11 @@ var Editor = class extends BaseService {
 			id: node.id,
 			type: node.type,
 			style: newStyle
-		}, { doNotPushHistory });
+		}, {
+			doNotPushHistory,
+			historyDescription,
+			historySource
+		});
 	}
 	resetState() {
 		this.set("root", null);
@@ -922,18 +1048,83 @@ var Editor = class extends BaseService {
 		if (this.selectionBeforeOp) return;
 		this.selectionBeforeOp = this.get("nodes").map((n) => n.id);
 	}
-	pushOpHistory(opType, extra, pageData, historyDescription) {
+	/**
+	* 比较「上一次 root」与「新 root」的页面 / 页面片，按页面粒度把整体替换拆成历史记录：
+	* - 新旧都存在且内容变化的页面 → 一条 `update`（整页快照替换，无 changeRecords）；
+	* - 仅新 root 存在的页面 → 一条 `add`；
+	* - 仅旧 root 存在的页面 → 一条 `remove`。
+	*
+	* 每条记录落到对应页面自己的历史栈（与普通节点操作一致），并标记来源 `source`。
+	* 内容未变化的页面不产生记录，避免重复设置相同 DSL 时产生噪声。
+	*/
+	pushRootDiffHistory(preRoot, nextRoot, source) {
+		const prevPages = preRoot?.items || [];
+		const nextPages = nextRoot?.items || [];
+		const prevMap = new Map(prevPages.map((p) => [`${p.id}`, p]));
+		const nextMap = new Map(nextPages.map((p) => [`${p.id}`, p]));
+		const indexInItems = (root, id) => (root.items ?? []).findIndex((item) => `${item.id}` === `${id}`);
+		nextPages.forEach((nextPage) => {
+			const prevPage = prevMap.get(`${nextPage.id}`);
+			if (!prevPage) this.pushPageDiffStep("add", nextPage, {
+				newSchema: cloneDeep$1(toRaw(nextPage)),
+				parentId: nextRoot.id,
+				index: indexInItems(nextRoot, nextPage.id)
+			}, source);
+			else if (!isEqual(toRaw(prevPage), toRaw(nextPage))) this.pushPageDiffStep("update", nextPage, {
+				oldSchema: cloneDeep$1(toRaw(prevPage)),
+				newSchema: cloneDeep$1(toRaw(nextPage))
+			}, source);
+		});
+		prevPages.forEach((prevPage) => {
+			if (!nextMap.has(`${prevPage.id}`)) this.pushPageDiffStep("remove", prevPage, {
+				oldSchema: cloneDeep$1(toRaw(prevPage)),
+				parentId: preRoot.id,
+				index: indexInItems(preRoot, prevPage.id)
+			}, source);
+		});
+	}
+	/**
+	* 构造一条页面级「set root」历史记录（不携带选区 / modifiedNodeIds 上下文）并落到该页面自己的栈。
+	*
+	* 连续 set root 替换：若该页栈最新一条已是**同来源**的 set root 记录（{@link StepValue.rootStep} 且 `source` 相同），
+	* 则用本次记录**替换**它而非新增，避免源码反复保存 / 外部重设 DSL 时堆积多条 root 记录；
+	* 来源不同则照常新增（initial 基线不是 rootStep，不在此列）。
+	*/
+	pushPageDiffStep(opType, page, diffItem, source) {
+		const step = {
+			uuid: guid(),
+			data: {
+				name: page.name || "",
+				id: page.id
+			},
+			opType,
+			selectedBefore: [],
+			selectedAfter: [],
+			modifiedNodeIds: /* @__PURE__ */ new Map(),
+			diff: [diffItem],
+			rootStep: true
+		};
+		if (source) step.source = source;
+		const top = history_default.getCurrentPageStep(page.id);
+		if (top?.rootStep && top.source === source) history_default.replaceCurrentPageStep(step, page.id);
+		else history_default.push(step, page.id);
+	}
+	pushOpHistory(opType, { diff, pageData, historyDescription, source }) {
 		const step = {
+			uuid: guid(),
 			data: pageData,
 			opType,
 			selectedBefore: this.selectionBeforeOp ?? [],
 			selectedAfter: this.get("nodes").map((n) => n.id),
 			modifiedNodeIds: new Map(this.get("modifiedNodeIds")),
-			...extra
+			diff
 		};
 		if (historyDescription) step.historyDescription = historyDescription;
-		history_default.push(step, pageData.id);
+		if (source) step.source = source;
+		const historyId = history_default.push(step, pageData.id) ? step.uuid : null;
+		this.lastPushedHistoryId = historyId;
 		this.selectionBeforeOp = null;
+		return historyId;
 	}
 	/**
 	* 应用历史操作（撤销 / 重做）
@@ -948,6 +1139,7 @@ var Editor = class extends BaseService {
 	* @param reverse true = 撤销，false = 重做
 	*/
 	async applyHistoryOp(step, reverse) {
+		if (step.opType === "initial") return;
 		const root = this.get("root");
 		const stage = this.get("stage");
 		if (!root) return;
@@ -958,56 +1150,59 @@ var Editor = class extends BaseService {
 		};
 		switch (step.opType) {
 			case "add": {
-				const nodes = step.nodes ?? [];
-				if (reverse) for (const n of nodes) {
-					const existing = this.getNodeById(n.id, false);
+				const items = step.diff ?? [];
+				if (reverse) for (const { newSchema } of items) {
+					if (!newSchema) continue;
+					const existing = this.getNodeById(newSchema.id, false);
 					if (existing) await this.remove(existing, commonOpts);
 				}
 				else {
-					const parent = this.getNodeById(step.parentId, false);
-					if (parent) {
-						const sorted = [...nodes].sort((a, b) => (step.indexMap?.[a.id] ?? 0) - (step.indexMap?.[b.id] ?? 0));
-						for (const n of sorted) {
-							const idx = step.indexMap?.[n.id];
-							if (parent.items) {
-								if (typeof idx === "number" && idx >= 0 && idx < parent.items.length) parent.items.splice(idx, 0, cloneDeep$1(n));
-								else parent.items.push(cloneDeep$1(n));
-								await stage?.add({
-									config: cloneDeep$1(n),
-									parent: cloneDeep$1(parent),
-									parentId: parent.id,
-									root: cloneDeep$1(root)
-								});
-							}
+					const sorted = [...items].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+					for (const { newSchema, parentId, index } of sorted) {
+						if (!newSchema || parentId === void 0) continue;
+						const parent = this.getNodeById(parentId, false);
+						if (parent?.items) {
+							if (typeof index === "number" && index >= 0 && index < parent.items.length) parent.items.splice(index, 0, cloneDeep$1(newSchema));
+							else parent.items.push(cloneDeep$1(newSchema));
+							await stage?.add({
+								config: cloneDeep$1(newSchema),
+								parent: cloneDeep$1(parent),
+								parentId: parent.id,
+								root: cloneDeep$1(root)
+							});
 						}
 					}
 				}
 				break;
 			}
 			case "remove": {
-				const items = step.removedItems ?? [];
+				const items = step.diff ?? [];
 				if (reverse) {
-					const sorted = [...items].sort((a, b) => a.index - b.index);
-					for (const { node, parentId, index } of sorted) {
+					const sorted = [...items].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+					for (const { oldSchema, parentId, index } of sorted) {
+						if (!oldSchema || parentId === void 0) continue;
 						const parent = this.getNodeById(parentId, false);
 						if (parent?.items) {
-							parent.items.splice(index, 0, cloneDeep$1(node));
+							parent.items.splice(index ?? parent.items.length, 0, cloneDeep$1(oldSchema));
 							await stage?.add({
-								config: cloneDeep$1(node),
+								config: cloneDeep$1(oldSchema),
 								parent: cloneDeep$1(parent),
 								parentId,
 								root: cloneDeep$1(root)
 							});
 						}
 					}
-				} else for (const { node } of items) {
-					const existing = this.getNodeById(node.id, false);
+				} else for (const { oldSchema } of items) {
+					if (!oldSchema) continue;
+					const existing = this.getNodeById(oldSchema.id, false);
 					if (existing) await this.remove(existing, commonOpts);
 				}
 				break;
 			}
 			case "update": {
-				const configs = (step.updatedItems ?? []).map(({ oldNode, newNode, changeRecords }) => {
+				const configs = (step.diff ?? []).filter((item) => item.oldSchema && item.newSchema).map(({ oldSchema, newSchema, changeRecords }) => {
+					const oldNode = oldSchema;
+					const newNode = newSchema;
 					if (changeRecords?.length) {
 						const sourceForValues = reverse ? oldNode : newNode;
 						const patch = {