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

package/src/services/editor.ts

@@ -17,13 +17,21 @@
  */
 
 import { reactive, toRaw } from 'vue';
-import { cloneDeep, isObject, mergeWith, uniq } from 'lodash-es';
+import { cloneDeep, isEmpty, isEqual, isObject, mergeWith, uniq } from 'lodash-es';
 
 import type { Id, MApp, MContainer, MNode, MPage, MPageFragment, TargetOptions } from '@tmagic/core';
 import { NodeType } from '@tmagic/core';
 import type { ChangeRecord } from '@tmagic/form';
 import { isFixed } from '@tmagic/stage';
-import { getNodeInfo, getNodePath, getValueByKeyPath, isPage, isPageFragment, setValueByKeyPath } from '@tmagic/utils';
+import {
+  getNodeInfo,
+  getNodePath,
+  getValueByKeyPath,
+  guid,
+  isPage,
+  isPageFragment,
+  setValueByKeyPath,
+} from '@tmagic/utils';
 
 import BaseService from '@editor/services//BaseService';
 import propsService from '@editor/services//props';
@@ -36,8 +44,10 @@ import type {
   DslOpOptions,
   EditorEvents,
   EditorNodeInfo,
+  HistoryOpSource,
   HistoryOpType,
   PastePosition,
+  StepDiffItem,
   StepValue,
   StoreState,
   StoreStateKey,
@@ -50,6 +60,7 @@ import {
   classifyDragSources,
   collectRelatedNodes,
   COPY_STORAGE_KEY,
+  describeStepForRevert,
   editorNodeMergeCustomizer,
   fixNodePosition,
   getInitPositionStyle,
@@ -67,36 +78,18 @@ import { beforePaste, getAddParent } from '@editor/utils/operator';
 type MoveItem = { node: MNode; parent: MContainer; pageForOp: { name: string; id: Id } | null };
 
 /**
- * 给「回滚」生成的新 step 用的简短描述生成器。
- * 与 UI 层 `describePageStep` 同义，但避免 service 反向依赖 layouts/，故在此本地实现。
+ * 把「变更前后节点快照」列表归一成 update 类型的 {@link StepDiffItem} 列表，供 {@link StepValue.diff} 使用。
+ * `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
+ * 缺省（未传 / 空数组）才退化为整节点替换。
  */
-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} 个节点的修改`;
-    }
-  }
-};
+const buildUpdateDiff = (
+  items: { oldNode: MNode; newNode: MNode; changeRecords?: ChangeRecord[] }[],
+): StepDiffItem<MNode>[] =>
+  items.map(({ oldNode, newNode, changeRecords }) => ({
+    oldSchema: oldNode,
+    newSchema: newNode,
+    ...(changeRecords?.length ? { changeRecords } : {}),
+  }));
 
 class Editor extends BaseService {
   public state: StoreState = reactive({
@@ -115,6 +108,12 @@ class Editor extends BaseService {
     alwaysMultiSelect: false,
   });
   private selectionBeforeOp: Id[] | null = null;
+  /**
+   * 最近一次 pushOpHistory 写入的历史记录 uuid。
+   * 供 *AndGetHistoryId 系列方法在调用普通操作后取回本次产生的历史记录 id；
+   * 普通操作不会读取它，调用前由 *AndGetHistoryId 重置为 null。
+   */
+  private lastPushedHistoryId: string | null = null;
 
   constructor() {
     super(
@@ -128,8 +127,13 @@ class Editor extends BaseService {
    * 设置当前指点节点配置
    * @param name 'root' | 'page' | 'parent' | 'node' | 'highlightNode' | 'nodes' | 'stage' | 'modifiedNodeIds' | 'pageLength' | 'pageFragmentLength
    * @param value MNode
+   * @param options.historySource 设置 root 时，本次变更写入历史记录的「操作来源」（仅 name === 'root' 时生效）
    */
-  public set<K extends StoreStateKey, T extends StoreState[K]>(name: K, value: T) {
+  public set<K extends StoreStateKey, T extends StoreState[K]>(
+    name: K,
+    value: T,
+    options: { historySource?: HistoryOpSource } = {},
+  ) {
     const preValue = this.state[name];
     this.state[name] = value;
 
@@ -148,6 +152,25 @@ class Editor 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)) {
+          // 编辑期间再次整体设置 root（源码保存 / 外部重设 DSL / root 节点更新）：与上一次 root
+          // 做页面级 diff，按 update / add / remove 入栈，作为正常历史记录体现整体替换。
+          this.pushRootDiffHistory(preValue as MApp, app, options.historySource);
+        } else {
+          // 首次设置 root：仅当该页面 / 页面片尚无基线标记时，才写入「未修改的初始状态」基线。
+          // 配合「先恢复历史再 set root」：若基线已随历史恢复建立（恢复后已有基线），则此处不再
+          // 重复创建，set root 不额外产生记录，由恢复出的历史栈作为当前状态来源。
+          // 标记不进入撤销/重做栈，仅作为该页历史列表底部的初始基线展示。
+          app.items?.forEach((pageNode) => {
+            if (pageNode?.id !== undefined && !historyService.getPageMarker(pageNode.id)) {
+              historyService.setPageMarker(pageNode.id, {
+                name: pageNode.name,
+                source: options.historySource,
+              });
+            }
+          });
+        }
       } else {
         this.state.pageLength = 0;
         this.state.pageFragmentLength = 0;
@@ -179,7 +202,30 @@ class Editor extends BaseService {
       root = toRaw(root);
     }
 
-    return getNodeInfo(id, root);
+    if (!root) {
+      return { node: null, parent: null, page: null };
+    }
+
+    if (id === root.id) {
+      return { node: root, parent: null, page: null };
+    }
+
+    // 大多数查找的目标都在当前页面内，优先在当前页面子树中查找以避免对整棵树做全量遍历。
+    // 注意：不能直接使用 state.page，它可能与当前 root 不同步（指向已脱离的旧页面对象），
+    // 因此仅借用其 id，再从当前 root 中取回真正的页面对象（页面均为 root 的直接子节点，数量很少）。
+    const pageIdStr = `${this.get('page')?.id || ''}`;
+    const currentPageNode = root.items?.find((item) => `${item.id}` === pageIdStr);
+    if (currentPageNode && `${id}` !== pageIdStr) {
+      // util 仅读取 root.id 与 root.items，按容器结构传入当前页面是安全的
+      const info = getNodeInfo(id, currentPageNode);
+      if (info.node) {
+        return info;
+      }
+    }
+
+    // 回退：在完整 root 上查找；当前页面已搜索过，用 skip 跳过其子树避免重复遍历，
+    // 同时保留真实的 parent / page 引用（id 命中当前页面节点本身时会在跳过子树前先匹配到）
+    return getNodeInfo(id, root, currentPageNode);
   }
 
   /**
@@ -406,7 +452,13 @@ class Editor extends BaseService {
   public async add(
     addNode: AddMNode | MNode[],
     parent?: MContainer | null,
-    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription }: DslOpOptions = {},
+    {
+      doNotSelect = false,
+      doNotSwitchPage = false,
+      doNotPushHistory = false,
+      historyDescription,
+      historySource,
+    }: DslOpOptions = {},
   ): Promise<MNode | MNode[]> {
     this.captureSelectionBeforeOp();
 
@@ -466,21 +518,21 @@ class Editor extends BaseService {
     if (!(isPage(newNodes[0]) || isPageFragment(newNodes[0]))) {
       const pageForOp = this.getNodeInfo(newNodes[0].id, false).page;
       if (!doNotPushHistory) {
-        this.pushOpHistory(
-          'add',
-          {
-            nodes: newNodes.map((n) => cloneDeep(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 },
+        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) as MContainer;
+            const idx = p ? getNodeIndex(n.id, p) : -1;
+            return {
+              newSchema: cloneDeep(toRaw(n)),
+              parentId,
+              index: typeof idx === 'number' ? idx : -1,
+            };
+          }),
+          pageData: { name: pageForOp?.name || '', id: pageForOp!.id },
           historyDescription,
-        );
+          source: historySource,
+        });
       } else {
         this.selectionBeforeOp = null;
       }
@@ -577,13 +629,19 @@ class Editor extends BaseService {
    */
   public async remove(
     nodeOrNodeList: MNode | MNode[],
-    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false, historyDescription }: DslOpOptions = {},
+    {
+      doNotSelect = false,
+      doNotSwitchPage = false,
+      doNotPushHistory = false,
+      historyDescription,
+      historySource,
+    }: DslOpOptions = {},
   ): Promise<void> {
     this.captureSelectionBeforeOp();
 
     const nodes = Array.isArray(nodeOrNodeList) ? nodeOrNodeList : [nodeOrNodeList];
 
-    const removedItems: { node: MNode; parentId: Id; index: number }[] = [];
+    const removedItems: StepDiffItem<MNode>[] = [];
     let pageForOp: { name: string; id: Id } | null = null;
     if (!(isPage(nodes[0]) || isPageFragment(nodes[0]))) {
       for (const n of nodes) {
@@ -594,7 +652,7 @@ class Editor extends BaseService {
           }
           const idx = getNodeIndex(curNode.id, parent);
           removedItems.push({
-            node: cloneDeep(toRaw(curNode)),
+            oldSchema: cloneDeep(toRaw(curNode)),
             parentId: parent.id,
             index: typeof idx === 'number' ? idx : -1,
           });
@@ -606,7 +664,12 @@ class Editor extends BaseService {
 
     if (removedItems.length > 0 && pageForOp) {
       if (!doNotPushHistory) {
-        this.pushOpHistory('remove', { removedItems }, pageForOp, historyDescription);
+        this.pushOpHistory('remove', {
+          diff: removedItems,
+          pageData: pageForOp,
+          historyDescription,
+          source: historySource,
+        });
       } else {
         this.selectionBeforeOp = null;
       }
@@ -617,7 +680,7 @@ class Editor extends BaseService {
 
   public async doUpdate(
     config: MNode,
-    { changeRecords = [] }: { changeRecords?: ChangeRecord[] } = {},
+    { changeRecords = [], historySource }: { changeRecords?: ChangeRecord[]; historySource?: HistoryOpSource } = {},
   ): Promise<{ newNode: MNode; oldNode: MNode; changeRecords?: ChangeRecord[] }> {
     const root = this.get('root');
     if (!root) throw new Error('root为空');
@@ -637,7 +700,7 @@ class Editor extends BaseService {
     if (!newConfig.type) throw new Error('配置缺少type值');
 
     if (newConfig.type === NodeType.ROOT) {
-      this.set('root', newConfig as MApp);
+      this.set('root', newConfig as MApp, { historySource });
       return {
         oldNode: node,
         newNode: newConfig,
@@ -704,11 +767,12 @@ class Editor extends BaseService {
       changeRecordList?: ChangeRecord[][];
       doNotPushHistory?: boolean;
       historyDescription?: string;
+      historySource?: HistoryOpSource;
     } = {},
   ): Promise<MNode | MNode[]> {
     this.captureSelectionBeforeOp();
 
-    const { doNotPushHistory = false, changeRecordList, changeRecords, historyDescription } = data;
+    const { doNotPushHistory = false, changeRecordList, changeRecords, historyDescription, historySource } = data;
 
     const nodes = Array.isArray(config) ? config : [config];
 
@@ -717,7 +781,7 @@ class Editor extends BaseService {
     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 });
       }),
     );
 
@@ -726,20 +790,20 @@ class Editor extends BaseService {
       if (curNodes.length) {
         if (!doNotPushHistory) {
           const pageForOp = this.getNodeInfo(nodes[0].id, false).page;
-          this.pushOpHistory(
-            'update',
-            {
-              updatedItems: updateData.map((d) => ({
+          this.pushOpHistory('update', {
+            // 每个节点单独保留自己的 changeRecords，便于撤销/重做时按 propPath 精细化更新；
+            // 没有 changeRecords 的（如内部 sort/moveLayer 等整节点替换操作）会退化为全节点替换。
+            diff: buildUpdateDiff(
+              updateData.map((d) => ({
                 oldNode: cloneDeep(d.oldNode),
-                newNode: cloneDeep(toRaw(d.newNode)),
-                // 每个节点单独保留自己的 changeRecords，便于撤销/重做时按 propPath 精细化更新；
-                // 没有 changeRecords 的（如内部 sort/moveLayer 等整节点替换操作）会退化为全节点替换。
+                newNode: cloneDeep(d.newNode),
                 changeRecords: d.changeRecords?.length ? cloneDeep(d.changeRecords) : undefined,
               })),
-            },
-            { name: pageForOp?.name || '', id: pageForOp!.id },
+            ),
+            pageData: { name: pageForOp?.name || '', id: pageForOp!.id },
             historyDescription,
-          );
+            source: historySource,
+          });
         } else {
           this.selectionBeforeOp = null;
         }
@@ -763,7 +827,7 @@ class Editor extends BaseService {
   public async sort(
     id1: Id,
     id2: Id,
-    { doNotSelect = false, doNotPushHistory = false }: DslOpOptions = {},
+    { doNotSelect = false, doNotPushHistory = false, historySource }: DslOpOptions = {},
   ): Promise<void> {
     this.captureSelectionBeforeOp();
 
@@ -783,7 +847,7 @@ class Editor extends BaseService {
 
     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);
     }
@@ -836,7 +900,13 @@ class Editor extends BaseService {
   public async paste(
     position: PastePosition = {},
     collectorOptions?: TargetOptions,
-    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false }: DslOpOptions = {},
+    {
+      doNotSelect = false,
+      doNotSwitchPage = false,
+      doNotPushHistory = false,
+      historyDescription,
+      historySource,
+    }: DslOpOptions = {},
   ): Promise<MNode | MNode[] | void> {
     const config: MNode[] = storageService.getItem(COPY_STORAGE_KEY);
     if (!Array.isArray(config)) return;
@@ -857,7 +927,13 @@ class Editor extends BaseService {
       propsService.replaceRelateId(config, pasteConfigs, collectorOptions);
     }
 
-    return this.add(pasteConfigs, parent, { doNotSelect, doNotSwitchPage, doNotPushHistory });
+    return this.add(pasteConfigs, parent, {
+      doNotSelect,
+      doNotSwitchPage,
+      doNotPushHistory,
+      historyDescription,
+      historySource,
+    });
   }
 
   public async doPaste(config: MNode[], position: PastePosition = {}): Promise<MNode[]> {
@@ -893,14 +969,14 @@ class Editor extends BaseService {
    */
   public async alignCenter(
     config: MNode | MNode[],
-    { doNotSelect = false, doNotPushHistory = false }: DslOpOptions = {},
+    { doNotSelect = false, doNotPushHistory = false, historyDescription, historySource }: 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, { doNotPushHistory });
+    const newNode = await this.update(newNodes, { doNotPushHistory, historyDescription, historySource });
 
     if (!doNotSelect) {
       if (newNodes.length > 1) {
@@ -919,7 +995,10 @@ class Editor extends BaseService {
    * @param options 可选配置
    * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    */
-  public async moveLayer(offset: number | LayerOffset, { doNotPushHistory = false }: DslOpOptions = {}): Promise<void> {
+  public async moveLayer(
+    offset: number | LayerOffset,
+    { doNotPushHistory = false, historyDescription, historySource }: DslOpOptions = {},
+  ): Promise<void> {
     this.captureSelectionBeforeOp();
 
     const root = this.get('root');
@@ -960,10 +1039,13 @@ class Editor extends BaseService {
       const pageForOp = this.getNodeInfo(node.id, false).page;
       this.pushOpHistory(
         'update',
+
         {
-          updatedItems: [{ oldNode: oldParent, newNode: cloneDeep(toRaw(parent)) }],
+          diff: buildUpdateDiff([{ oldNode: oldParent, newNode: cloneDeep(toRaw(parent)) }]),
+          pageData: { name: pageForOp?.name || '', id: pageForOp!.id },
+          historyDescription,
+          source: historySource,
         },
-        { name: pageForOp?.name || '', id: pageForOp!.id },
       );
     } else {
       this.selectionBeforeOp = null;
@@ -989,7 +1071,13 @@ class Editor extends BaseService {
   public async moveToContainer(
     config: MNode | MNode[],
     targetId: Id,
-    { doNotSelect = false, doNotSwitchPage = false, doNotPushHistory = false }: DslOpOptions = {},
+    {
+      doNotSelect = false,
+      doNotSwitchPage = false,
+      doNotPushHistory = false,
+      historyDescription,
+      historySource,
+    }: DslOpOptions = {},
   ): Promise<MNode | MNode[]> {
     const isBatch = Array.isArray(config);
     const configs = (isBatch ? config : [config]).filter((item) => !(isPage(item) || isPageFragment(item)));
@@ -1052,7 +1140,12 @@ class Editor extends BaseService {
         newNode: cloneDeep(toRaw(this.getNodeById(id, false))) as MNode,
       }));
       const historyPage = moves[0].pageForOp ?? { name: '', id: target.id };
-      this.pushOpHistory('update', { updatedItems }, historyPage);
+      this.pushOpHistory('update', {
+        diff: buildUpdateDiff(updatedItems),
+        pageData: historyPage,
+        historyDescription,
+        source: historySource,
+      });
     } else {
       this.selectionBeforeOp = null;
     }
@@ -1064,7 +1157,7 @@ class Editor extends BaseService {
     config: MNode | MNode[],
     targetParent: MContainer,
     targetIndex: number,
-    { doNotPushHistory = false }: DslOpOptions = {},
+    { doNotPushHistory = false, historyDescription, historySource }: DslOpOptions = {},
   ) {
     this.captureSelectionBeforeOp();
 
@@ -1127,7 +1220,12 @@ class Editor 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;
     }
@@ -1135,6 +1233,86 @@ class Editor extends BaseService {
     this.emit('drag-to', { targetIndex, configs, targetParent });
   }
 
+  // #region AndGetHistoryId
+  /**
+   * 下列 *AndGetHistoryId 方法与对应的普通操作（add / remove / update ...）行为完全一致，
+   * 唯一区别是返回值为本次写入历史栈的历史记录 uuid（{@link StepValue.uuid}），
+   * 而非节点 / 节点数组。可用于精确引用 / 定位该条历史记录（埋点、revert、跨端同步等）。
+   *
+   * 当本次操作未写入历史（doNotPushHistory 为 true、或操作无实际变更 / 提前返回）时返回 null。
+   */
+
+  /** 等价于 {@link add}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public async addAndGetHistoryId(
+    addNode: AddMNode | MNode[],
+    parent?: MContainer | null,
+    options: DslOpOptions = {},
+  ): Promise<string | null> {
+    this.lastPushedHistoryId = null;
+    await this.add(addNode, parent, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link remove}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public async removeAndGetHistoryId(
+    nodeOrNodeList: MNode | MNode[],
+    options: DslOpOptions = {},
+  ): Promise<string | null> {
+    this.lastPushedHistoryId = null;
+    await this.remove(nodeOrNodeList, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link update}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public async updateAndGetHistoryId(
+    config: MNode | MNode[],
+    data: {
+      changeRecords?: ChangeRecord[];
+      changeRecordList?: ChangeRecord[][];
+      doNotPushHistory?: boolean;
+      historyDescription?: string;
+      historySource?: HistoryOpSource;
+    } = {},
+  ): Promise<string | null> {
+    this.lastPushedHistoryId = null;
+    await this.update(config, data);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link moveLayer}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public async moveLayerAndGetHistoryId(
+    offset: number | LayerOffset,
+    options: DslOpOptions = {},
+  ): Promise<string | null> {
+    this.lastPushedHistoryId = null;
+    await this.moveLayer(offset, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link moveToContainer}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public async moveToContainerAndGetHistoryId(
+    config: MNode | MNode[],
+    targetId: Id,
+    options: DslOpOptions = {},
+  ): Promise<string | null> {
+    this.lastPushedHistoryId = null;
+    await this.moveToContainer(config, targetId, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link dragTo}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public async dragToAndGetHistoryId(
+    config: MNode | MNode[],
+    targetParent: MContainer,
+    targetIndex: number,
+    options: DslOpOptions = {},
+  ): Promise<string | null> {
+    this.lastPushedHistoryId = null;
+    await this.dragTo(config, targetParent, targetIndex, options);
+    return this.lastPushedHistoryId;
+  }
+  // #endregion AndGetHistoryId
+
   /**
    * 撤销当前操作
    * @returns 被撤销的操作
@@ -1181,9 +1359,17 @@ class Editor extends BaseService {
     if (!entry?.applied) return null;
 
     const { step } = entry;
+    // 初始基线（index 0 的 initial step）是栈底线，不可回滚。
+    if (step.opType === 'initial') return null;
     const root = this.get('root');
     if (!root) return null;
 
+    // 更新类步骤必须带 changeRecords 才支持回滚：缺失时只能整节点替换，会冲掉后续无关变更，故不支持。
+    if (step.opType === 'update') {
+      const items = step.diff ?? [];
+      if (!items.length || !items.every((item) => item.changeRecords?.length)) return null;
+    }
+
     // 反向应用产生的新 step 由内部 pushOpHistory 触发 history `change` 事件，监听一次以拿到引用。
     let revertedStep: StepValue | null = null;
     const captureRevert = (s: StepValue) => {
@@ -1193,15 +1379,15 @@ class Editor extends BaseService {
 
     const historyDescription = `回滚 #${index + 1}: ${describeStepForRevert(step)}`;
     // revert 走 public add/remove/update，让操作以一条普通新 step 入栈；不要切换选区与页面，避免打断用户。
-    const opts = { doNotSelect: true, doNotSwitchPage: true, historyDescription } as const;
+    const opts = { doNotSelect: true, doNotSwitchPage: true, historyDescription, historySource: 'rollback' } 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);
+          for (const { newSchema } of step.diff ?? []) {
+            if (!newSchema) continue;
+            const existing = this.getNodeById(newSchema.id, false);
             if (existing) {
               await this.remove(existing, opts);
             }
@@ -1211,37 +1397,42 @@ class Editor extends BaseService {
         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 items = step.diff ?? [];
+          const sorted = [...items].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+          for (const { oldSchema, parentId } of sorted) {
+            if (!oldSchema || parentId === undefined) continue;
             const parent = this.getNodeById(parentId, false) as MContainer | null;
             if (parent) {
-              await this.add([cloneDeep(node)] as MNode[], parent, opts);
+              await this.add([cloneDeep(oldSchema)] as MNode[], parent, opts);
             }
           }
           break;
         }
         case 'update': {
-          // 原本是更新 → revert 即把 oldNode 的值写回；
+          // 原本是更新 → revert 即把 oldSchema 的值写回；
           // 优先按 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 items = step.diff ?? [];
+          const configs = items
+            .filter((item) => item.oldSchema && item.newSchema)
+            .map(({ oldSchema, newSchema, changeRecords }) => {
+              const oldNode = oldSchema!;
+              const newNode = newSchema!;
+              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);
                 }
-                const value = cloneDeep(getValueByKeyPath(record.propPath, oldNode));
-                setValueByKeyPath(record.propPath, value, patch);
+                return patch;
               }
-              return patch;
-            }
-            return cloneDeep(oldNode);
-          });
+              return cloneDeep(oldNode);
+            });
           if (configs.length) {
-            await this.update(configs, { historyDescription });
+            await this.update(configs, { historyDescription, historySource: 'rollback' });
           }
           break;
         }
@@ -1259,6 +1450,20 @@ class Editor extends BaseService {
     return revertedStep;
   }
 
+  /**
+   * 通过历史记录 uuid 回滚当前页面的某条历史步骤，语义与 {@link revertPageStep} 完全一致，
+   * 仅入参从 index 改为 uuid（{@link StepValue.uuid}）。uuid 不随栈内步骤增删而变化，
+   * 更适合业务侧持有引用后再回滚（埋点、跨端同步等场景）。
+   *
+   * @param uuid 目标历史记录的 uuid，通常由 *AndGetHistoryId 方法返回
+   * @returns 反向后产生的新 step；找不到对应 uuid / 未应用 / 反向失败时返回 null
+   */
+  public async revertPageStepById(uuid: string): Promise<StepValue | null> {
+    const index = historyService.getPageStepIndexByUuid(uuid);
+    if (index < 0) return null;
+    return this.revertPageStep(index);
+  }
+
   /**
    * 跳转当前页面历史栈到指定游标位置。
    *
@@ -1285,14 +1490,21 @@ class Editor extends BaseService {
     return cursor;
   }
 
-  public async move(left: number, top: number, { doNotPushHistory = false }: DslOpOptions = {}) {
+  public async move(
+    left: number,
+    top: number,
+    { doNotPushHistory = false, historyDescription, historySource }: 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 }, { doNotPushHistory });
+    await this.update(
+      { id: node.id, type: node.type, style: newStyle },
+      { doNotPushHistory, historyDescription, historySource },
+    );
   }
 
   public resetState() {
@@ -1348,25 +1560,119 @@ class Editor extends BaseService {
     this.selectionBeforeOp = this.get('nodes').map((n) => n.id);
   }
 
+  /**
+   * 比较「上一次 root」与「新 root」的页面 / 页面片，按页面粒度把整体替换拆成历史记录：
+   * - 新旧都存在且内容变化的页面 → 一条 `update`（整页快照替换，无 changeRecords）；
+   * - 仅新 root 存在的页面 → 一条 `add`；
+   * - 仅旧 root 存在的页面 → 一条 `remove`。
+   *
+   * 每条记录落到对应页面自己的历史栈（与普通节点操作一致），并标记来源 `source`。
+   * 内容未变化的页面不产生记录，避免重复设置相同 DSL 时产生噪声。
+   */
+  private pushRootDiffHistory(preRoot: MApp, nextRoot: MApp, source?: HistoryOpSource): void {
+    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: MApp, id: Id) => (root.items ?? []).findIndex((item) => `${item.id}` === `${id}`);
+
+    nextPages.forEach((nextPage) => {
+      const prevPage = prevMap.get(`${nextPage.id}`);
+      if (!prevPage) {
+        this.pushPageDiffStep(
+          'add',
+          nextPage,
+          { newSchema: cloneDeep(toRaw(nextPage)), parentId: nextRoot.id, index: indexInItems(nextRoot, nextPage.id) },
+          source,
+        );
+      } else if (!isEqual(toRaw(prevPage), toRaw(nextPage))) {
+        this.pushPageDiffStep(
+          'update',
+          nextPage,
+          { oldSchema: cloneDeep(toRaw(prevPage)), newSchema: cloneDeep(toRaw(nextPage)) },
+          source,
+        );
+      }
+    });
+
+    prevPages.forEach((prevPage) => {
+      if (!nextMap.has(`${prevPage.id}`)) {
+        this.pushPageDiffStep(
+          'remove',
+          prevPage,
+          { oldSchema: cloneDeep(toRaw(prevPage)), parentId: preRoot.id, index: indexInItems(preRoot, prevPage.id) },
+          source,
+        );
+      }
+    });
+  }
+
+  /**
+   * 构造一条页面级「set root」历史记录（不携带选区 / modifiedNodeIds 上下文）并落到该页面自己的栈。
+   *
+   * 连续 set root 替换：若该页栈最新一条已是**同来源**的 set root 记录（{@link StepValue.rootStep} 且 `source` 相同），
+   * 则用本次记录**替换**它而非新增，避免源码反复保存 / 外部重设 DSL 时堆积多条 root 记录；
+   * 来源不同则照常新增（initial 基线不是 rootStep，不在此列）。
+   */
+  private pushPageDiffStep(
+    opType: HistoryOpType,
+    page: MPage | MPageFragment,
+    diffItem: StepDiffItem<MNode>,
+    source?: HistoryOpSource,
+  ): void {
+    const step: StepValue = {
+      uuid: guid(),
+      data: { name: page.name || '', id: page.id },
+      opType,
+      selectedBefore: [],
+      selectedAfter: [],
+      modifiedNodeIds: new Map(),
+      diff: [diffItem],
+      rootStep: true,
+    };
+    if (source) step.source = source;
+
+    const top = historyService.getCurrentPageStep(page.id);
+    if (top?.rootStep && top.source === source) {
+      historyService.replaceCurrentPageStep(step, page.id);
+    } else {
+      historyService.push(step, page.id);
+    }
+  }
+
   private pushOpHistory(
     opType: HistoryOpType,
-    extra: Partial<StepValue>,
-    pageData: { name: string; id: Id },
-    historyDescription?: string,
-  ) {
+    {
+      diff,
+      pageData,
+      historyDescription,
+      source,
+    }: {
+      diff: StepDiffItem<MNode>[];
+      pageData: { name: string; id: Id };
+      historyDescription?: string;
+      source?: HistoryOpSource;
+    },
+  ): string | null {
     const step: StepValue = {
+      uuid: guid(),
       data: pageData,
       opType,
       selectedBefore: this.selectionBeforeOp ?? [],
       selectedAfter: this.get('nodes').map((n) => n.id),
       modifiedNodeIds: new Map(this.get('modifiedNodeIds')),
-      ...extra,
+      diff,
     };
     if (historyDescription) step.historyDescription = historyDescription;
+    if (source) step.source = source;
     // 显式按 step.data.id 入栈：跨页操作（如 moveToContainer 从源页搬到目标页）
     // 必须落到正确的页面栈，否则会把记录错误地推到当前活动页 / 操作发起页。
-    historyService.push(step, pageData.id);
+    const pushed = historyService.push(step, pageData.id);
+    // push 返回 null 表示当前没有可写入的页面栈（未真正入栈），此时不应返回 uuid。
+    const historyId = pushed ? step.uuid : null;
+    this.lastPushedHistoryId = historyId;
     this.selectionBeforeOp = null;
+    return historyId;
   }
 
   /**
@@ -1382,6 +1688,8 @@ class Editor extends BaseService {
    * @param reverse true = 撤销，false = 重做
    */
   private async applyHistoryOp(step: StepValue, reverse: boolean) {
+    // 初始基线 step 仅作展示，不承载任何变更，撤销/重做时无需应用（正常流程下也不会被触达）。
+    if (step.opType === 'initial') return;
     const root = this.get('root');
     const stage = this.get('stage');
     if (!root) return;
@@ -1390,52 +1698,52 @@ class Editor extends BaseService {
 
     switch (step.opType) {
       case 'add': {
-        const nodes = step.nodes ?? [];
+        const items = step.diff ?? [];
         if (reverse) {
           // 撤销 add：把当时加入的节点删除
-          for (const n of nodes) {
-            const existing = this.getNodeById(n.id, false);
+          for (const { newSchema } of items) {
+            if (!newSchema) continue;
+            const existing = this.getNodeById(newSchema.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),
-                });
+          // 重做 add：按记录的 parentId / index 把节点重新插回父容器。
+          // 按目标 index 升序逐个插入，先小后大避免索引漂移
+          const sorted = [...items].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+          for (const { newSchema, parentId, index } of sorted) {
+            if (!newSchema || parentId === undefined) continue;
+            const parent = this.getNodeById(parentId, false) as MContainer | null;
+            if (parent?.items) {
+              if (typeof index === 'number' && index >= 0 && index < parent.items.length) {
+                parent.items.splice(index, 0, cloneDeep(newSchema));
+              } else {
+                parent.items.push(cloneDeep(newSchema));
               }
+              await stage?.add({
+                config: cloneDeep(newSchema),
+                parent: cloneDeep(parent),
+                parentId: parent.id,
+                root: cloneDeep(root),
+              });
             }
           }
         }
         break;
       }
       case 'remove': {
-        const items = step.removedItems ?? [];
+        const items = step.diff ?? [];
         if (reverse) {
           // 撤销 remove：按原 index 升序逐个插回（先小后大避免索引漂移）
-          const sorted = [...items].sort((a, b) => a.index - b.index);
-          for (const { node, parentId, index } of sorted) {
+          const sorted = [...items].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+          for (const { oldSchema, parentId, index } of sorted) {
+            if (!oldSchema || parentId === undefined) continue;
             const parent = this.getNodeById(parentId, false) as MContainer | null;
             if (parent?.items) {
-              parent.items.splice(index, 0, cloneDeep(node));
+              parent.items.splice(index ?? parent.items.length, 0, cloneDeep(oldSchema));
               await stage?.add({
-                config: cloneDeep(node),
+                config: cloneDeep(oldSchema),
                 parent: cloneDeep(parent),
                 parentId,
                 root: cloneDeep(root),
@@ -1444,8 +1752,9 @@ class Editor extends BaseService {
           }
         } else {
           // 重做 remove：再删一次
-          for (const { node } of items) {
-            const existing = this.getNodeById(node.id, false);
+          for (const { oldSchema } of items) {
+            if (!oldSchema) continue;
+            const existing = this.getNodeById(oldSchema.id, false);
             if (existing) {
               await this.remove(existing, commonOpts);
             }
@@ -1454,27 +1763,31 @@ class Editor extends BaseService {
         break;
       }
       case 'update': {
-        const items = step.updatedItems ?? [];
+        const items = step.diff ?? [];
         // 优先按 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 configs = items
+          .filter((item) => item.oldSchema && item.newSchema)
+          .map(({ oldSchema, newSchema, changeRecords }) => {
+            const oldNode = oldSchema!;
+            const newNode = newSchema!;
+            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);
               }
-              const value = cloneDeep(getValueByKeyPath(record.propPath, sourceForValues));
-              setValueByKeyPath(record.propPath, value, patch);
+              return patch;
             }
-            return patch;
-          }
-          return cloneDeep(reverse ? oldNode : newNode);
-        });
+            return cloneDeep(reverse ? oldNode : newNode);
+          });
         if (configs.length) {
           await this.update(configs, { doNotPushHistory: true });
         }