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

package/src/services/editor.ts

@@ -23,7 +23,7 @@ import type { Id, MApp, MContainer, MNode, MPage, MPageFragment, TargetOptions }
 import { NodeType } from '@tmagic/core';
 import type { ChangeRecord } from '@tmagic/form';
 import { isFixed } from '@tmagic/stage';
-import { getNodeInfo, getNodePath, isPage, isPageFragment } from '@tmagic/utils';
+import { getNodeInfo, getNodePath, getValueByKeyPath, isPage, isPageFragment, setValueByKeyPath } from '@tmagic/utils';
 
 import BaseService from '@editor/services//BaseService';
 import propsService from '@editor/services//props';
@@ -62,27 +62,40 @@ import {
   setLayout,
   toggleFixedPosition,
 } from '@editor/utils/editor';
-import type { HistoryOpContext } from '@editor/utils/editor-history';
-import { applyHistoryAddOp, applyHistoryRemoveOp, applyHistoryUpdateOp } from '@editor/utils/editor-history';
 import { beforePaste, getAddParent } from '@editor/utils/operator';
 
-/**
- * 经过 BaseService 的插件 / 中间件包装后，源方法的最后一个形参可能被注入为 dispatch 函数
- * 当 options 形参位置被注入为函数（或为 null）时，将其归一为空对象，避免后续逻辑误读
- */
-const safeOptions = <T extends object>(options: unknown): T => {
-  const empty = {};
-  if (!options || typeof options === 'function') return empty as T;
-  return options as T;
-};
+type MoveItem = { node: MNode; parent: MContainer; pageForOp: { name: string; id: Id } | null };
 
 /**
- * 经过 BaseService 的插件 / 中间件包装后，源方法的形参可能被注入为 dispatch 函数
- * 当 parent 形参位置被注入为函数（或为空值）时，归一为 null，由调用方继续走默认 parent 逻辑
+ * 给「回滚」生成的新 step 用的简短描述生成器。
+ * 与 UI 层 `describePageStep` 同义，但避免 service 反向依赖 layouts/，故在此本地实现。
  */
-const safeParent = (parent: unknown): MContainer | null => {
-  if (!parent || typeof parent === 'function') return null;
-  return parent as MContainer;
+const describeStepForRevert = (step: StepValue): string => {
+  switch (step.opType) {
+    case 'add': {
+      const count = step.nodes?.length ?? 0;
+      const node = step.nodes?.[0];
+      const label = node?.name || node?.type || (node?.id !== undefined ? `${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 !== undefined ? `${node.id}` : '');
+      return `还原已删除的 ${count} 个节点${count === 1 && label ? `（${label}）` : ''}`;
+    }
+    case 'update':
+    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} 个节点的修改`;
+    }
+  }
 };
 
 class Editor extends BaseService {
@@ -101,7 +114,6 @@ class Editor extends BaseService {
     disabledMultiSelect: false,
     alwaysMultiSelect: false,
   });
-  private isHistoryStateChange = false;
   private selectionBeforeOp: Id[] | null = null;
 
   constructor() {
@@ -212,7 +224,7 @@ class Editor extends BaseService {
    * 只有容器拥有布局
    */
   public async getLayout(parent: MNode, node?: MNode | null): Promise<Layout> {
-    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;
@@ -388,16 +400,14 @@ class Editor extends BaseService {
    * @param options 可选配置
    * @param options.doNotSelect 添加后是否不更新当前选中节点（默认 false，添加后会选中新增的节点）
    * @param options.doNotSwitchPage 添加后是否不切换当前页面（默认 false；新增页面 / 跨页新增时为 true 会跳过会引发页面切换的选中操作）
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    * @returns 添加后的节点
    */
   public async add(
     addNode: AddMNode | MNode[],
     parent?: MContainer | null,
-    options?: DslOpOptions,
+    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription }: DslOpOptions = {},
   ): Promise<MNode | MNode[]> {
-    const safeParentNode = safeParent(parent);
-    const { doNotSelect = false, doNotSwitchPage = false } = safeOptions<DslOpOptions>(options);
-
     this.captureSelectionBeforeOp();
 
     const stage = this.get('stage');
@@ -420,7 +430,7 @@ class Editor extends BaseService {
         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);
       }),
@@ -455,20 +465,25 @@ class Editor extends BaseService {
 
     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) as MContainer;
-              return [n.id, p ? getNodeIndex(n.id, p) : -1];
-            }),
-          ),
-        },
-        { name: pageForOp?.name || '', id: pageForOp!.id },
-      );
+      if (!doNotPushHistory) {
+        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) as MContainer;
+                return [n.id, p ? getNodeIndex(n.id, p) : -1];
+              }),
+            ),
+          },
+          { name: pageForOp?.name || '', id: pageForOp!.id },
+          historyDescription,
+        );
+      } else {
+        this.selectionBeforeOp = null;
+      }
     }
 
     this.emit('add', newNodes);
@@ -476,9 +491,10 @@ class Editor extends BaseService {
     return Array.isArray(addNode) ? newNodes : newNodes[0];
   }
 
-  public async doRemove(node: MNode, options?: DslOpOptions): Promise<void> {
-    const { doNotSelect = false, doNotSwitchPage = false } = safeOptions<DslOpOptions>(options);
-
+  public async doRemove(
+    node: MNode,
+    { doNotSelect = false, doNotSwitchPage = false }: DslOpOptions = {},
+  ): Promise<void> {
     const root = this.get('root');
     if (!root) throw new Error('root不能为空');
 
@@ -557,10 +573,12 @@ class Editor extends BaseService {
    * @param options 可选配置
    * @param options.doNotSelect 删除后是否不更新当前选中节点（默认 false，删除后会选中父节点或首个页面）
    * @param options.doNotSwitchPage 删除后是否不切换当前页面（默认 false；删除页面 / 页面片段时为 true 会跳过自动切换到首个剩余页面）
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    */
-  public async remove(nodeOrNodeList: MNode | MNode[], options?: DslOpOptions): Promise<void> {
-    const { doNotSelect = false, doNotSwitchPage = false } = safeOptions<DslOpOptions>(options);
-
+  public async remove(
+    nodeOrNodeList: MNode | MNode[],
+    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription }: DslOpOptions = {},
+  ): Promise<void> {
     this.captureSelectionBeforeOp();
 
     const nodes = Array.isArray(nodeOrNodeList) ? nodeOrNodeList : [nodeOrNodeList];
@@ -587,7 +605,11 @@ class Editor extends BaseService {
     await Promise.all(nodes.map((node) => this.doRemove(node, { doNotSelect, doNotSwitchPage })));
 
     if (removedItems.length > 0 && pageForOp) {
-      this.pushOpHistory('remove', { removedItems }, pageForOp);
+      if (!doNotPushHistory) {
+        this.pushOpHistory('remove', { removedItems }, pageForOp, historyDescription);
+      } else {
+        this.selectionBeforeOp = null;
+      }
     }
 
     this.emit('remove', nodes);
@@ -668,34 +690,60 @@ class Editor extends BaseService {
    * 更新节点
    * 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 更新后的节点配置
    */
   public async update(
     config: MNode | MNode[],
-    data: { changeRecords?: ChangeRecord[] } = {},
+    data: {
+      changeRecords?: ChangeRecord[];
+      changeRecordList?: ChangeRecord[][];
+      doNotPushHistory?: boolean;
+      historyDescription?: string;
+    } = {},
   ): Promise<MNode | MNode[]> {
     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)));
+    // 多节点必须使用 changeRecordList 为每个节点提供独立的记录；
+    // 否则同一份 changeRecords 会被复用到每个节点上，nodeUpdateHandler / 历史回放都会按错误的 propPath 处理。
+    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) {
-        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 },
-        );
+      if (curNodes.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)),
+                // 每个节点单独保留自己的 changeRecords，便于撤销/重做时按 propPath 精细化更新；
+                // 没有 changeRecords 的（如内部 sort/moveLayer 等整节点替换操作）会退化为全节点替换。
+                changeRecords: d.changeRecords?.length ? cloneDeep(d.changeRecords) : undefined,
+              })),
+            },
+            { name: pageForOp?.name || '', id: pageForOp!.id },
+            historyDescription,
+          );
+        } else {
+          this.selectionBeforeOp = null;
+        }
       }
-      this.isHistoryStateChange = false;
     }
 
     this.emit('update', updateData);
@@ -709,11 +757,14 @@ class Editor extends BaseService {
    * @param options 可选配置
    * @param options.doNotSelect 排序后是否不更新当前选中节点（默认 false）
    * @param options.doNotSwitchPage 排序后是否不切换当前页面（排序只发生在同一父节点内，方法内为空操作；保留以与其它 DSL 操作 API 一致）
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    * @returns void
    */
-  public async sort(id1: Id, id2: Id, options?: DslOpOptions): Promise<void> {
-    const { doNotSelect = false } = safeOptions<DslOpOptions>(options);
-
+  public async sort(
+    id1: Id,
+    id2: Id,
+    { doNotSelect = false, doNotPushHistory = false }: DslOpOptions = {},
+  ): Promise<void> {
     this.captureSelectionBeforeOp();
 
     const root = this.get('root');
@@ -732,7 +783,7 @@ class Editor extends BaseService {
 
     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);
     }
@@ -779,15 +830,14 @@ class Editor extends BaseService {
    * @param options 可选配置
    * @param options.doNotSelect 粘贴后是否不更新当前选中节点（默认 false）
    * @param options.doNotSwitchPage 粘贴后是否不切换当前页面（默认 false；跨页粘贴时为 true 会跳过页面切换）
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    * @returns 添加后的组件节点配置
    */
   public async paste(
     position: PastePosition = {},
     collectorOptions?: TargetOptions,
-    options?: DslOpOptions,
+    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false }: DslOpOptions = {},
   ): Promise<MNode | MNode[] | void> {
-    const { doNotSelect = false, doNotSwitchPage = false } = safeOptions<DslOpOptions>(options);
-
     const config: MNode[] = storageService.getItem(COPY_STORAGE_KEY);
     if (!Array.isArray(config)) return;
 
@@ -807,7 +857,7 @@ class Editor extends BaseService {
       propsService.replaceRelateId(config, pasteConfigs, collectorOptions);
     }
 
-    return this.add(pasteConfigs, parent, { doNotSelect, doNotSwitchPage });
+    return this.add(pasteConfigs, parent, { doNotSelect, doNotSwitchPage, doNotPushHistory });
   }
 
   public async doPaste(config: MNode[], position: PastePosition = {}): Promise<MNode[]> {
@@ -838,17 +888,19 @@ class Editor extends BaseService {
    * @param options 可选配置
    * @param options.doNotSelect 居中后是否不更新当前选中节点（默认 false）
    * @param options.doNotSwitchPage 居中后是否不切换当前页面（居中只更新节点 style，方法内为空操作；保留以与其它 DSL 操作 API 一致）
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    * @returns 当前组件节点配置
    */
-  public async alignCenter(config: MNode | MNode[], options?: DslOpOptions): Promise<MNode | MNode[]> {
-    const { doNotSelect = false } = safeOptions<DslOpOptions>(options);
-
+  public async alignCenter(
+    config: MNode | MNode[],
+    { doNotSelect = false, doNotPushHistory = false }: DslOpOptions = {},
+  ): Promise<MNode | MNode[]> {
     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) {
@@ -864,8 +916,10 @@ class Editor extends BaseService {
   /**
    * 移动当前选中节点位置
    * @param offset 偏移量
+   * @param options 可选配置
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    */
-  public async moveLayer(offset: number | LayerOffset): Promise<void> {
+  public async moveLayer(offset: number | LayerOffset, { doNotPushHistory = false }: DslOpOptions = {}): Promise<void> {
     this.captureSelectionBeforeOp();
 
     const root = this.get('root');
@@ -902,94 +956,116 @@ class Editor extends BaseService {
     });
 
     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(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）
    */
-  public async moveToContainer(config: MNode, targetId: Id, options?: DslOpOptions): Promise<MNode | undefined> {
-    const { doNotSelect = false, doNotSwitchPage = false } = safeOptions<DslOpOptions>(options);
+  public async moveToContainer(
+    config: MNode | MNode[],
+    targetId: Id,
+    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false }: DslOpOptions = {},
+  ): Promise<MNode | MNode[]> {
+    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) as MContainer;
 
-    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);
+    if (!target) {
+      throw new Error('目标容器不存在');
+    }
 
-      target.items.push(newConfig);
+    const root = this.get('root');
+    const stage = this.get('stage');
 
-      // 目标容器是否在非当前页面：选中目标会触发当前页面切换
-      const targetWouldSwitchPage = this.isOnDifferentPage(target);
-      const skipSelect = doNotSelect || (doNotSwitchPage && targetWouldSwitchPage);
+    if (!root || !stage) {
+      throw new Error('root 或 stage为空');
+    }
 
-      if (!skipSelect) {
-        await stage.select(targetId);
-      }
+    // 收集 (节点, 源父) 信息，过滤掉异常节点（找不到父或源父等于目标本身）
+    const moves: MoveItem[] = [];
+    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 });
+    }
 
-      const targetParent = this.getParentById(target.id);
-      await stage.update({
-        config: cloneDeep(target),
-        parentId: targetParent?.id,
-        root: cloneDeep(root),
-      });
+    if (moves.length === 0) {
+      throw new Error('没有可移动的节点');
+    }
 
-      if (!skipSelect) {
-        await this.select(newConfig);
-        stage.select(newConfig.id);
+    // 记录所有涉及的源父容器（按 id 去重）+ 目标容器的前置快照；同一父容器只快照一次。
+    const beforeSnapshots = new Map<Id, MNode>();
+    beforeSnapshots.set(target.id, cloneDeep(toRaw(target)));
+    for (const { parent } of moves) {
+      if (!beforeSnapshots.has(parent.id)) {
+        beforeSnapshots.set(parent.id, cloneDeep(toRaw(parent)));
       }
+    }
 
-      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 },
-      );
-
-      return newConfig;
+    let newConfigs: MNode[] = [];
+
+    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,
+    })) as MNode[];
+
+    if (!doNotPushHistory) {
+      // 整批只入栈一条历史：updatedItems 包含所有源父容器 + 目标容器的前后快照（撤销/重做最小依赖）。
+      const updatedItems = Array.from(beforeSnapshots.entries()).map(([id, oldNode]) => ({
+        oldNode,
+        newNode: cloneDeep(toRaw(this.getNodeById(id, false))) as MNode,
+      }));
+      const historyPage = moves[0].pageForOp ?? { name: '', id: target.id };
+      this.pushOpHistory('update', { updatedItems }, historyPage);
+    } else {
+      this.selectionBeforeOp = null;
     }
+
+    return isBatch ? newConfigs : newConfigs[0];
   }
 
-  public async dragTo(config: MNode | MNode[], targetParent: MContainer, targetIndex: number) {
+  public async dragTo(
+    config: MNode | MNode[],
+    targetParent: MContainer,
+    targetIndex: number,
+    { doNotPushHistory = false }: DslOpOptions = {},
+  ) {
     this.captureSelectionBeforeOp();
 
     if (!targetParent || !Array.isArray(targetParent.items)) return;
@@ -1049,8 +1125,12 @@ class Editor extends BaseService {
         updatedItems.push({ oldNode, newNode: cloneDeep(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, targetParent });
   }
@@ -1079,14 +1159,140 @@ class Editor extends BaseService {
     return value;
   }
 
-  public async move(left: number, top: number) {
+  /**
+   * 「回滚」指定页面历史步骤（类 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
+   */
+  public async revertPageStep(index: number): Promise<StepValue | null> {
+    const list = historyService.getPageStepList();
+    const entry = list[index];
+    if (!entry?.applied) return null;
+
+    const { step } = entry;
+    const root = this.get('root');
+    if (!root) return null;
+
+    // 反向应用产生的新 step 由内部 pushOpHistory 触发 history `change` 事件，监听一次以拿到引用。
+    let revertedStep: StepValue | null = null;
+    const captureRevert = (s: StepValue) => {
+      revertedStep = s;
+    };
+    historyService.once('change', captureRevert);
+
+    const historyDescription = `回滚 #${index + 1}: ${describeStepForRevert(step)}`;
+    // revert 走 public add/remove/update，让操作以一条普通新 step 入栈；不要切换选区与页面，避免打断用户。
+    const opts = { doNotSelect: true, doNotSwitchPage: true, historyDescription } as const;
+
+    try {
+      switch (step.opType) {
+        case 'add': {
+          // 原本是新增 → revert 即删除当时被加入的节点
+          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': {
+          // 原本是删除 → revert 即把节点按原父容器加回来。
+          // 按原 index 升序逐个插回，先小后大避免索引漂移。
+          const items = step.removedItems ?? [];
+          const sorted = [...items].sort((a, b) => a.index - b.index);
+          for (const { node, parentId } of sorted) {
+            const parent = this.getNodeById(parentId, false) as MContainer | null;
+            if (parent) {
+              await this.add([cloneDeep(node)] as MNode[], parent, opts);
+            }
+          }
+          break;
+        }
+        case 'update': {
+          // 原本是更新 → revert 即把 oldNode 的值写回；
+          // 优先按 changeRecords 局部 patch（仅触达 propPath 下的字段，避免冲掉同节点上其它无关变更）。
+          const items = step.updatedItems ?? [];
+          const configs = items.map(({ oldNode, newNode, changeRecords }) => {
+            if (changeRecords?.length) {
+              const patch: MNode = { id: newNode.id, type: newNode.type };
+              for (const record of changeRecords) {
+                if (!record.propPath) {
+                  // 没有 propPath 视为整节点替换
+                  return cloneDeep(oldNode);
+                }
+                const value = cloneDeep(getValueByKeyPath(record.propPath, oldNode));
+                setValueByKeyPath(record.propPath, value, patch);
+              }
+              return patch;
+            }
+            return cloneDeep(oldNode);
+          });
+          if (configs.length) {
+            await this.update(configs, { historyDescription });
+          }
+          break;
+        }
+      }
+    } finally {
+      historyService.off('change', captureRevert);
+    }
+
+    // 通知一次 history-change，让上层（如属性面板）按当前最新 DSL 刷新
+    const page = toRaw(this.get('page'));
+    if (page) {
+      this.emit('history-change', page as MPage | MPageFragment);
+    }
+
+    return revertedStep;
+  }
+
+  /**
+   * 跳转当前页面历史栈到指定游标位置。
+   *
+   * `targetCursor` 与 `UndoRedo.getCursor()` 同义：表示"已应用步骤数量"，
+   * 取值范围 `[0, length]`。当目标 < 当前游标时循环 undo，否则循环 redo。
+   * 通常由历史面板传入「点击的 step.index + 1」作为目标。
+   *
+   * @returns 实际移动到的最终游标位置
+   */
+  public async gotoPageStep(targetCursor: number): Promise<number> {
+    let cursor = historyService.getPageCursor();
+    const { length } = historyService.getPageStepList();
+    const target = Math.max(0, Math.min(targetCursor, length));
+    while (cursor > target) {
+      const step = await this.undo();
+      if (!step) break;
+      cursor -= 1;
+    }
+    while (cursor < target) {
+      const step = await this.redo();
+      if (!step) break;
+      cursor += 1;
+    }
+    return cursor;
+  }
+
+  public async move(left: number, top: number, { doNotPushHistory = false }: DslOpOptions = {}) {
     const node = toRaw(this.get('node'));
     if (!node || isPage(node)) return;
 
     const newStyle = calcMoveStyle(node.style || {}, left, top);
     if (!newStyle) return;
 
-    await this.update({ id: node.id, type: node.type, style: newStyle });
+    await this.update({ id: node.id, type: node.type, style: newStyle }, { doNotPushHistory });
   }
 
   public resetState() {
@@ -1134,22 +1340,20 @@ class Editor extends BaseService {
   }
 
   private addModifiedNodeId(id: Id) {
-    if (!this.isHistoryStateChange) {
-      this.get('modifiedNodeIds').set(id, id);
-    }
+    this.get('modifiedNodeIds').set(id, id);
   }
 
   private captureSelectionBeforeOp() {
-    if (this.isHistoryStateChange || this.selectionBeforeOp) return;
+    if (this.selectionBeforeOp) return;
     this.selectionBeforeOp = this.get('nodes').map((n) => n.id);
   }
 
-  private pushOpHistory(opType: HistoryOpType, extra: Partial<StepValue>, pageData: { name: string; id: Id }) {
-    if (this.isHistoryStateChange) {
-      this.selectionBeforeOp = null;
-      return;
-    }
-
+  private pushOpHistory(
+    opType: HistoryOpType,
+    extra: Partial<StepValue>,
+    pageData: { name: string; id: Id },
+    historyDescription?: string,
+  ) {
     const step: StepValue = {
       data: pageData,
       opType,
@@ -1158,43 +1362,124 @@ class Editor extends BaseService {
       modifiedNodeIds: new Map(this.get('modifiedNodeIds')),
       ...extra,
     };
-    historyService.push(step);
+    if (historyDescription) step.historyDescription = historyDescription;
+    // 显式按 step.data.id 入栈：跨页操作（如 moveToContainer 从源页搬到目标页）
+    // 必须落到正确的页面栈，否则会把记录错误地推到当前活动页 / 操作发起页。
+    historyService.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 = 重做
    */
   private async applyHistoryOp(step: StepValue, reverse: boolean) {
-    this.isHistoryStateChange = true;
-
     const root = this.get('root');
     const stage = this.get('stage');
     if (!root) return;
 
-    const ctx: HistoryOpContext = {
-      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 } as const;
 
     switch (step.opType) {
-      case 'add':
-        await applyHistoryAddOp(step, reverse, ctx);
+      case 'add': {
+        const nodes = step.nodes ?? [];
+        if (reverse) {
+          // 撤销 add：把当时加入的节点删除
+          for (const n of nodes) {
+            const existing = this.getNodeById(n.id, false);
+            if (existing) {
+              await this.remove(existing, commonOpts);
+            }
+          }
+        } else {
+          // 重做 add：按记录的 indexMap 把节点重新插回父容器
+          const parent = this.getNodeById(step.parentId!, false) as MContainer | null;
+          if (parent) {
+            // 按目标 index 升序逐个插入，先小后大避免索引漂移
+            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(n));
+                } else {
+                  parent.items.push(cloneDeep(n));
+                }
+                await stage?.add({
+                  config: cloneDeep(n),
+                  parent: cloneDeep(parent),
+                  parentId: parent.id,
+                  root: cloneDeep(root),
+                });
+              }
+            }
+          }
+        }
         break;
-      case 'remove':
-        await applyHistoryRemoveOp(step, reverse, ctx);
+      }
+      case 'remove': {
+        const items = step.removedItems ?? [];
+        if (reverse) {
+          // 撤销 remove：按原 index 升序逐个插回（先小后大避免索引漂移）
+          const sorted = [...items].sort((a, b) => a.index - b.index);
+          for (const { node, parentId, index } of sorted) {
+            const parent = this.getNodeById(parentId, false) as MContainer | null;
+            if (parent?.items) {
+              parent.items.splice(index, 0, cloneDeep(node));
+              await stage?.add({
+                config: cloneDeep(node),
+                parent: cloneDeep(parent),
+                parentId,
+                root: cloneDeep(root),
+              });
+            }
+          }
+        } else {
+          // 重做 remove：再删一次
+          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 items = step.updatedItems ?? [];
+        // 优先按 changeRecords 局部 patch：仅触达 propPath 下的字段，避免整节点替换冲掉同节点上其它无关变更。
+        // 没有 changeRecords 的（如内部 sort/moveLayer/拖动等整节点快照场景）才退化为整节点替换。
+        const configs = items.map(({ oldNode, newNode, changeRecords }) => {
+          if (changeRecords?.length) {
+            const sourceForValues = reverse ? oldNode : newNode;
+            // 仅保留 id / type 作为最小骨架，再按 propPath 写入需要回滚/重做的字段；
+            // 后续 update -> mergeWith 会与现有节点深合并，patch 中未涉及的字段不会被改动。
+            const patch: MNode = { id: newNode.id, type: newNode.type };
+            for (const record of changeRecords) {
+              if (!record.propPath) {
+                // 没有 propPath 视为整节点替换
+                return cloneDeep(sourceForValues);
+              }
+              const value = cloneDeep(getValueByKeyPath(record.propPath, sourceForValues));
+              setValueByKeyPath(record.propPath, value, patch);
+            }
+            return patch;
+          }
+          return cloneDeep(reverse ? oldNode : newNode);
+        });
+        if (configs.length) {
+          await this.update(configs, { doNotPushHistory: true });
+        }
         break;
+      }
     }
 
     this.set('modifiedNodeIds', step.modifiedNodeIds);
@@ -1216,8 +1501,6 @@ class Editor extends BaseService {
       }, 0);
       this.emit('history-change', page as MPage | MPageFragment);
     }
-
-    this.isHistoryStateChange = false;
   }
 
   private selectedConfigExceptionHandler(config: MNode | Id): EditorNodeInfo {