@tmagic/editor 1.8.0-beta.2 → 1.8.0-beta.20

package/dist/es/services/editor.js

@@ -1,46 +1,27 @@
 import { Layout, canUsePluginMethods } from "../type.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 { 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, isPageOrFragment, setValueByKeyPath, traverseNode } 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 { nextTick, reactive, toRaw } from "vue";
+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,
@@ -52,12 +33,24 @@ var Editor = class extends BaseService {
 		stageLoading: true,
 		highlightNode: null,
 		modifiedNodeIds: /* @__PURE__ */ new Map(),
+		invalidNodeIds: /* @__PURE__ */ new Map(),
 		pageLength: 0,
 		pageFragmentLength: 0,
 		disabledMultiSelect: false,
 		alwaysMultiSelect: false
 	});
 	selectionBeforeOp = null;
+	/**
+	* 操作前的节点校验错误快照，与 selectionBeforeOp 同时在 captureSelectionBeforeOp 中捕获，
+	* 供 pushOpHistory 写入 step.extra.invalidNodeIdsBefore，用于撤销时还原到「操作前」的错误状态。
+	*/
+	invalidNodeIdsBeforeOp = null;
+	/**
+	* 最近一次 pushOpHistory 写入的历史记录 uuid。
+	* 供 *AndGetHistoryId 系列方法在调用普通操作后取回本次产生的历史记录 id；
+	* 普通操作不会读取它，调用前由 *AndGetHistoryId 重置为 null。
+	*/
+	lastPushedHistoryId = null;
 	constructor() {
 		super(canUsePluginMethods.async.map((methodName) => ({
 			name: methodName,
@@ -70,10 +63,11 @@ var Editor = class extends BaseService {
 	}
 	/**
 	* 设置当前指点节点配置
-	* @param name 'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength
+	* @param name 'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'invalidNodeIds' | '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,17 +78,25 @@ 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.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);
+			this.pruneInvalidNodeIds();
 		}
 	}
 	/**
 	* 获取当前指点节点配置
-	* @param name  'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength'
+	* @param name  'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'invalidNodeIds' | 'pageLength' | 'pageFragmentLength'
 	* @returns MNode
 	*/
 	get(name) {
@@ -109,7 +111,25 @@ 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,
+			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获取指点节点配置
@@ -139,7 +159,7 @@ var Editor = class extends BaseService {
 	isOnDifferentPage(node) {
 		const currentPageId = this.get("page")?.id;
 		if (currentPageId === void 0 || currentPageId === null) return false;
-		if (isPage(node) || isPageFragment(node)) return `${node.id}` !== `${currentPageId}`;
+		if (isPageOrFragment(node)) return `${node.id}` !== `${currentPageId}`;
 		const nodePage = this.getNodeInfo(node.id, false).page;
 		if (!nodePage) return false;
 		return `${nodePage.id}` !== `${currentPageId}`;
@@ -163,8 +183,6 @@ var Editor = class extends BaseService {
 		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,
@@ -234,8 +252,8 @@ var Editor = class extends BaseService {
 		const curNode = this.get("node");
 		const stage = this.get("stage");
 		if (!curNode) throw new Error("当前选中节点为空");
-		if ((parent.type === NodeType.ROOT || curNode?.type === NodeType.ROOT) && !(isPage(node) || isPageFragment(node))) throw new Error("app下不能添加组件");
-		if (parent.id !== curNode.id && !(isPage(node) || isPageFragment(node))) {
+		if ((parent.type === NodeType.ROOT || curNode?.type === NodeType.ROOT) && !isPageOrFragment(node)) throw new Error("app下不能添加组件");
+		if (parent.id !== curNode.id && !isPageOrFragment(node)) {
 			const index = parent.items.indexOf(curNode);
 			parent.items?.splice(index + 1, 0, node);
 		} else parent.items?.push(node);
@@ -269,7 +287,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 = [];
@@ -280,7 +298,7 @@ var Editor = class extends BaseService {
 		} else addNodes.push(...addNode);
 		const newNodes = await Promise.all(addNodes.map((node) => {
 			const root = this.get("root");
-			if ((isPage(node) || isPageFragment(node)) && root) return this.doAdd(node, root);
+			if (isPageOrFragment(node) && root) return this.doAdd(node, root);
 			const parentNode = parent ?? getAddParent(node);
 			if (!parentNode) throw new Error("未找到父元素");
 			return this.doAdd(node, parentNode);
@@ -300,22 +318,44 @@ var Editor = class extends BaseService {
 			else if (isPageFragment(newNodes[0])) this.state.pageFragmentLength += 1;
 			else if (!skipSelect) stage?.select(newNodes[0].id);
 		}
-		if (!(isPage(newNodes[0]) || isPageFragment(newNodes[0]))) {
+		if (!isPageOrFragment(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);
+		this.emit("change", {
+			type: "add",
+			data: newNodes.map((node) => ({
+				node,
+				page: this.getPageOfNode(node.id)
+			})),
+			historySource,
+			doNotPushHistory
+		});
+		const addedPages = newNodes.filter((node) => isPageOrFragment(node));
+		if (addedPages.length) history_default.notifyPageStructureChange({
+			add: addedPages,
+			remove: []
+		});
 		return Array.isArray(addNode) ? newNodes : newNodes[0];
 	}
 	async doRemove(node, { doNotSelect = false, doNotSwitchPage = false } = {}) {
@@ -325,13 +365,10 @@ var Editor = class extends BaseService {
 		if (!parent || !curNode) throw new Error("找不要删除的节点");
 		const index = getNodeIndex(curNode.id, parent);
 		if (typeof index !== "number" || index === -1) throw new Error("找不要删除的节点");
-		parent.items?.splice(index, 1);
 		const stage = this.get("stage");
-		stage?.remove({
-			id: node.id,
-			parentId: parent.id,
-			root: cloneDeep$1(root)
-		});
+		const currentPage = this.get("page");
+		const isDeletingCurrentPage = isPageOrFragment(node) && !!currentPage && `${currentPage.id}` === `${node.id}`;
+		parent.items?.splice(index, 1);
 		const selectedNodes = this.get("nodes");
 		const removedSelectedIndex = selectedNodes.findIndex((n) => `${n.id}` === `${node.id}`);
 		if (removedSelectedIndex !== -1) {
@@ -339,27 +376,29 @@ var Editor = class extends BaseService {
 			nextSelected.splice(removedSelectedIndex, 1);
 			this.set("nodes", nextSelected);
 		}
-		if (isPage(node) || isPageFragment(node)) {
-			const currentPage = this.get("page");
-			if (currentPage && `${currentPage.id}` === `${node.id}`) this.set("page", null);
-		}
-		const selectDefault = async (pages) => {
-			if (pages[0]) {
-				await this.select(pages[0]);
-				stage?.select(pages[0].id);
-			} else {
-				this.selectRoot();
-				history_default.resetPage();
-			}
+		const removeData = {
+			id: node.id,
+			parentId: parent.id,
+			root: cloneDeep$1(root)
 		};
 		const rootItems = root.items || [];
-		if (isPage(node)) {
-			this.state.pageLength -= 1;
-			if (!doNotSelect && !doNotSwitchPage) await selectDefault(rootItems);
-		} else if (isPageFragment(node)) {
-			this.state.pageFragmentLength -= 1;
-			if (!doNotSelect && !doNotSwitchPage) await selectDefault(rootItems);
+		const shouldReselect = isDeletingCurrentPage && !doNotSelect && !doNotSwitchPage;
+		const shouldSwitchPage = shouldReselect && rootItems.length > 0;
+		if (isPageOrFragment(node)) {
+			if (isPage(node)) this.state.pageLength -= 1;
+			else this.state.pageFragmentLength -= 1;
+			if (shouldSwitchPage) {
+				await this.select(rootItems[0]);
+				stage?.select(rootItems[0].id);
+				await nextTick();
+				stage?.remove(removeData);
+			} else {
+				stage?.remove(removeData);
+				if (shouldReselect) this.selectRoot();
+				else if (isDeletingCurrentPage) this.set("page", null);
+			}
 		} else {
+			stage?.remove(removeData);
 			if (!doNotSelect) {
 				await this.select(parent);
 				stage?.select(parent.id);
@@ -379,12 +418,16 @@ 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 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) {
+		if (!isPageOrFragment(nodes[0])) for (const n of nodes) {
 			const { parent, node: curNode, page } = this.getNodeInfo(n.id, false);
 			if (parent && curNode) {
 				if (!pageForOp && page) pageForOp = {
@@ -393,7 +436,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,22 +446,38 @@ var Editor = class extends BaseService {
 			doNotSelect,
 			doNotSwitchPage
 		})));
-		if (removedItems.length > 0 && pageForOp) if (!doNotPushHistory) this.pushOpHistory("remove", { removedItems }, pageForOp, historyDescription);
+		this.removeInvalidNodesBySubtree(nodes);
+		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,
+			historySource,
+			doNotPushHistory
+		});
+		const removedPages = nodes.filter((node) => isPageOrFragment(node));
+		if (removedPages.length) history_default.notifyPageStructureChange({
+			add: [],
+			remove: removedPages
+		});
 	}
-	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);
+		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,
@@ -440,7 +499,7 @@ var Editor = class extends BaseService {
 			selectedNodes.splice(targetIndex, 1, newConfig);
 			this.set("nodes", [...selectedNodes]);
 		}
-		if (isPage(newConfig) || isPageFragment(newConfig)) {
+		if (isPageOrFragment(newConfig)) {
 			const currentPage = this.get("page");
 			if (currentPage && `${currentPage.id}` === `${newConfig.id}`) this.set("page", newConfig);
 		}
@@ -464,26 +523,44 @@ 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, invalidInfo } = 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
+			});
 		}));
+		this.applyInvalidInfo(config, invalidInfo);
 		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);
+		this.emit("change", {
+			type: "update",
+			data: updateData.map((node) => ({
+				node,
+				page: this.getPageOfNode(node.newNode.id)
+			})),
+			historySource,
+			doNotPushHistory
+		});
 		return Array.isArray(config) ? updateData.map((item) => item.newNode) : updateData[0].newNode;
 	}
 	/**
@@ -496,7 +573,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 +585,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 +624,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 +638,9 @@ var Editor = class extends BaseService {
 		return this.add(pasteConfigs, parent, {
 			doNotSelect,
 			doNotSwitchPage,
-			doNotPushHistory
+			doNotPushHistory,
+			historyDescription,
+			historySource
 		});
 	}
 	async doPaste(config, position = {}) {
@@ -586,11 +668,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 +687,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,15 +712,30 @@ 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);
+		this.emit("change", {
+			type: "move-layer",
+			data: [{
+				node,
+				page: this.getPageOfNode(node.id)
+			}],
+			offset,
+			historySource,
+			doNotPushHistory
+		});
 	}
 	/**
 	* 移动一个或多个节点到指定容器中。
@@ -650,9 +751,9 @@ 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)));
+		const configs = (isBatch ? config : [config]).filter((item) => !isPageOrFragment(item));
 		if (configs.length === 0) throw new Error("没有可移动的节点");
 		this.captureSelectionBeforeOp();
 		const target = this.getNodeById(targetId, false);
@@ -698,11 +799,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 +850,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", {
@@ -754,13 +865,84 @@ var Editor = class extends BaseService {
 			configs,
 			targetParent
 		});
+		this.emit("change", {
+			type: "drag-to",
+			data: configs.map((node) => ({
+				node,
+				page: this.getPageOfNode(node.id)
+			})),
+			targetIndex,
+			targetParent,
+			historySource,
+			doNotPushHistory
+		});
+	}
+	/**
+	* 下列 *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;
 	}
@@ -769,7 +951,9 @@ var Editor = class extends BaseService {
 	* @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;
 	}
@@ -790,12 +974,17 @@ var Editor = class extends BaseService {
 	* @returns 反向后产生的新 step；目标不存在 / 未应用 / 反向失败时返回 null
 	*/
 	async revertPageStep(index) {
-		const entry = history_default.getPageStepList()[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 = (s) => {
+		const captureRevert = (_pageId, s) => {
 			revertedStep = s;
 		};
 		history_default.once("change", captureRevert);
@@ -803,28 +992,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 +1031,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 +1046,22 @@ var Editor = class extends BaseService {
 		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()` 同义：表示"已应用步骤数量"，
@@ -860,8 +1071,9 @@ var Editor = class extends BaseService {
 	* @returns 实际移动到的最终游标位置
 	*/
 	async gotoPageStep(targetCursor) {
-		let cursor = history_default.getPageCursor();
-		const { length } = history_default.getPageStepList();
+		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;
@@ -873,7 +1085,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 +1094,11 @@ var Editor = class extends BaseService {
 			id: node.id,
 			type: node.type,
 			style: newStyle
-		}, { doNotPushHistory });
+		}, {
+			doNotPushHistory,
+			historyDescription,
+			historySource
+		});
 	}
 	resetState() {
 		this.set("root", null);
@@ -893,6 +1109,7 @@ var Editor = class extends BaseService {
 		this.set("stage", null);
 		this.set("highlightNode", null);
 		this.set("modifiedNodeIds", /* @__PURE__ */ new Map());
+		this.set("invalidNodeIds", /* @__PURE__ */ new Map());
 		this.set("pageLength", 0);
 	}
 	destroy() {
@@ -903,6 +1120,51 @@ var Editor = class extends BaseService {
 	resetModifiedNodeId() {
 		this.get("modifiedNodeIds").clear();
 	}
+	/**
+	* 记录（或覆盖）某个节点在指定来源（属性表单 / 样式表单）上的校验错误信息。
+	* @param id 节点 id
+	* @param source 错误来源：'props'（属性表单）| 'style'（样式表单）
+	* @param message 错误文案（可能是包含 <br> 的 HTML）
+	*/
+	setInvalidNode(id, source, message) {
+		const map = this.get("invalidNodeIds");
+		const info = { ...map.get(id) || {} };
+		info[source] = message;
+		map.set(id, info);
+		this.emit("invalid-node-change", map);
+	}
+	/**
+	* 删除节点的校验错误记录。
+	* @param id 节点 id
+	* @param source 指定来源则仅删除该来源；不传则删除该节点全部来源的错误
+	*/
+	deleteInvalidNode(id, source) {
+		const map = this.get("invalidNodeIds");
+		if (!map.has(id)) return;
+		if (!source) map.delete(id);
+		else {
+			const info = { ...map.get(id) || {} };
+			delete info[source];
+			if (info.props || info.style) map.set(id, info);
+			else map.delete(id);
+		}
+		this.emit("invalid-node-change", map);
+	}
+	/** 获取当前存在校验错误的节点错误 Map（key 为节点 id） */
+	getInvalidNodeIds() {
+		return this.get("invalidNodeIds");
+	}
+	/** 获取指定节点的校验错误信息 */
+	getInvalidNodeInfo(id) {
+		return this.get("invalidNodeIds").get(id);
+	}
+	/** 清空全部校验错误记录 */
+	resetInvalidNodeId() {
+		const map = this.get("invalidNodeIds");
+		if (map.size === 0) return;
+		map.clear();
+		this.emit("invalid-node-change", map);
+	}
 	usePlugin(options) {
 		super.usePlugin(options);
 	}
@@ -915,99 +1177,248 @@ var Editor = class extends BaseService {
 	emit(eventName, ...args) {
 		return super.emit(eventName, ...args);
 	}
+	/**
+	* 应用一次属性面板提交携带的校验错误信息（在写入历史记录之前调用，使历史快照与本次变更对齐）。
+	* - invalidInfo 为空（调用方未携带）：认为本次更新对应的节点已无校验错误，清除其全部来源的错误；
+	* - error 非空则记录错误，为空则清除对应来源的错误。
+	*/
+	applyInvalidInfo(config, invalidInfo) {
+		if (!invalidInfo) {
+			(Array.isArray(config) ? config : [config]).map((node) => node.id).filter((id) => id !== void 0).forEach((id) => this.deleteInvalidNode(id));
+			return;
+		}
+		const { id, source, error } = invalidInfo;
+		if (error) this.setInvalidNode(id, source, error);
+		else this.deleteInvalidNode(id, source);
+	}
+	/** 删除被移除节点（含其子树）的校验错误记录，避免残留误报 */
+	removeInvalidNodesBySubtree(nodes) {
+		const map = this.get("invalidNodeIds");
+		if (map.size === 0) return;
+		let changed = false;
+		nodes.forEach((node) => {
+			traverseNode(node, (n) => {
+				if (n.id !== void 0 && map.delete(n.id)) changed = true;
+			});
+		});
+		if (changed) this.emit("invalid-node-change", map);
+	}
+	/** 清理不在当前 DSL 中的失效节点错误记录（用于整体替换 root 后） */
+	pruneInvalidNodeIds() {
+		const map = this.get("invalidNodeIds");
+		if (map.size === 0) return;
+		let changed = false;
+		for (const id of [...map.keys()]) if (!this.getNodeById(id, false)) {
+			map.delete(id);
+			changed = true;
+		}
+		if (changed) this.emit("invalid-node-change", map);
+	}
 	addModifiedNodeId(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 && isPageOrFragment(node)) return node;
+		return null;
+	}
 	captureSelectionBeforeOp() {
 		if (this.selectionBeforeOp) return;
 		this.selectionBeforeOp = this.get("nodes").map((n) => n.id);
+		this.invalidNodeIdsBeforeOp = new Map(this.get("invalidNodeIds"));
 	}
-	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}`);
+		const addedPages = [];
+		const removedPages = [];
+		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);
+				addedPages.push(nextPage);
+			} 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);
+				removedPages.push(prevPage);
+			}
+		});
+		if (addedPages.length || removedPages.length) history_default.notifyPageStructureChange({
+			add: addedPages,
+			remove: removedPages
+		});
+	}
+	/**
+	* 构造一条页面级「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")),
+				invalidNodeIdsBefore: new Map(this.invalidNodeIdsBeforeOp ?? this.get("invalidNodeIds")),
+				invalidNodeIdsAfter: new Map(this.get("invalidNodeIds"))
+			},
+			diff
 		};
 		if (historyDescription) step.historyDescription = historyDescription;
-		history_default.push(step, pageData.id);
+		if (source) step.source = source;
+		const historyId = history_default.push("page", step, pageData.id) ? step.uuid : null;
+		this.lastPushedHistoryId = historyId;
 		this.selectionBeforeOp = null;
+		this.invalidNodeIdsBeforeOp = null;
+		return historyId;
 	}
 	/**
 	* 应用历史操作（撤销 / 重做）
 	*
-	* 所有 DSL 修改都走 `editor.add / remove / update`，并通过 `doNotPushHistory` 阻止再次入栈、
-	* `doNotSelect / doNotSwitchPage` 让选区由方法末尾的统一逻辑兜底。
+	* 删除 / 更新类修改走 `editor.remove / update`，并通过 `doNotPushHistory` 阻止再次入栈、
+	* `doNotSelect / doNotSwitchPage` 让选区由方法末尾的统一逻辑兜底；
+	* 「重新插回节点」（撤销 remove / 重做 add）需按 step 记录的 parentId / index 精确还原，
+	* 不走 this.add，由手工 splice + stage.add 完成后补发等价的 add / change 事件（见 emitHistoryInsertEvents）。
 	*
-	* 注意：这些公开方法会发出 add / remove / update 事件，业务侧若需要区分"用户操作"与"撤销重做触发"，
+	* 注意：这些路径都会发出 add / remove / update / change 事件，业务侧若需要区分"用户操作"与"撤销重做触发"，
 	* 请监听 `history-change` 事件配合判断。
 	*
 	* @param step 操作记录
 	* @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;
 		const commonOpts = {
 			doNotSelect: true,
 			doNotSwitchPage: true,
-			doNotPushHistory: true
+			doNotPushHistory: true,
+			historySource: step.source
 		};
 		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));
+					const addedNodes = [];
+					for (const { newSchema, parentId, index } of sorted) {
+						if (!newSchema || parentId === void 0) continue;
+						const parent = this.getNodeById(parentId, false);
+						if (parent?.items) {
+							const addedNode = cloneDeep$1(newSchema);
+							if (typeof index === "number" && index >= 0 && index < parent.items.length) parent.items.splice(index, 0, addedNode);
+							else parent.items.push(addedNode);
+							addedNodes.push(addedNode);
+							await stage?.add({
+								config: cloneDeep$1(newSchema),
+								parent: cloneDeep$1(parent),
+								parentId: parent.id,
+								root: cloneDeep$1(root)
+							});
 						}
 					}
+					this.emitHistoryInsertEvents(addedNodes, step.source);
 				}
 				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));
+					const addedNodes = [];
+					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));
+							const addedNode = cloneDeep$1(oldSchema);
+							parent.items.splice(index ?? parent.items.length, 0, addedNode);
+							addedNodes.push(addedNode);
 							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);
+					this.emitHistoryInsertEvents(addedNodes, step.source);
+				} 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 = {
@@ -1023,14 +1434,20 @@ var Editor = class extends BaseService {
 					}
 					return cloneDeep$1(reverse ? oldNode : newNode);
 				});
-				if (configs.length) await this.update(configs, { doNotPushHistory: true });
+				if (configs.length) await this.update(configs, {
+					doNotPushHistory: true,
+					historySource: step.source
+				});
 				break;
 			}
 		}
-		this.set("modifiedNodeIds", step.modifiedNodeIds);
+		this.set("modifiedNodeIds", step.extra?.modifiedNodeIds ?? /* @__PURE__ */ new Map());
+		const invalidToRestore = (reverse ? step.extra?.invalidNodeIdsBefore : step.extra?.invalidNodeIdsAfter) ?? /* @__PURE__ */ new Map();
+		this.set("invalidNodeIds", new Map(invalidToRestore));
+		this.emit("invalid-node-change", this.get("invalidNodeIds"));
 		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) {
@@ -1044,6 +1461,23 @@ var Editor = class extends BaseService {
 	selectedConfigExceptionHandler(config) {
 		return resolveSelectedNode(config, (id) => this.getNodeInfo(id), this.state.root?.id);
 	}
+	/**
+	* 撤销 remove / 重做 add 通过手工 splice 按 step 记录的 parentId / index 精确还原节点（不走 this.add，原因见调用处注释），
+	* 这里补齐与 this.add 等价的 add / change 事件，保证撤销/重做路径的事件行为与正向操作一致。
+	*/
+	emitHistoryInsertEvents(nodes, source) {
+		if (!nodes.length) return;
+		this.emit("add", nodes);
+		this.emit("change", {
+			type: "add",
+			data: nodes.map((node) => ({
+				node,
+				page: this.getPageOfNode(node.id)
+			})),
+			historySource: source,
+			doNotPushHistory: true
+		});
+	}
 };
 var editor_default = new Editor();
 //#endregion