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

package/dist/es/services/editor.js

@@ -1,35 +1,47 @@
 import { Layout, canUsePluginMethods } from "../type.js";
-import BaseService_default from "./BaseService.js";
+import BaseService from "./BaseService.js";
 import props_default from "./props.js";
 import history_default from "./history.js";
 import storage_default, { Protocol } from "./storage.js";
 import { COPY_STORAGE_KEY, calcAlignCenterStyle, calcLayerTargetIndex, calcMoveStyle, classifyDragSources, collectRelatedNodes, editorNodeMergeCustomizer, fixNodePosition, getInitPositionStyle, getNodeIndex, getPageFragmentList, getPageList, moveItemsInContainer, resolveSelectedNode, setChildrenLayout, setLayout, toggleFixedPosition } from "../utils/editor.js";
-import { applyHistoryAddOp, applyHistoryRemoveOp, applyHistoryUpdateOp } from "../utils/editor-history.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, 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, isObject, mergeWith, uniq } from "lodash-es";
 //#region packages/editor/src/services/editor.ts
 /**
-* 经过 BaseService 的插件 / 中间件包装后，源方法的最后一个形参可能被注入为 dispatch 函数
-* 当 options 形参位置被注入为函数（或为 null）时，将其归一为空对象，避免后续逻辑误读
+* 给「回滚」生成的新 step 用的简短描述生成器。
+* 与 UI 层 `describePageStep` 同义，但避免 service 反向依赖 layouts/，故在此本地实现。
 */
-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 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 Editor = class extends BaseService_default {
+var Editor = class extends BaseService {
 	state = reactive({
 		root: null,
 		page: null,
@@ -45,7 +57,6 @@ var Editor = class extends BaseService_default {
 		disabledMultiSelect: false,
 		alwaysMultiSelect: false
 	});
-	isHistoryStateChange = false;
 	selectionBeforeOp = null;
 	constructor() {
 		super(canUsePluginMethods.async.map((methodName) => ({
@@ -137,7 +148,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;
@@ -231,18 +242,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 +266,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 } = {}) {
 		this.captureSelectionBeforeOp();
 		const stage = this.get("stage");
 		const addNodes = [];
@@ -271,7 +281,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,8 +302,8 @@ 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))),
+			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);
@@ -302,13 +312,13 @@ var Editor = class extends BaseService_default {
 			}, {
 				name: pageForOp?.name || "",
 				id: pageForOp.id
-			});
+			}, historyDescription);
+			else this.selectionBeforeOp = null;
 		}
 		this.emit("add", newNodes);
 		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 +330,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}`);
@@ -367,9 +377,9 @@ 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 } = {}) {
 		this.captureSelectionBeforeOp();
 		const nodes = Array.isArray(nodeOrNodeList) ? nodeOrNodeList : [nodeOrNodeList];
 		const removedItems = [];
@@ -383,7 +393,7 @@ var Editor = class extends BaseService_default {
 				};
 				const idx = getNodeIndex(curNode.id, parent);
 				removedItems.push({
-					node: cloneDeep(toRaw(curNode)),
+					node: cloneDeep$1(toRaw(curNode)),
 					parentId: parent.id,
 					index: typeof idx === "number" ? idx : -1
 				});
@@ -393,7 +403,8 @@ 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", { removedItems }, pageForOp, historyDescription);
+		else this.selectionBeforeOp = null;
 		this.emit("remove", nodes);
 	}
 	async doUpdate(config, { changeRecords = [] } = {}) {
@@ -404,7 +415,7 @@ var Editor = class extends BaseService_default {
 		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);
+		newConfig = mergeWith(cloneDeep$1(node), newConfig, editorNodeMergeCustomizer);
 		if (!newConfig.type) throw new Error("配置缺少type值");
 		if (newConfig.type === NodeType.ROOT) {
 			this.set("root", newConfig);
@@ -444,25 +455,33 @@ 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 } = 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 });
+		}));
 		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))
+					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
-				});
-			}
-			this.isHistoryStateChange = false;
+				}, historyDescription);
+			} else this.selectionBeforeOp = null;
 		}
 		this.emit("update", updateData);
 		return Array.isArray(config) ? updateData.map((item) => item.newNode) : updateData[0].newNode;
@@ -474,27 +493,27 @@ 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 } = {}) {
 		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 });
 		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 +541,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 } = {}) {
 		const config = storage_default.getItem(COPY_STORAGE_KEY);
 		if (!Array.isArray(config)) return;
 		const node = this.get("node");
@@ -538,18 +557,19 @@ 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
 		});
 	}
 	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 +583,14 @@ 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 } = {}) {
 		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 });
 		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 +598,10 @@ var Editor = class extends BaseService_default {
 	/**
 	* 移动当前选中节点位置
 	* @param offset 偏移量
+	* @param options 可选配置
+	* @param options.doNotPushHistory 是否不写入历史记录（默认 false）
 	*/
-	async moveLayer(offset) {
+	async moveLayer(offset, { doNotPushHistory = false } = {}) {
 		this.captureSelectionBeforeOp();
 		const root = this.get("root");
 		if (!root) throw new Error("root为空");
@@ -592,95 +614,104 @@ 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", { updatedItems: [{
+				oldNode: oldParent,
+				newNode: cloneDeep$1(toRaw(parent))
+			}] }, {
+				name: pageForOp?.name || "",
+				id: pageForOp.id
+			});
+		} else this.selectionBeforeOp = null;
 		this.emit("move-layer", 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 } = {}) {
+		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", { updatedItems }, historyPage);
+		} else this.selectionBeforeOp = null;
+		return isBatch ? newConfigs : newConfigs[0];
 	}
-	async dragTo(config, targetParent, targetIndex) {
+	async dragTo(config, targetParent, targetIndex, { doNotPushHistory = false } = {}) {
 		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,23 +730,25 @@ 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", { updatedItems }, {
+				name: pageForOp?.name || "",
+				id: pageForOp.id
+			});
+		} else this.selectionBeforeOp = null;
 		this.emit("drag-to", {
 			targetIndex,
 			configs,
@@ -740,7 +773,107 @@ var Editor = class extends BaseService_default {
 		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.getPageStepList()[index];
+		if (!entry?.applied) return null;
+		const { step } = entry;
+		if (!this.get("root")) return null;
+		let revertedStep = null;
+		const captureRevert = (s) => {
+			revertedStep = s;
+		};
+		history_default.once("change", captureRevert);
+		const historyDescription = `回滚 #${index + 1}: ${describeStepForRevert(step)}`;
+		const opts = {
+			doNotSelect: true,
+			doNotSwitchPage: true,
+			historyDescription
+		};
+		try {
+			switch (step.opType) {
+				case "add": {
+					const nodes = step.nodes ?? [];
+					for (const n of nodes) {
+						const existing = this.getNodeById(n.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 parent = this.getNodeById(parentId, false);
+						if (parent) await this.add([cloneDeep$1(node)], parent, opts);
+					}
+					break;
+				}
+				case "update": {
+					const configs = (step.updatedItems ?? []).map(({ oldNode, newNode, changeRecords }) => {
+						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 });
+					break;
+				}
+			}
+		} finally {
+			history_default.off("change", captureRevert);
+		}
+		const page = toRaw(this.get("page"));
+		if (page) this.emit("history-change", page);
+		return revertedStep;
+	}
+	/**
+	* 跳转当前页面历史栈到指定游标位置。
+	*
+	* `targetCursor` 与 `UndoRedo.getCursor()` 同义：表示"已应用步骤数量"，
+	* 取值范围 `[0, length]`。当目标 < 当前游标时循环 undo，否则循环 redo。
+	* 通常由历史面板传入「点击的 step.index + 1」作为目标。
+	*
+	* @returns 实际移动到的最终游标位置
+	*/
+	async gotoPageStep(targetCursor) {
+		let cursor = history_default.getPageCursor();
+		const { length } = history_default.getPageStepList();
+		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 } = {}) {
 		const node = toRaw(this.get("node"));
 		if (!node || isPage(node)) return;
 		const newStyle = calcMoveStyle(node.style || {}, left, top);
@@ -749,7 +882,7 @@ var Editor = class extends BaseService_default {
 			id: node.id,
 			type: node.type,
 			style: newStyle
-		});
+		}, { doNotPushHistory });
 	}
 	resetState() {
 		this.set("root", null);
@@ -783,17 +916,13 @@ 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);
 	}
 	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;
-		}
+	pushOpHistory(opType, extra, pageData, historyDescription) {
 		const step = {
 			data: pageData,
 			opType,
@@ -802,39 +931,101 @@ var Editor = class extends BaseService_default {
 			modifiedNodeIds: new Map(this.get("modifiedNodeIds")),
 			...extra
 		};
-		history_default.push(step);
+		if (historyDescription) step.historyDescription = historyDescription;
+		history_default.push(step, pageData.id);
 		this.selectionBeforeOp = null;
-		this.isHistoryStateChange = false;
 	}
 	/**
 	* 应用历史操作（撤销 / 重做）
+	*
+	* 所有 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;
 		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 nodes = step.nodes ?? [];
+				if (reverse) for (const n of nodes) {
+					const existing = this.getNodeById(n.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)
+								});
+							}
+						}
+					}
+				}
 				break;
-			case "remove":
-				await applyHistoryRemoveOp(step, reverse, ctx);
+			}
+			case "remove": {
+				const items = step.removedItems ?? [];
+				if (reverse) {
+					const sorted = [...items].sort((a, b) => a.index - b.index);
+					for (const { node, parentId, index } of sorted) {
+						const parent = this.getNodeById(parentId, false);
+						if (parent?.items) {
+							parent.items.splice(index, 0, cloneDeep$1(node));
+							await stage?.add({
+								config: cloneDeep$1(node),
+								parent: cloneDeep$1(parent),
+								parentId,
+								root: cloneDeep$1(root)
+							});
+						}
+					}
+				} else for (const { node } of items) {
+					const existing = this.getNodeById(node.id, false);
+					if (existing) await this.remove(existing, commonOpts);
+				}
 				break;
-			case "update":
-				await applyHistoryUpdateOp(step, reverse, ctx);
+			}
+			case "update": {
+				const configs = (step.updatedItems ?? []).map(({ oldNode, newNode, changeRecords }) => {
+					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);
 		const page = toRaw(this.get("page"));
@@ -849,7 +1040,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);