@tmagic/editor 1.8.0-beta.1 → 1.8.0-beta.10

package/dist/es/services/editor.js

@@ -1,35 +1,28 @@
 import { Layout, canUsePluginMethods } from "../type.js";
-import BaseService_default from "./BaseService.js";
+import BaseService from "./BaseService.js";
 import props_default from "./props.js";
+import { getLastPushedHistoryIds } from "../utils/history.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 { applyHistoryAddOp, applyHistoryRemoveOp, applyHistoryUpdateOp } from "../utils/editor-history.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, isPage, isPageFragment } 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, 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
 /**
-* 经过 BaseService 的插件 / 中间件包装后，源方法的最后一个形参可能被注入为 dispatch 函数
-* 当 options 形参位置被注入为函数（或为 null）时，将其归一为空对象，避免后续逻辑误读
+* 把「变更前后节点快照」列表归一成 update 类型的 {@link StepDiffItem} 列表，供 {@link StepValue.diff} 使用。
+* `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
+* 缺省（未传 / 空数组）才退化为整节点替换。
 */
-var safeOptions = (options) => {
-	const empty = {};
-	if (!options || typeof options === "function") return empty;
-	return options;
-};
-/**
-* 经过 BaseService 的插件 / 中间件包装后，源方法的形参可能被注入为 dispatch 函数
-* 当 parent 形参位置被注入为函数（或为空值）时，归一为 null，由调用方继续走默认 parent 逻辑
-*/
-var safeParent = (parent) => {
-	if (!parent || typeof parent === "function") return null;
-	return parent;
-};
-var Editor = class extends BaseService_default {
+var buildUpdateDiff = (items) => items.map(({ oldNode, newNode, changeRecords }) => ({
+	oldSchema: oldNode,
+	newSchema: newNode,
+	...changeRecords?.length ? { changeRecords } : {}
+}));
+var Editor = class extends BaseService {
 	state = reactive({
 		root: null,
 		page: null,
@@ -45,8 +38,13 @@ var Editor = class extends BaseService_default {
 		disabledMultiSelect: false,
 		alwaysMultiSelect: false
 	});
-	isHistoryStateChange = false;
 	selectionBeforeOp = null;
+	/**
+	* 最近一次 pushOpHistory 写入的历史记录 uuid。
+	* 供 *AndGetHistoryId 系列方法在调用普通操作后取回本次产生的历史记录 id；
+	* 普通操作不会读取它，调用前由 *AndGetHistoryId 重置为 null。
+	*/
+	lastPushedHistoryId = null;
 	constructor() {
 		super(canUsePluginMethods.async.map((methodName) => ({
 			name: methodName,
@@ -61,8 +59,9 @@ var Editor = class extends BaseService_default {
 	* 设置当前指点节点配置
 	* @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]);
@@ -73,12 +72,19 @@ var Editor = class extends BaseService_default {
 				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.getMarker("page", pageNode.id)) history_default.setMarker("page", pageNode.id, {
+						name: pageNode.name,
+						source: options.historySource
+					});
+				});
 			} else {
 				this.state.pageLength = 0;
 				this.state.pageFragmentLength = 0;
 				this.state.stageLoading = false;
 			}
-			this.emit("root-change", value, preValue);
+			this.emit("root-change", value, preValue, options);
 		}
 	}
 	/**
@@ -98,7 +104,25 @@ var Editor = class extends BaseService_default {
 	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,
+			path: []
+		};
+		if (id === root.id) return {
+			node: root,
+			parent: null,
+			page: null,
+			path: []
+		};
+		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获取指点节点配置
@@ -137,7 +161,7 @@ var Editor = class extends BaseService_default {
 	* 只有容器拥有布局
 	*/
 	async getLayout(parent, node) {
-		if (node && typeof node !== "function" && isFixed(node.style || {})) return Layout.FIXED;
+		if (node && isFixed(node.style || {})) return Layout.FIXED;
 		if (parent.layout) return parent.layout;
 		if (!parent.style?.position) return Layout.RELATIVE;
 		return Layout.ABSOLUTE;
@@ -152,8 +176,6 @@ var Editor = class extends BaseService_default {
 		this.set("nodes", node ? [node] : []);
 		this.set("page", page);
 		this.set("parent", parent);
-		if (page) history_default.changePage(toRaw(page));
-		else history_default.resetState();
 		if (node?.id) this.get("stage")?.renderer?.runtime?.getApp?.()?.page?.emit("editor:select", {
 			node,
 			page,
@@ -231,18 +253,18 @@ var Editor = class extends BaseService_default {
 		const layout = await this.getLayout(toRaw(parent), node);
 		node.style = getInitPositionStyle(node.style, layout);
 		await stage?.add({
-			config: cloneDeep(node),
-			parent: cloneDeep(parent),
+			config: cloneDeep$1(node),
+			parent: cloneDeep$1(parent),
 			parentId: parent.id,
-			root: cloneDeep(root)
+			root: cloneDeep$1(root)
 		});
 		const newStyle = fixNodePosition(node, parent, stage);
 		if (newStyle && (newStyle.top !== node.style.top || newStyle.left !== node.style.left)) {
 			node.style = newStyle;
 			await stage?.update({
-				config: cloneDeep(node),
+				config: cloneDeep$1(node),
 				parentId: parent.id,
-				root: cloneDeep(root)
+				root: cloneDeep$1(root)
 			});
 		}
 		this.addModifiedNodeId(node.id);
@@ -255,11 +277,10 @@ var Editor = class extends BaseService_default {
 	* @param options 可选配置
 	* @param options.doNotSelect 添加后是否不更新当前选中节点（默认 false，添加后会选中新增的节点）
 	* @param options.doNotSwitchPage 添加后是否不切换当前页面（默认 false；新增页面 / 跨页新增时为 true 会跳过会引发页面切换的选中操作）
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns 添加后的节点
 	*/
-	async add(addNode, parent, options) {
-		const safeParentNode = safeParent(parent);
-		const { doNotSelect = false, doNotSwitchPage = false } = safeOptions(options);
+	async add(addNode, parent, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const stage = this.get("stage");
 		const addNodes = [];
@@ -271,7 +292,7 @@ var Editor = class extends BaseService_default {
 		const newNodes = await Promise.all(addNodes.map((node) => {
 			const root = this.get("root");
 			if ((isPage(node) || isPageFragment(node)) && root) return this.doAdd(node, root);
-			const parentNode = safeParentNode ?? getAddParent(node);
+			const parentNode = parent ?? getAddParent(node);
 			if (!parentNode) throw new Error("未找到父元素");
 			return this.doAdd(node, parentNode);
 		}));
@@ -292,23 +313,38 @@ var Editor = class extends BaseService_default {
 		}
 		if (!(isPage(newNodes[0]) || isPageFragment(newNodes[0]))) {
 			const pageForOp = this.getNodeInfo(newNodes[0].id, false).page;
-			this.pushOpHistory("add", {
-				nodes: newNodes.map((n) => cloneDeep(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
-			});
+			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);
+		this.emit("change", {
+			type: "add",
+			data: newNodes.map((node) => ({
+				node,
+				page: this.getPageOfNode(node.id)
+			}))
+		});
 		return Array.isArray(addNode) ? newNodes : newNodes[0];
 	}
-	async doRemove(node, options) {
-		const { doNotSelect = false, doNotSwitchPage = false } = safeOptions(options);
+	async doRemove(node, { doNotSelect = false, doNotSwitchPage = false } = {}) {
 		const root = this.get("root");
 		if (!root) throw new Error("root不能为空");
 		const { parent, node: curNode } = this.getNodeInfo(node.id, false);
@@ -320,7 +356,7 @@ var Editor = class extends BaseService_default {
 		stage?.remove({
 			id: node.id,
 			parentId: parent.id,
-			root: cloneDeep(root)
+			root: cloneDeep$1(root)
 		});
 		const selectedNodes = this.get("nodes");
 		const removedSelectedIndex = selectedNodes.findIndex((n) => `${n.id}` === `${node.id}`);
@@ -337,10 +373,7 @@ var Editor = class extends BaseService_default {
 			if (pages[0]) {
 				await this.select(pages[0]);
 				stage?.select(pages[0].id);
-			} else {
-				this.selectRoot();
-				history_default.resetPage();
-			}
+			} else this.selectRoot();
 		};
 		const rootItems = root.items || [];
 		if (isPage(node)) {
@@ -367,11 +400,15 @@ var Editor = class extends BaseService_default {
 	* @param options 可选配置
 	* @param options.doNotSelect 删除后是否不更新当前选中节点（默认 false，删除后会选中父节点或首个页面）
 	* @param options.doNotSwitchPage 删除后是否不切换当前页面（默认 false；删除页面 / 页面片段时为 true 会跳过自动切换到首个剩余页面）
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	*/
-	async remove(nodeOrNodeList, options) {
-		const { doNotSelect = false, doNotSwitchPage = false } = safeOptions(options);
+	async remove(nodeOrNodeList, { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const nodes = Array.isArray(nodeOrNodeList) ? nodeOrNodeList : [nodeOrNodeList];
+		const changeItems = nodes.map((node) => ({
+			node,
+			page: this.getPageOfNode(node.id)
+		}));
 		const removedItems = [];
 		let pageForOp = null;
 		if (!(isPage(nodes[0]) || isPageFragment(nodes[0]))) for (const n of nodes) {
@@ -383,7 +420,7 @@ var Editor = class extends BaseService_default {
 				};
 				const idx = getNodeIndex(curNode.id, parent);
 				removedItems.push({
-					node: cloneDeep(toRaw(curNode)),
+					oldSchema: cloneDeep$1(toRaw(curNode)),
 					parentId: parent.id,
 					index: typeof idx === "number" ? idx : -1
 				});
@@ -393,21 +430,30 @@ var Editor = class extends BaseService_default {
 			doNotSelect,
 			doNotSwitchPage
 		})));
-		if (removedItems.length > 0 && pageForOp) this.pushOpHistory("remove", { removedItems }, pageForOp);
+		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);
+		this.emit("change", {
+			type: "remove",
+			data: changeItems
+		});
 	}
-	async doUpdate(config, { changeRecords = [] } = {}) {
-		const root = this.get("root");
-		if (!root) throw new Error("root为空");
+	async doUpdate(config, { changeRecords = [], historySource } = {}) {
+		if (!this.get("root")) throw new Error("root为空");
 		if (!config?.id) throw new Error("没有配置或者配置缺少id值");
 		const info = this.getNodeInfo(config.id, false);
 		if (!info.node) throw new Error(`获取不到id为${config.id}的节点`);
 		const node = toRaw(info.node);
-		let newConfig = await toggleFixedPosition(toRaw(config), node, root, this.getLayout);
-		newConfig = mergeWith(cloneDeep(node), newConfig, editorNodeMergeCustomizer);
+		let newConfig = await toggleFixedPosition(toRaw(config), node, info.path, this.getLayout);
+		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,
@@ -444,27 +490,50 @@ var Editor = class extends BaseService_default {
 	* 更新节点
 	* update后会触发依赖收集，收集完后会掉stage.update方法
 	* @param config 新的节点配置，配置中需要有id信息
+	* @param data 额外数据
+	* @param data.changeRecords 单节点 form 端变更记录（多节点场景下被忽略，使用 changeRecordList）
+	* @param data.changeRecordList 多节点 form 端变更记录列表，按 config 数组同序对应每个节点；优先级高于 changeRecords
+	* @param data.doNotPushHistory 是否不写入历史记录（默认 false）
+	* @param data.historyDescription 入栈时附带的人类可读描述，用于历史面板展示（不影响 undo/redo 行为）
 	* @returns 更新后的节点配置
 	*/
 	async update(config, data = {}) {
 		this.captureSelectionBeforeOp();
+		const { doNotPushHistory = false, changeRecordList, changeRecords, historyDescription, historySource } = data;
 		const nodes = Array.isArray(config) ? config : [config];
-		const updateData = await Promise.all(nodes.map((node) => this.doUpdate(node, data)));
+		const updateData = await Promise.all(nodes.map((node, index) => {
+			const recordsForNode = changeRecordList ? changeRecordList[index] ?? [] : changeRecords ?? [];
+			return this.doUpdate(node, {
+				changeRecords: recordsForNode,
+				historySource
+			});
+		}));
 		if (updateData[0].oldNode?.type !== NodeType.ROOT) {
-			const curNodes = this.get("nodes");
-			if (!this.isHistoryStateChange && curNodes.length) {
+			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(d.oldNode),
-					newNode: cloneDeep(toRaw(d.newNode))
-				})) }, {
-					name: pageForOp?.name || "",
-					id: pageForOp.id
+				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
 				});
-			}
-			this.isHistoryStateChange = false;
+			} else this.selectionBeforeOp = null;
 		}
 		this.emit("update", updateData);
+		this.emit("change", {
+			type: "update",
+			data: updateData.map((node) => ({
+				node,
+				page: this.getPageOfNode(node.newNode.id)
+			}))
+		});
 		return Array.isArray(config) ? updateData.map((item) => item.newNode) : updateData[0].newNode;
 	}
 	/**
@@ -474,27 +543,30 @@ var Editor = class extends BaseService_default {
 	* @param options 可选配置
 	* @param options.doNotSelect 排序后是否不更新当前选中节点（默认 false）
 	* @param options.doNotSwitchPage 排序后是否不切换当前页面（排序只发生在同一父节点内，方法内为空操作；保留以与其它 DSL 操作 API 一致）
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns void
 	*/
-	async sort(id1, id2, options) {
-		const { doNotSelect = false } = safeOptions(options);
+	async sort(id1, id2, { doNotSelect = false, doNotPushHistory = false, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const root = this.get("root");
 		if (!root) throw new Error("root为空");
 		const node = this.get("node");
 		if (!node) throw new Error("当前节点为空");
-		const parent = cloneDeep(toRaw(this.get("parent")));
+		const parent = cloneDeep$1(toRaw(this.get("parent")));
 		if (!parent) throw new Error("父节点为空");
 		const index2 = parent.items.findIndex((node) => `${node.id}` === `${id2}`);
 		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);
+		await this.update(parent, {
+			doNotPushHistory,
+			historySource
+		});
 		if (!doNotSelect) await this.select(node);
 		this.get("stage")?.update({
-			config: cloneDeep(node),
+			config: cloneDeep$1(node),
 			parentId: parent.id,
-			root: cloneDeep(root)
+			root: cloneDeep$1(root)
 		});
 	}
 	/**
@@ -522,10 +594,10 @@ var Editor = class extends BaseService_default {
 	* @param options 可选配置
 	* @param options.doNotSelect 粘贴后是否不更新当前选中节点（默认 false）
 	* @param options.doNotSwitchPage 粘贴后是否不切换当前页面（默认 false；跨页粘贴时为 true 会跳过页面切换）
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns 添加后的组件节点配置
 	*/
-	async paste(position = {}, collectorOptions, options) {
-		const { doNotSelect = false, doNotSwitchPage = false } = safeOptions(options);
+	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");
@@ -538,18 +610,21 @@ var Editor = class extends BaseService_default {
 		if (collectorOptions && typeof collectorOptions.isTarget === "function") props_default.replaceRelateId(config, pasteConfigs, collectorOptions);
 		return this.add(pasteConfigs, parent, {
 			doNotSelect,
-			doNotSwitchPage
+			doNotSwitchPage,
+			doNotPushHistory,
+			historyDescription,
+			historySource
 		});
 	}
 	async doPaste(config, position = {}) {
 		props_default.clearRelateId();
 		const doc = this.get("stage")?.renderer?.contentWindow?.document;
-		return beforePaste(position, cloneDeep(config), doc);
+		return beforePaste(position, cloneDeep$1(config), doc);
 	}
 	async doAlignCenter(config) {
 		const parent = this.getParentById(config.id);
 		if (!parent) throw new Error("找不到父节点");
-		const node = cloneDeep(toRaw(config));
+		const node = cloneDeep$1(toRaw(config));
 		const layout = await this.getLayout(parent, node);
 		const doc = this.get("stage")?.renderer?.contentWindow?.document;
 		const newStyle = calcAlignCenterStyle(node, parent, layout, doc);
@@ -563,14 +638,18 @@ var Editor = class extends BaseService_default {
 	* @param options 可选配置
 	* @param options.doNotSelect 居中后是否不更新当前选中节点（默认 false）
 	* @param options.doNotSwitchPage 居中后是否不切换当前页面（居中只更新节点 style，方法内为空操作；保留以与其它 DSL 操作 API 一致）
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	* @returns 当前组件节点配置
 	*/
-	async alignCenter(config, options) {
-		const { doNotSelect = false } = safeOptions(options);
+	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);
+		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;
@@ -578,8 +657,10 @@ var Editor = class extends BaseService_default {
 	/**
 	* 移动当前选中节点位置
 	* @param offset 偏移量
+	* @param options 可选配置
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	*/
-	async moveLayer(offset) {
+	async moveLayer(offset, { doNotPushHistory = false, historyDescription, historySource } = {}) {
 		this.captureSelectionBeforeOp();
 		const root = this.get("root");
 		if (!root) throw new Error("root为空");
@@ -592,95 +673,122 @@ var Editor = class extends BaseService_default {
 		const isRelative = await this.getLayout(parent, node) === Layout.RELATIVE;
 		const offsetIndex = calcLayerTargetIndex(index, offset, brothers.length, isRelative);
 		if (offsetIndex > 0 && offsetIndex > brothers.length || offsetIndex < 0) return;
-		const oldParent = cloneDeep(toRaw(parent));
+		const oldParent = cloneDeep$1(toRaw(parent));
 		brothers.splice(index, 1);
 		brothers.splice(offsetIndex, 0, node);
 		const grandparent = this.getParentById(parent.id);
 		this.get("stage")?.update({
-			config: cloneDeep(toRaw(parent)),
+			config: cloneDeep$1(toRaw(parent)),
 			parentId: grandparent?.id,
-			root: cloneDeep(root)
+			root: cloneDeep$1(root)
 		});
 		this.addModifiedNodeId(parent.id);
-		const pageForOp = this.getNodeInfo(node.id, false).page;
-		this.pushOpHistory("update", { updatedItems: [{
-			oldNode: oldParent,
-			newNode: cloneDeep(toRaw(parent))
-		}] }, {
-			name: pageForOp?.name || "",
-			id: pageForOp.id
-		});
+		if (!doNotPushHistory) {
+			const pageForOp = this.getNodeInfo(node.id, false).page;
+			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);
+		this.emit("change", {
+			type: "move-layer",
+			data: [{
+				node,
+				page: this.getPageOfNode(node.id)
+			}],
+			offset
+		});
 	}
 	/**
-	* 移动到指定容器中
-	* @param config 需要移动的节点
+	* 移动一个或多个节点到指定容器中。
+	*
+	* 多选场景（config 是数组）只会产生一条历史记录，
+	* `updatedItems` 涵盖所有源父容器 + 目标容器的前后快照。
+	* 这避免了"多选移动到某容器"在历史栈里被切成 N 条记录。
+	*
+	* @param config 需要移动的节点（或节点数组，各项需带 id；style 等字段会与原节点合并）
 	* @param targetId 容器ID
 	* @param options 可选配置
 	* @param options.doNotSelect 移动后是否不更新当前选中节点（默认 false）
 	* @param options.doNotSwitchPage 移动后是否不切换当前页面（默认 false；目标容器位于其它页面时为 true 会跳过自动选中以避免页面切换）
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	*/
-	async moveToContainer(config, targetId, options) {
-		const { doNotSelect = false, doNotSwitchPage = false } = safeOptions(options);
+	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("没有可移动的节点");
 		this.captureSelectionBeforeOp();
-		const root = this.get("root");
-		const { node, parent, page: pageForOp } = this.getNodeInfo(config.id, false);
 		const target = this.getNodeById(targetId, false);
+		if (!target) throw new Error("目标容器不存在");
+		const root = this.get("root");
 		const stage = this.get("stage");
-		if (root && node && parent && stage) {
-			const oldSourceParent = cloneDeep(toRaw(parent));
-			const oldTarget = cloneDeep(toRaw(target));
-			const index = getNodeIndex(node.id, parent);
-			parent.items?.splice(index, 1);
-			await stage.remove({
-				id: node.id,
-				parentId: parent.id,
-				root: cloneDeep(root)
-			});
-			const layout = await this.getLayout(target);
-			const newConfig = mergeWith(cloneDeep(node), config, (_objValue, srcValue) => {
-				if (Array.isArray(srcValue)) return srcValue;
-			});
-			newConfig.style = getInitPositionStyle(newConfig.style, layout);
-			target.items.push(newConfig);
-			const targetWouldSwitchPage = this.isOnDifferentPage(target);
-			const skipSelect = doNotSelect || doNotSwitchPage && targetWouldSwitchPage;
-			if (!skipSelect) await stage.select(targetId);
-			const targetParent = this.getParentById(target.id);
-			await stage.update({
-				config: cloneDeep(target),
-				parentId: targetParent?.id,
-				root: cloneDeep(root)
-			});
-			if (!skipSelect) {
-				await this.select(newConfig);
-				stage.select(newConfig.id);
-			}
-			this.addModifiedNodeId(target.id);
-			this.addModifiedNodeId(parent.id);
-			this.pushOpHistory("update", { updatedItems: [{
-				oldNode: oldSourceParent,
-				newNode: cloneDeep(toRaw(parent))
-			}, {
-				oldNode: oldTarget,
-				newNode: cloneDeep(toRaw(target))
-			}] }, {
-				name: pageForOp?.name || "",
-				id: pageForOp.id
+		if (!root || !stage) throw new Error("root 或 stage为空");
+		const moves = [];
+		for (const { id } of configs) {
+			const { node, parent, page } = this.getNodeInfo(id, false);
+			if (!node || !parent) continue;
+			moves.push({
+				node,
+				parent,
+				pageForOp: page ? {
+					name: page.name || "",
+					id: page.id
+				} : null
 			});
-			return newConfig;
 		}
+		if (moves.length === 0) throw new Error("没有可移动的节点");
+		const beforeSnapshots = /* @__PURE__ */ new Map();
+		beforeSnapshots.set(target.id, cloneDeep$1(toRaw(target)));
+		for (const { parent } of moves) if (!beforeSnapshots.has(parent.id)) beforeSnapshots.set(parent.id, cloneDeep$1(toRaw(parent)));
+		let newConfigs = [];
+		const moveNodes = moves.map(({ node }) => node);
+		await this.remove(moveNodes, {
+			doNotPushHistory: true,
+			doNotSelect,
+			doNotSwitchPage: true
+		});
+		newConfigs = await this.add(moveNodes, target, {
+			doNotPushHistory: true,
+			doNotSelect,
+			doNotSwitchPage
+		});
+		if (!doNotPushHistory) {
+			const updatedItems = Array.from(beforeSnapshots.entries()).map(([id, oldNode]) => ({
+				oldNode,
+				newNode: cloneDeep$1(toRaw(this.getNodeById(id, false)))
+			}));
+			const historyPage = moves[0].pageForOp ?? {
+				name: "",
+				id: target.id
+			};
+			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) {
+	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];
 		const beforeSnapshots = /* @__PURE__ */ new Map();
 		for (const cfg of configs) {
 			const { parent } = this.getNodeInfo(cfg.id, false);
-			if (parent && !beforeSnapshots.has(`${parent.id}`)) beforeSnapshots.set(`${parent.id}`, cloneDeep(toRaw(parent)));
+			if (parent && !beforeSnapshots.has(`${parent.id}`)) beforeSnapshots.set(`${parent.id}`, cloneDeep$1(toRaw(parent)));
 		}
-		if (!beforeSnapshots.has(`${targetParent.id}`)) beforeSnapshots.set(`${targetParent.id}`, cloneDeep(toRaw(targetParent)));
+		if (!beforeSnapshots.has(`${targetParent.id}`)) beforeSnapshots.set(`${targetParent.id}`, cloneDeep$1(toRaw(targetParent)));
 		const newLayout = await this.getLayout(targetParent);
 		const { sameParentIndices, crossParentConfigs, aborted } = classifyDragSources(configs, targetParent, (id, raw) => this.getNodeInfo(id, raw));
 		if (aborted) return;
@@ -699,35 +807,111 @@ var Editor = class extends BaseService_default {
 		const root = this.get("root");
 		const stage = this.get("stage");
 		if (stage && page && root) stage.update({
-			config: cloneDeep(page),
+			config: cloneDeep$1(page),
 			parentId: root.id,
-			root: cloneDeep(root)
+			root: cloneDeep$1(root)
 		});
 		const updatedItems = [];
 		for (const oldNode of beforeSnapshots.values()) {
 			const newNode = this.getNodeById(oldNode.id, false);
 			if (newNode) updatedItems.push({
 				oldNode,
-				newNode: cloneDeep(toRaw(newNode))
+				newNode: cloneDeep$1(toRaw(newNode))
 			});
 		}
-		const pageForOp = this.getNodeInfo(configs[0].id, false).page;
-		this.pushOpHistory("update", { updatedItems }, {
-			name: pageForOp?.name || "",
-			id: pageForOp.id
-		});
+		if (!doNotPushHistory) {
+			const pageForOp = this.getNodeInfo(configs[0].id, false).page;
+			this.pushOpHistory("update", {
+				diff: buildUpdateDiff(updatedItems),
+				pageData: {
+					name: pageForOp?.name || "",
+					id: pageForOp.id
+				},
+				historyDescription,
+				source: historySource
+			});
+		} else this.selectionBeforeOp = null;
 		this.emit("drag-to", {
 			targetIndex,
 			configs,
 			targetParent
 		});
+		this.emit("change", {
+			type: "drag-to",
+			data: configs.map((node) => ({
+				node,
+				page: this.getPageOfNode(node.id)
+			})),
+			targetIndex,
+			targetParent
+		});
+	}
+	/**
+	* 下列 *AndGetHistoryId 方法与对应的普通操作（add / remove / update ...）行为完全一致，
+	* 返回值在 {@link DslOpWithHistoryIdsResult} 中同时包含原操作结果与本次写入历史栈的 uuid 列表（{@link StepValue.uuid}），
+	* 可用于精确引用 / 定位该条历史记录（埋点、revert、跨端同步等）。
+	*
+	* 当本次操作未写入历史（doNotPushHistory 为 true、或操作无实际变更 / 提前返回）时 historyIds 为 `[]`。
+	*/
+	/** 等价于 {@link add}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+	async addAndGetHistoryId(addNode, parent, options = {}) {
+		this.lastPushedHistoryId = null;
+		return {
+			result: await this.add(addNode, parent, options),
+			historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId)
+		};
+	}
+	/** 等价于 {@link remove}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+	async removeAndGetHistoryId(nodeOrNodeList, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.remove(nodeOrNodeList, options);
+		return {
+			result: void 0,
+			historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId)
+		};
+	}
+	/** 等价于 {@link update}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+	async updateAndGetHistoryId(config, data = {}) {
+		this.lastPushedHistoryId = null;
+		return {
+			result: await this.update(config, data),
+			historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId)
+		};
+	}
+	/** 等价于 {@link moveLayer}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+	async moveLayerAndGetHistoryId(offset, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.moveLayer(offset, options);
+		return {
+			result: void 0,
+			historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId)
+		};
+	}
+	/** 等价于 {@link moveToContainer}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+	async moveToContainerAndGetHistoryId(config, targetId, options = {}) {
+		this.lastPushedHistoryId = null;
+		return {
+			result: await this.moveToContainer(config, targetId, options),
+			historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId)
+		};
+	}
+	/** 等价于 {@link dragTo}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+	async dragToAndGetHistoryId(config, targetParent, targetIndex, options = {}) {
+		this.lastPushedHistoryId = null;
+		await this.dragTo(config, targetParent, targetIndex, options);
+		return {
+			result: void 0,
+			historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId)
+		};
 	}
 	/**
 	* 撤销当前操作
 	* @returns 被撤销的操作
 	*/
 	async undo() {
-		const value = history_default.undo();
+		const pageId = this.get("page")?.id;
+		if (pageId === void 0) return null;
+		const value = history_default.undo("page", pageId);
 		if (value) await this.applyHistoryOp(value, true);
 		return value;
 	}
@@ -736,11 +920,141 @@ var Editor = class extends BaseService_default {
 	* @returns 被恢复的操作
 	*/
 	async redo() {
-		const value = history_default.redo();
+		const pageId = this.get("page")?.id;
+		if (pageId === void 0) return null;
+		const value = history_default.redo("page", pageId);
 		if (value) await this.applyHistoryOp(value, false);
 		return value;
 	}
-	async move(left, top) {
+	/**
+	* 「回滚」指定页面历史步骤（类 git revert 语义）：
+	* - 不动原始历史栈结构（不移动 cursor、不丢弃任何步骤）；
+	* - 取出 `index` 对应的 step，**反向应用**一次（add→remove / remove→add / update→旧值）；
+	* - 把这次反向应用作为一条**新步骤**追加到栈顶，可被普通 undo / redo。
+	*
+	* 与 `gotoPageStep`（类 git reset）的区别在于此操作**不丢弃**目标之后的历史。
+	* 与 `applyHistoryOp(reverse=true)` 的区别在于：本方法**不带** `doNotPushHistory`，
+	* 反向应用会以一条新 step 入栈；并且不实施 step 中保存的选区与 modifiedNodeIds 状态，
+	* 选区由用户当前位置决定，符合"新提交"语义。
+	*
+	* 仅对处于「已应用」状态的步骤生效——未应用的步骤本身就不存在于当前 DSL 中，反向无意义。
+	*
+	* @param index 目标 step 在所属页面栈中的索引（0 为最早），通常由历史面板传入
+	* @returns 反向后产生的新 step；目标不存在 / 未应用 / 反向失败时返回 null
+	*/
+	async revertPageStep(index) {
+		const entry = history_default.getStepList("page", this.get("page")?.id)[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 = (_pageId, s) => {
+			revertedStep = s;
+		};
+		history_default.once("change", captureRevert);
+		const historyDescription = `回滚 #${index + 1}: ${describeStepForRevert(step)}`;
+		const opts = {
+			doNotSelect: true,
+			doNotSwitchPage: true,
+			historyDescription,
+			historySource: "rollback"
+		};
+		try {
+			switch (step.opType) {
+				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.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(oldSchema)], parent, opts);
+					}
+					break;
+				}
+				case "update": {
+					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,
+								type: newNode.type
+							};
+							for (const record of changeRecords) {
+								if (!record.propPath) return cloneDeep$1(oldNode);
+								const value = cloneDeep$1(getValueByKeyPath(record.propPath, oldNode));
+								setValueByKeyPath(record.propPath, value, patch);
+							}
+							return patch;
+						}
+						return cloneDeep$1(oldNode);
+					});
+					if (configs.length) await this.update(configs, {
+						historyDescription,
+						historySource: "rollback"
+					});
+					break;
+				}
+			}
+		} finally {
+			history_default.off("change", captureRevert);
+		}
+		const page = toRaw(this.get("page"));
+		if (page) this.emit("history-change", page);
+		return revertedStep;
+	}
+	/**
+	* 通过历史记录 uuid 回滚当前页面的历史步骤，语义与 {@link revertPageStep} 完全一致，
+	* 仅入参从 index 改为 uuid 列表（{@link StepValue.uuid}）。按数组顺序依次回滚，
+	* 返回与入参同序的结果列表（某项失败时为 `null`）。
+	*
+	* @param uuids 目标历史记录的 uuid 列表，通常由 *AndGetHistoryId 方法返回的 `historyIds`
+	*/
+	async revertPageStepById(uuids) {
+		const results = [];
+		const pageId = this.get("page")?.id;
+		for (const uuid of uuids) {
+			const location = history_default.findStepLocationByUuid("page", uuid, pageId);
+			results.push(!location ? null : await this.revertPageStep(location.index));
+		}
+		return results;
+	}
+	/**
+	* 跳转当前页面历史栈到指定游标位置。
+	*
+	* `targetCursor` 与 `UndoRedo.getCursor()` 同义：表示"已应用步骤数量"，
+	* 取值范围 `[0, length]`。当目标 < 当前游标时循环 undo，否则循环 redo。
+	* 通常由历史面板传入「点击的 step.index + 1」作为目标。
+	*
+	* @returns 实际移动到的最终游标位置
+	*/
+	async gotoPageStep(targetCursor) {
+		const pageId = this.get("page")?.id;
+		let cursor = history_default.getCursor("page", pageId);
+		const { length } = history_default.getStepList("page", pageId);
+		const target = Math.max(0, Math.min(targetCursor, length));
+		while (cursor > target) {
+			if (!await this.undo()) break;
+			cursor -= 1;
+		}
+		while (cursor < target) {
+			if (!await this.redo()) break;
+			cursor += 1;
+		}
+		return cursor;
+	}
+	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);
@@ -749,6 +1063,10 @@ var Editor = class extends BaseService_default {
 			id: node.id,
 			type: node.type,
 			style: newStyle
+		}, {
+			doNotPushHistory,
+			historyDescription,
+			historySource
 		});
 	}
 	resetState() {
@@ -783,63 +1101,207 @@ var Editor = class extends BaseService_default {
 		return super.emit(eventName, ...args);
 	}
 	addModifiedNodeId(id) {
-		if (!this.isHistoryStateChange) this.get("modifiedNodeIds").set(id, id);
+		this.get("modifiedNodeIds").set(id, id);
+	}
+	/**
+	* 获取指定节点所属的页面 / 页面片：
+	* - 普通节点返回其所在的 page；
+	* - 节点本身就是 page / pageFragment 时返回它自己；
+	* - 找不到时返回 null。
+	* 供 `change` 事件携带「变更节点对应的 page」（而非编辑器当前选中页）。
+	*/
+	getPageOfNode(id) {
+		const { node, page } = this.getNodeInfo(id, false);
+		if (page) return page;
+		if (node && (isPage(node) || isPageFragment(node))) return node;
+		return null;
 	}
 	captureSelectionBeforeOp() {
-		if (this.isHistoryStateChange || this.selectionBeforeOp) return;
+		if (this.selectionBeforeOp) return;
 		this.selectionBeforeOp = this.get("nodes").map((n) => n.id);
 	}
-	pushOpHistory(opType, extra, pageData) {
-		if (this.isHistoryStateChange) {
-			this.selectionBeforeOp = null;
-			return;
-		}
+	/**
+	* 比较「上一次 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,
+			extra: {
+				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.replaceCurrentStep("page", step, page.id);
+		else history_default.push("page", 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
+			extra: {
+				selectedBefore: this.selectionBeforeOp ?? [],
+				selectedAfter: this.get("nodes").map((n) => n.id),
+				modifiedNodeIds: new Map(this.get("modifiedNodeIds"))
+			},
+			diff
 		};
-		history_default.push(step);
+		if (historyDescription) step.historyDescription = historyDescription;
+		if (source) step.source = source;
+		const historyId = history_default.push("page", step, pageData.id) ? step.uuid : null;
+		this.lastPushedHistoryId = historyId;
 		this.selectionBeforeOp = null;
-		this.isHistoryStateChange = false;
+		return historyId;
 	}
 	/**
 	* 应用历史操作（撤销 / 重做）
+	*
+	* 所有 DSL 修改都走 `editor.add / remove / update`，并通过 `doNotPushHistory` 阻止再次入栈、
+	* `doNotSelect / doNotSwitchPage` 让选区由方法末尾的统一逻辑兜底。
+	*
+	* 注意：这些公开方法会发出 add / remove / update 事件，业务侧若需要区分"用户操作"与"撤销重做触发"，
+	* 请监听 `history-change` 事件配合判断。
+	*
 	* @param step 操作记录
 	* @param reverse true = 撤销，false = 重做
 	*/
 	async applyHistoryOp(step, reverse) {
-		this.isHistoryStateChange = true;
+		if (step.opType === "initial") return;
 		const root = this.get("root");
 		const stage = this.get("stage");
 		if (!root) return;
-		const ctx = {
-			root,
-			stage,
-			getNodeById: (id, raw) => this.getNodeById(id, raw),
-			getNodeInfo: (id, raw) => this.getNodeInfo(id, raw),
-			setRoot: (r) => this.set("root", r),
-			setPage: (p) => this.set("page", p),
-			getPage: () => this.get("page")
+		const commonOpts = {
+			doNotSelect: true,
+			doNotSwitchPage: true,
+			doNotPushHistory: true
 		};
 		switch (step.opType) {
-			case "add":
-				await applyHistoryAddOp(step, reverse, ctx);
+			case "add": {
+				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 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":
-				await applyHistoryRemoveOp(step, reverse, ctx);
+			}
+			case "remove": {
+				const items = step.diff ?? [];
+				if (reverse) {
+					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 ?? parent.items.length, 0, cloneDeep$1(oldSchema));
+							await stage?.add({
+								config: cloneDeep$1(oldSchema),
+								parent: cloneDeep$1(parent),
+								parentId,
+								root: cloneDeep$1(root)
+							});
+						}
+					}
+				} 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":
-				await applyHistoryUpdateOp(step, reverse, ctx);
+			}
+			case "update": {
+				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 = {
+							id: newNode.id,
+							type: newNode.type
+						};
+						for (const record of changeRecords) {
+							if (!record.propPath) return cloneDeep$1(sourceForValues);
+							const value = cloneDeep$1(getValueByKeyPath(record.propPath, sourceForValues));
+							setValueByKeyPath(record.propPath, value, patch);
+						}
+						return patch;
+					}
+					return cloneDeep$1(reverse ? oldNode : newNode);
+				});
+				if (configs.length) await this.update(configs, { doNotPushHistory: true });
 				break;
+			}
 		}
-		this.set("modifiedNodeIds", step.modifiedNodeIds);
+		this.set("modifiedNodeIds", step.extra?.modifiedNodeIds ?? /* @__PURE__ */ new Map());
 		const page = toRaw(this.get("page"));
 		if (page) {
-			const selectIds = reverse ? step.selectedBefore : step.selectedAfter;
+			const selectIds = (reverse ? step.extra?.selectedBefore : step.extra?.selectedAfter) ?? [];
 			setTimeout(() => {
 				if (!selectIds.length) return;
 				if (selectIds.length > 1) {
@@ -849,7 +1311,6 @@ var Editor = class extends BaseService_default {
 			}, 0);
 			this.emit("history-change", page);
 		}
-		this.isHistoryStateChange = false;
 	}
 	selectedConfigExceptionHandler(config) {
 		return resolveSelectedNode(config, (id) => this.getNodeInfo(id), this.state.root?.id);