@tmagic/editor 1.8.0-beta.4 → 1.8.0-beta.6

package/src/services/history.ts

@@ -17,10 +17,10 @@
  */
 
 import { reactive } from 'vue';
-import { cloneDeep } from 'lodash-es';
 
 import type { CodeBlockContent, DataSourceSchema, Id, MPage, MPageFragment } from '@tmagic/core';
 import type { ChangeRecord } from '@tmagic/form';
+import { guid } from '@tmagic/utils';
 
 import type {
   CodeBlockHistoryGroup,
@@ -28,173 +28,38 @@ import type {
   DataSourceHistoryGroup,
   DataSourceStepValue,
   HistoryOpSource,
+  HistoryPersistOptions,
   HistoryState,
   PageHistoryGroup,
   PageHistoryStepEntry,
+  PersistedHistoryState,
   StepValue,
 } from '@editor/type';
+import { getEditorConfig } from '@editor/utils/config';
+import {
+  createStackStep,
+  deserializeStacks,
+  getOrCreateStack,
+  markStackSaved,
+  mergePageSteps,
+  mergeStackSteps,
+  serializeStacks,
+  undoFloor,
+} from '@editor/utils/history';
+import { idbGet, idbSet } from '@editor/utils/indexed-db';
 import { UndoRedo } from '@editor/utils/undo-redo';
 
 import BaseService from './BaseService';
+import editorService from './editor';
 
-class History extends BaseService {
-  /**
-   * 把单个代码块栈拆成若干 group：
-   * - 把"新增/删除"独立成组（语义上属于一次性事件，不应与 update 合并）；
-   * - 连续 'update' 合并到同一组，组内 steps 顺序就是发生顺序。
-   */
-  private static mergeCodeBlockSteps(
-    codeBlockId: Id,
-    list: CodeBlockStepValue[],
-    cursor: number,
-  ): CodeBlockHistoryGroup[] {
-    const groups: CodeBlockHistoryGroup[] = [];
-    let current: CodeBlockHistoryGroup | null = null;
-    const currentIndex = cursor - 1;
-    list.forEach((step, index) => {
-      const opType = History.detectOpType(step.oldContent, step.newContent);
-      const applied = index < cursor;
-      const isCurrent = index === currentIndex;
-      if (opType === 'update' && current?.opType === 'update') {
-        current.steps.push({ step, index, applied, isCurrent });
-        current.applied = applied;
-        if (isCurrent) current.isCurrent = true;
-      } else {
-        current = {
-          kind: 'code-block',
-          id: codeBlockId,
-          opType,
-          steps: [{ step, index, applied, isCurrent }],
-          applied,
-          isCurrent,
-        };
-        groups.push(current);
-      }
-    });
-    return groups;
-  }
-
-  private static mergeDataSourceSteps(
-    dataSourceId: Id,
-    list: DataSourceStepValue[],
-    cursor: number,
-  ): DataSourceHistoryGroup[] {
-    const groups: DataSourceHistoryGroup[] = [];
-    let current: DataSourceHistoryGroup | null = null;
-    const currentIndex = cursor - 1;
-    list.forEach((step, index) => {
-      const opType = History.detectOpType(step.oldSchema, step.newSchema);
-      const applied = index < cursor;
-      const isCurrent = index === currentIndex;
-      if (opType === 'update' && current?.opType === 'update') {
-        current.steps.push({ step, index, applied, isCurrent });
-        current.applied = applied;
-        if (isCurrent) current.isCurrent = true;
-      } else {
-        current = {
-          kind: 'data-source',
-          id: dataSourceId,
-          opType,
-          steps: [{ step, index, applied, isCurrent }],
-          applied,
-          isCurrent,
-        };
-        groups.push(current);
-      }
-    });
-    return groups;
-  }
-
-  /**
-   * 根据 old/new 是否为 null 推断 opType（与 push 时的约定一致）。
-   */
-  private static detectOpType(oldVal: unknown, newVal: unknown): 'add' | 'remove' | 'update' {
-    if (oldVal === null && newVal !== null) return 'add';
-    if (oldVal !== null && newVal === null) return 'remove';
-    return 'update';
-  }
-
-  /**
-   * 把页面栈拆成若干 group：
-   * - 单节点的 'update' 按 targetId 与相邻同 targetId 的 update 合并到一个 group；
-   * - 'add' / 'remove' 始终独立成组（语义上是结构变更，不应被收纳进单节点修改组）；
-   * - 多节点 'update'（如批量改属性）也独立成组（无明确单一目标，避免误合并）。
-   */
-  private static mergePageSteps(pageId: Id, list: StepValue[], cursor: number): PageHistoryGroup[] {
-    const groups: PageHistoryGroup[] = [];
-    let current: PageHistoryGroup | null = null;
-    const currentIndex = cursor - 1;
-    list.forEach((step, index) => {
-      const applied = index < cursor;
-      const isCurrent = index === currentIndex;
-      const targetId = History.detectPageTargetId(step);
-      const targetName = History.detectPageTargetName(step);
-      const entry: PageHistoryStepEntry = { step, index, applied, isCurrent };
-
-      // 仅"单节点 update"参与合并；其它情形（add/remove/多节点 update）始终独立成组。
-      const mergeable = step.opType === 'update' && targetId !== undefined;
-      if (mergeable && current?.opType === 'update' && current.targetId === targetId) {
-        current.steps.push(entry);
-        current.applied = applied;
-        if (isCurrent) current.isCurrent = true;
-        // 保持目标名为最近一次的（节点重命名时也能反映）
-        if (targetName) current.targetName = targetName;
-      } else {
-        current = {
-          kind: 'page',
-          pageId,
-          opType: step.opType,
-          targetId: mergeable ? targetId : undefined,
-          targetName,
-          steps: [entry],
-          applied,
-          isCurrent,
-        };
-        groups.push(current);
-      }
-    });
-    return groups;
-  }
-
-  /**
-   * 解析 StepValue 中的"目标节点 id"用于合并：
-   * - 单节点 update：取唯一一项 updatedItems 的节点 id；
-   * - 其它情形（多节点 update / add / remove）：返回 undefined，表示不参与合并。
-   */
-  private static detectPageTargetId(step: StepValue): Id | undefined {
-    if (step.opType !== 'update') return undefined;
-    const items = step.updatedItems;
-    if (items?.length !== 1) return undefined;
-    return items[0].newNode?.id ?? items[0].oldNode?.id;
-  }
-
-  /** 解析 StepValue 中的目标节点可读名（用于 UI 展示）。 */
-  private static detectPageTargetName(step: StepValue): string | undefined {
-    if (step.opType === 'update') {
-      const items = step.updatedItems;
-      if (items?.length === 1) {
-        const node = items[0].newNode || items[0].oldNode;
-        return (node?.name as string) || (node?.type as string) || (node?.id !== undefined ? `${node.id}` : undefined);
-      }
-      return items?.length ? `${items.length} 个节点` : undefined;
-    }
-    if (step.opType === 'add') {
-      if (step.nodes?.length === 1) {
-        const n = step.nodes[0];
-        return (n.name as string) || (n.type as string) || `${n.id}`;
-      }
-      return step.nodes?.length ? `${step.nodes.length} 个节点` : undefined;
-    }
-    if (step.opType === 'remove') {
-      if (step.removedItems?.length === 1) {
-        const n = step.removedItems[0].node;
-        return (n.name as string) || (n.type as string) || `${n.id}`;
-      }
-      return step.removedItems?.length ? `${step.removedItems.length} 个节点` : undefined;
-    }
-    return undefined;
-  }
+/** 历史记录持久化快照的默认存储位置与结构版本。 */
+const DEFAULT_DB_NAME = 'tmagic-editor';
+const DEFAULT_STORE_NAME = 'history';
+const DEFAULT_KEY: IDBValidKey = 'default';
+// v2：仅把每条 step 的 diff 序列化成字符串，其余字段交给 IndexedDB 结构化克隆原生存储（见 saveToIndexedDB）。
+const PERSIST_VERSION = 2;
 
+class History extends BaseService {
   public state = reactive<HistoryState>({
     pageSteps: {},
     pageId: undefined,
@@ -246,6 +111,59 @@ class History extends BaseService {
     this.state.dataSourceState = {};
   }
 
+  /**
+   * 为指定页面 / 页面片种入一条「初始基线」记录（如加载 DSL 时的「初始 / 加载」基线）。
+   *
+   * 该记录是一条 `opType: 'initial'` 的 {@link StepValue}，作为页面历史栈 **index 0 的固定底线**：
+   * - 它是一条真实入栈的 step（随栈一起持久化），但被钉为撤销/回滚的下限——cursor 永不低于它，
+   *   因此不会被 undo / goto / revert 触达（详见 {@link undo} / {@link setCanUndoRedo}）；
+   * - 历史面板把它过滤出分组列表（见 {@link getPageHistoryGroups}），改由底部「初始」行展示。
+   *
+   * 仅当目标页面栈为空时种入（保证 initial 一定位于 index 0）；已存在 initial 底线时默认不重复种入，
+   * 传 `force=true` 且栈为空时按新基线种入。
+   */
+  public setPageMarker(
+    pageId: Id,
+    options: { name?: string; description?: string; source?: HistoryOpSource } = {},
+  ): StepValue | null {
+    if (pageId === undefined || pageId === null || `${pageId}` === '') return null;
+
+    const existing = this.getPageMarker(pageId);
+    if (existing) return existing;
+
+    const stack = getOrCreateStack(this.state.pageSteps, pageId);
+    // initial 必须是 index 0；栈非空（已有真实记录、却无 initial，如旧数据）时不强行前插，优雅降级为无基线。
+    if (stack.getLength() > 0) return null;
+
+    const marker: StepValue = {
+      uuid: guid(),
+      opType: 'initial',
+      diff: [],
+      data: { name: options.name || '', id: pageId },
+      selectedBefore: [],
+      selectedAfter: [],
+      modifiedNodeIds: new Map(),
+      historyDescription: options.description || '未修改的初始状态',
+      timestamp: Date.now(),
+      ...(options.source ? { source: options.source } : {}),
+    };
+    stack.pushElement(marker);
+    if (`${pageId}` === `${this.state.pageId}`) this.setCanUndoRedo();
+    this.emit('page-marker-change', marker);
+    return marker;
+  }
+
+  /**
+   * 读取指定页面（缺省当前活动页）的初始基线 step（页面栈 index 0 且 `opType: 'initial'`）；
+   * 不存在时返回 undefined。
+   */
+  public getPageMarker(pageId?: Id): StepValue | undefined {
+    const targetPageId = pageId ?? this.state.pageId;
+    if (!targetPageId) return undefined;
+    const first = this.state.pageSteps[targetPageId]?.getElementList()[0];
+    return first?.opType === 'initial' ? first : undefined;
+  }
+
   /**
    * 把一条步骤推入指定页面的栈；不指定 pageId 时落到当前活动页。
    *
@@ -255,6 +173,7 @@ class History extends BaseService {
   public push(state: StepValue, pageId?: Id): StepValue | null {
     const undoRedo = this.getUndoRedo(pageId);
     if (!undoRedo) return null;
+    if (state.uuid === undefined) state.uuid = guid();
     if (state.timestamp === undefined) state.timestamp = Date.now();
     undoRedo.pushElement(state);
     // 仅当推入的是当前活动页时才需要刷新 canUndo/canRedo —— 其它页栈对当前 UI 状态没影响。
@@ -264,6 +183,27 @@ class History extends BaseService {
     return state;
   }
 
+  /** 读取指定页面（缺省当前活动页）历史栈当前游标所在的 step（cursor - 1）；无则返回 null。 */
+  public getCurrentPageStep(pageId?: Id): StepValue | null {
+    const targetPageId = pageId ?? this.state.pageId;
+    if (!targetPageId) return null;
+    return this.state.pageSteps[targetPageId]?.getCurrentElement() ?? null;
+  }
+
+  /**
+   * 用 `state` 替换指定页面栈当前游标所在的 step（并丢弃其后的重做尾部），游标不变。
+   * 用于「连续 set root 记录合并」等就地替换最新一条的场景；替换成功后按需刷新 / 通知。
+   */
+  public replaceCurrentPageStep(state: StepValue, pageId?: Id): StepValue | null {
+    const undoRedo = this.getUndoRedo(pageId);
+    if (!undoRedo) return null;
+    if (state.uuid === undefined) state.uuid = guid();
+    if (state.timestamp === undefined) state.timestamp = Date.now();
+    if (!undoRedo.replaceCurrentElement(state)) return null;
+    this.emit('change', state);
+    return state;
+  }
+
   /**
    * 推入一条代码块变更记录（与页面/节点完全无关），按 `codeBlockId` 维度独立一份 UndoRedo 栈。
    *
@@ -285,19 +225,15 @@ class History extends BaseService {
       source?: HistoryOpSource;
     },
   ): CodeBlockStepValue | null {
-    if (!codeBlockId) return null;
-
-    const step: CodeBlockStepValue = {
-      id: codeBlockId,
-      oldContent: payload.oldContent ? cloneDeep(payload.oldContent) : null,
-      newContent: payload.newContent ? cloneDeep(payload.newContent) : null,
-      changeRecords: payload.changeRecords?.length ? cloneDeep(payload.changeRecords) : undefined,
+    const step = createStackStep<CodeBlockContent, CodeBlockStepValue>(codeBlockId, {
+      oldValue: payload.oldContent,
+      newValue: payload.newContent,
+      changeRecords: payload.changeRecords,
       historyDescription: payload.historyDescription,
       source: payload.source,
-      timestamp: Date.now(),
-    };
-
-    this.getCodeBlockUndoRedo(codeBlockId).pushElement(step);
+    });
+    if (!step) return null;
+    getOrCreateStack(this.state.codeBlockState, codeBlockId).pushElement(step);
     this.emit('code-block-history-change', codeBlockId, step);
     return step;
   }
@@ -318,19 +254,15 @@ class History extends BaseService {
       source?: HistoryOpSource;
     },
   ): DataSourceStepValue | null {
-    if (!dataSourceId) return null;
-
-    const step: DataSourceStepValue = {
-      id: dataSourceId,
-      oldSchema: payload.oldSchema ? cloneDeep(payload.oldSchema) : null,
-      newSchema: payload.newSchema ? cloneDeep(payload.newSchema) : null,
-      changeRecords: payload.changeRecords?.length ? cloneDeep(payload.changeRecords) : undefined,
+    const step = createStackStep<DataSourceSchema, DataSourceStepValue>(dataSourceId, {
+      oldValue: payload.oldSchema,
+      newValue: payload.newSchema,
+      changeRecords: payload.changeRecords,
       historyDescription: payload.historyDescription,
       source: payload.source,
-      timestamp: Date.now(),
-    };
-
-    this.getDataSourceUndoRedo(dataSourceId).pushElement(step);
+    });
+    if (!step) return null;
+    getOrCreateStack(this.state.dataSourceState, dataSourceId).pushElement(step);
     this.emit('data-source-history-change', dataSourceId, step);
     return step;
   }
@@ -394,6 +326,8 @@ class History extends BaseService {
   public undo(): StepValue | null {
     const undoRedo = this.getUndoRedo();
     if (!undoRedo) return null;
+    // 不允许撤销越过初始基线（index 0 的 initial step）。
+    if (undoRedo.getCursor() <= undoFloor(undoRedo)) return null;
     const state = undoRedo.undo();
     this.emit('change', state);
     return state;
@@ -413,6 +347,144 @@ class History extends BaseService {
     this.removeAllPlugins();
   }
 
+  /**
+   * 清空指定页面（缺省当前活动页）的历史记录栈。
+   * 仅删除撤销/重做记录，不会改动当前 DSL；清空后该页将无法再撤销/重做之前的操作。
+   */
+  public clearPage(pageId?: Id): void {
+    const targetPageId = pageId ?? this.state.pageId;
+    if (!targetPageId) return;
+    // 保留该页原 initial 基线的文案 / 来源（仅清空其后的真实操作记录），无基线时清空成空栈。
+    const marker = this.getPageMarker(targetPageId);
+    this.state.pageSteps[targetPageId] = new UndoRedo<StepValue>();
+    if (marker) {
+      this.setPageMarker(targetPageId, {
+        name: marker.data?.name,
+        description: marker.historyDescription,
+        source: marker.source,
+      });
+    }
+    if (`${targetPageId}` === `${this.state.pageId}`) {
+      this.setCanUndoRedo();
+      this.emit('clear-page', null);
+    }
+  }
+
+  /**
+   * 清空数据源历史记录栈：传入 `dataSourceId` 仅清空该数据源，缺省清空全部数据源。
+   * 仅删除撤销/重做记录，不会改动数据源本身。
+   */
+  public clearDataSource(dataSourceId?: Id): void {
+    if (dataSourceId !== undefined) {
+      delete this.state.dataSourceState[dataSourceId];
+    } else {
+      this.state.dataSourceState = {};
+    }
+  }
+
+  /**
+   * 清空代码块历史记录栈：传入 `codeBlockId` 仅清空该代码块，缺省清空全部代码块。
+   * 仅删除撤销/重做记录，不会改动代码块本身。
+   */
+  public clearCodeBlock(codeBlockId?: Id): void {
+    if (codeBlockId !== undefined) {
+      delete this.state.codeBlockState[codeBlockId];
+    } else {
+      this.state.codeBlockState = {};
+    }
+  }
+
+  /**
+   * 标记「整份 DSL 已保存」：把页面 / 代码块 / 数据源所有栈当前游标所在的记录都标为 `saved`。
+   * 适用于「整体落库」场景；若只保存了其中一类，请改用更细粒度的
+   * {@link markPageSaved} / {@link markCodeBlockSaved} / {@link markDataSourceSaved}。
+   */
+  public markSaved(): void {
+    Object.values(this.state.pageSteps).forEach(markStackSaved);
+    Object.values(this.state.codeBlockState).forEach(markStackSaved);
+    Object.values(this.state.dataSourceState).forEach(markStackSaved);
+    this.emit('mark-saved', { kind: 'all' });
+  }
+
+  /**
+   * 标记指定页面（缺省为当前活动页）的历史栈当前记录为已保存。
+   * 仅影响该页面自己的栈，不波及代码块 / 数据源 / 其它页面。
+   */
+  public markPageSaved(pageId?: Id): void {
+    const targetPageId = pageId ?? this.state.pageId;
+    if (!targetPageId) return;
+    markStackSaved(this.state.pageSteps[targetPageId]);
+    this.emit('mark-saved', { kind: 'page', id: targetPageId });
+  }
+
+  /** 标记指定代码块的历史栈当前记录为已保存，仅影响该代码块自己的栈。 */
+  public markCodeBlockSaved(codeBlockId: Id): void {
+    if (!codeBlockId) return;
+    markStackSaved(this.state.codeBlockState[codeBlockId]);
+    this.emit('mark-saved', { kind: 'code-block', id: codeBlockId });
+  }
+
+  /** 标记指定数据源的历史栈当前记录为已保存，仅影响该数据源自己的栈。 */
+  public markDataSourceSaved(dataSourceId: Id): void {
+    if (!dataSourceId) return;
+    markStackSaved(this.state.dataSourceState[dataSourceId]);
+    this.emit('mark-saved', { kind: 'data-source', id: dataSourceId });
+  }
+
+  /**
+   * 把当前内存中的全部历史栈（页面 / 代码块 / 数据源）序列化后写入本地 IndexedDB。
+   *
+   * - 每个 UndoRedo 栈连同其游标、容量一并保存，恢复后可继续 undo/redo；
+   * - `key` 用于区分不同活动页 / 项目（同一 store 下可保存多份快照），缺省为 `default`；
+   * - 返回写入成功的快照对象，便于调用方记录 savedAt 等信息；
+   * - 不支持 IndexedDB 的环境（如 SSR）会 reject。
+   */
+  public async saveToIndexedDB(options: HistoryPersistOptions = {}): Promise<PersistedHistoryState> {
+    const { dbName = DEFAULT_DB_NAME, storeName = DEFAULT_STORE_NAME, key = DEFAULT_KEY, appId } = options;
+
+    // serializeStacks 会在序列化各栈时只把每条 step 的 diff（可能含函数）序列化成字符串，其余字段原样保留，
+    // 因此整份快照可直接按对象写入 IndexedDB（结构化克隆），避免序列化整份快照的开销；读取时再用 parseDSL 还原 diff。
+    const snapshot: PersistedHistoryState = {
+      version: PERSIST_VERSION,
+      pageId: this.state.pageId,
+      pageSteps: serializeStacks(this.state.pageSteps),
+      codeBlockState: serializeStacks(this.state.codeBlockState),
+      dataSourceState: serializeStacks(this.state.dataSourceState),
+      savedAt: Date.now(),
+    };
+
+    await idbSet(this.resolveDbName(dbName, appId), storeName, key, snapshot);
+    this.emit('save-to-indexed-db', snapshot);
+    return snapshot;
+  }
+
+  /**
+   * 从本地 IndexedDB 读取此前保存的历史快照并重建全部撤销/重做栈。
+   *
+   * - 读取到的每个栈都会经 {@link UndoRedo.fromSerialized} 还原（含游标），随后可直接 undo/redo；
+   * - 会整体覆盖当前内存中的历史状态，并把活动页恢复为快照中的 pageId；
+   * - 找不到对应记录时返回 null，且不改动当前状态；
+   * - 不支持 IndexedDB 的环境（如 SSR）会 reject。
+   */
+  public async restoreFromIndexedDB(options: HistoryPersistOptions = {}): Promise<PersistedHistoryState | null> {
+    const { dbName = DEFAULT_DB_NAME, storeName = DEFAULT_STORE_NAME, key = DEFAULT_KEY, appId } = options;
+
+    const snapshot = await idbGet<PersistedHistoryState>(this.resolveDbName(dbName, appId), storeName, key);
+    if (!snapshot) return null;
+
+    // 各 step 的 diff 以序列化字符串存储（含函数），由 deserializeStacks 逐条用 parseDSL 还原。
+    const parseDSL = getEditorConfig('parseDSL');
+    this.state.pageSteps = deserializeStacks(snapshot.pageSteps, parseDSL);
+    this.state.codeBlockState = deserializeStacks(snapshot.codeBlockState, parseDSL);
+    this.state.dataSourceState = deserializeStacks(snapshot.dataSourceState, parseDSL);
+    // initial 基线作为页面栈 index 0 的 step 随 pageSteps 一并还原，无需单独恢复。
+    this.state.pageId = snapshot.pageId;
+
+    this.setCanUndoRedo();
+    this.emit('restore-from-indexed-db', snapshot);
+    return snapshot;
+  }
+
   /**
    * 取出当前活动页的历史步骤平铺列表（包含已应用 + 已撤销）。
    * 列表按时间正序，最早一步在最前面。
@@ -446,15 +518,14 @@ class History extends BaseService {
     const list = undoRedo.getElementList();
     if (!list.length) return [];
     const cursor = undoRedo.getCursor();
-    return History.mergePageSteps(targetPageId, list, cursor);
+    // initial 基线（index 0）不作为普通操作组展示，过滤掉；其余真实 step 的 index 保持不变，
+    // 以便面板 goto(index+1) / revert(index) 仍直接对应栈内位置。底部「初始」行由 getPageMarker 驱动。
+    return mergePageSteps(targetPageId, list, cursor).filter((group) => group.opType !== 'initial');
   }
 
   /**
-   * 取出全部代码块的历史栈，按 codeBlockId 分组。
-   * 同一栈内相邻、同 opType 且作用于同一 id 的多步会被合并为一个 group：
-   * - 这正是"代码块/数据源各自按 id 分栈"的天然表现，再叠加"连续修改同目标的相邻步骤合并展示"。
-   * - 合并后 group 暴露子步骤数组，UI 可展开查看每一步的 changeRecords。
-   * - applied 字段：组内最后一步是否处于已应用段。
+   * 取出全部代码块的历史栈，按 codeBlockId 分桶展示。
+   * 同一栈内每条操作记录独立成组，不做相邻 update 合并。
    */
   public getCodeBlockHistoryGroups(): CodeBlockHistoryGroup[] {
     const groups: CodeBlockHistoryGroup[] = [];
@@ -463,7 +534,7 @@ class History extends BaseService {
       const list = undoRedo.getElementList();
       if (!list.length) return;
       const cursor = undoRedo.getCursor();
-      groups.push(...History.mergeCodeBlockSteps(id, list, cursor));
+      groups.push(...mergeStackSteps('code-block', id, list, cursor));
     });
     return groups;
   }
@@ -511,7 +582,42 @@ class History extends BaseService {
   }
 
   /**
-   * 取出全部数据源的历史栈，按 dataSourceId 分组。同上。
+   * 按历史记录 uuid 在指定页面（默认当前活动页）的栈中查找其索引。
+   * 找不到时返回 -1。供「按 uuid 回滚」等需要把 uuid 映射回 index 的场景使用。
+   */
+  public getPageStepIndexByUuid(uuid: string, pageId?: Id): number {
+    if (!uuid) return -1;
+    return this.getPageStepList(pageId).findIndex((entry) => entry.step.uuid === uuid);
+  }
+
+  /**
+   * 按历史记录 uuid 在全部代码块栈中查找其所属 codeBlockId 与索引。
+   * 找不到时返回 null。
+   */
+  public findCodeBlockStepLocationByUuid(uuid: string): { id: Id; index: number } | null {
+    if (!uuid) return null;
+    for (const id of Object.keys(this.state.codeBlockState)) {
+      const index = this.getCodeBlockStepList(id).findIndex((entry) => entry.step.uuid === uuid);
+      if (index >= 0) return { id, index };
+    }
+    return null;
+  }
+
+  /**
+   * 按历史记录 uuid 在全部数据源栈中查找其所属 dataSourceId 与索引。
+   * 找不到时返回 null。
+   */
+  public findDataSourceStepLocationByUuid(uuid: string): { id: Id; index: number } | null {
+    if (!uuid) return null;
+    for (const id of Object.keys(this.state.dataSourceState)) {
+      const index = this.getDataSourceStepList(id).findIndex((entry) => entry.step.uuid === uuid);
+      if (index >= 0) return { id, index };
+    }
+    return null;
+  }
+
+  /**
+   * 取出全部数据源的历史栈，按 dataSourceId 分桶展示。同上，每条操作独立成组。
    */
   public getDataSourceHistoryGroups(): DataSourceHistoryGroup[] {
     const groups: DataSourceHistoryGroup[] = [];
@@ -520,7 +626,7 @@ class History extends BaseService {
       const list = undoRedo.getElementList();
       if (!list.length) return;
       const cursor = undoRedo.getCursor();
-      groups.push(...History.mergeDataSourceSteps(id, list, cursor));
+      groups.push(...mergeStackSteps('data-source', id, list, cursor));
     });
     return groups;
   }
@@ -540,30 +646,21 @@ class History extends BaseService {
     return this.state.pageSteps[targetPageId];
   }
 
-  private setCanUndoRedo(): void {
-    const undoRedo = this.getUndoRedo();
-    this.state.canRedo = undoRedo?.canRedo() || false;
-    this.state.canUndo = undoRedo?.canUndo() || false;
-  }
-
   /**
-   * 按 id 获取（或创建）指定代码块的 UndoRedo 栈。
+   * 把基础 dbName 与当前 DSL（root app）的 id 拼成最终库名，实现不同应用历史隔离。
+   * 取不到 app id（如尚未加载 DSL）时退回基础 dbName。
    */
-  private getCodeBlockUndoRedo(codeBlockId: Id): UndoRedo<CodeBlockStepValue> {
-    if (!this.state.codeBlockState[codeBlockId]) {
-      this.state.codeBlockState[codeBlockId] = new UndoRedo<CodeBlockStepValue>();
-    }
-    return this.state.codeBlockState[codeBlockId];
+  private resolveDbName(dbName: string, appId?: Id): string {
+    // 优先用显式传入的 appId（「先恢复再 set root」时 root 尚未就绪）；否则回退到当前 root.id。
+    const resolvedAppId = appId ?? editorService.get('root')?.id;
+    return resolvedAppId ? `${dbName}-${resolvedAppId}` : dbName;
   }
 
-  /**
-   * 按 id 获取（或创建）指定数据源的 UndoRedo 栈。
-   */
-  private getDataSourceUndoRedo(dataSourceId: Id): UndoRedo<DataSourceStepValue> {
-    if (!this.state.dataSourceState[dataSourceId]) {
-      this.state.dataSourceState[dataSourceId] = new UndoRedo<DataSourceStepValue>();
-    }
-    return this.state.dataSourceState[dataSourceId];
+  private setCanUndoRedo(): void {
+    const undoRedo = this.getUndoRedo();
+    this.state.canRedo = undoRedo?.canRedo() || false;
+    // 初始基线之上才可撤销：cursor 必须高于底线（有 initial 时为 1）。
+    this.state.canUndo = undoRedo ? undoRedo.getCursor() > undoFloor(undoRedo) : false;
   }
 }
 

package/src/services/ui.ts

@@ -62,6 +62,7 @@ const state = shallowReactive<UiState>({
   showPageListButton: true,
   hideSlideBar: false,
   sideBarItems: [],
+  sideBarActiveTabName: '',
   navMenuRect: {
     left: 0,
     top: 0,
@@ -104,7 +105,13 @@ class Ui extends BaseService {
       mask?.showRule(value as unknown as boolean);
     }
 
+    const preValue = state[name];
+
     state[name] = value;
+
+    if (preValue !== value) {
+      this.emit('state-change', name, value, preValue);
+    }
   }
 
   public get<K extends keyof UiState>(name: K) {