@tmagic/editor 1.8.0-beta.7 → 1.8.0-manmanyu.8

package/src/services/history.ts

@@ -17,31 +17,32 @@
  */
 
 import { reactive } from 'vue';
+import type { Writable } from 'type-fest';
 
-import type { CodeBlockContent, DataSourceSchema, Id, MPage, MPageFragment } from '@tmagic/core';
-import type { ChangeRecord } from '@tmagic/form';
+import type { Id } from '@tmagic/core';
 import { guid } from '@tmagic/utils';
 
 import type {
+  BaseStepValue,
   CodeBlockStepValue,
   DataSourceStepValue,
+  HistoryEvents,
+  HistoryGroup,
   HistoryOpSource,
   HistoryPersistOptions,
   HistoryState,
-  PageHistoryGroup,
-  PageHistoryStepEntry,
+  HistoryStepEntry,
+  HistoryStepType,
   PersistedHistoryState,
-  StackHistoryGroup,
   StepValue,
+  SyncHookPlugin,
 } from '@editor/type';
 import { getEditorConfig } from '@editor/utils/config';
 import {
-  createStackStep,
   deserializeStacks,
   getOrCreateStack,
   markStackSaved,
-  mergePageSteps,
-  mergeStackSteps,
+  mergeSteps,
   serializeStacks,
   undoFloor,
 } from '@editor/utils/history';
@@ -51,86 +52,110 @@ import { UndoRedo } from '@editor/utils/undo-redo';
 import BaseService from './BaseService';
 import editorService from './editor';
 
+const canUsePluginMethods = {
+  sync: ['push', 'undo', 'redo'] as const,
+};
+
+/** 各内置历史类型的默认展示名称（用于历史面板 tab / 分组标题等）。扩展类型可通过 registerStepType / setStepName 登记。 */
+const DEFAULT_STEP_NAMES: Record<string, string> = {
+  page: '页面',
+  codeBlock: '代码块',
+  dataSource: '数据源',
+};
+
+/** 各历史类型对应的分组 `kind`（展示用）：page→page，codeBlock→code-block，dataSource→data-source。扩展类型缺省回退到 stepType 本身。 */
+const STEP_TYPE_KIND: Record<string, string> = {
+  page: 'page',
+  codeBlock: 'code-block',
+  dataSource: 'data-source',
+};
+
+type SyncMethodName = Writable<(typeof canUsePluginMethods)['sync']>;
+
 /** 历史记录持久化快照的默认存储位置与结构版本。 */
 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;
+// 仅把每条 step 的 diff 序列化成字符串，其余字段交给 IndexedDB 结构化克隆原生存储（见 saveToIndexedDB）；
+// 全部历史栈统一收敛到 steps 字段（见 HistorySteps）。
+const PERSIST_VERSION = 3;
 
 class History extends BaseService {
   public state = reactive<HistoryState>({
-    pageSteps: {},
-    pageId: undefined,
-    canRedo: false,
-    canUndo: false,
-    codeBlockState: {},
-    dataSourceState: {},
+    steps: {
+      page: {},
+      codeBlock: {},
+      dataSource: {},
+    },
+    stepNames: { ...DEFAULT_STEP_NAMES },
   });
 
   constructor() {
-    super([]);
-
-    this.on('change', this.setCanUndoRedo);
+    super([...canUsePluginMethods.sync.map((methodName) => ({ name: methodName, isAsync: false }))]);
   }
 
-  public reset() {
-    this.state.pageSteps = {};
-    this.state.codeBlockState = {};
-    this.state.dataSourceState = {};
-    this.resetPage();
+  /**
+   * 注册一个扩展历史类型，使其可与内置 `page` / `codeBlock` / `dataSource` 一样走统一的
+   * {@link push} / {@link undo} / {@link redo}（按 id 分栈、独立 undo/redo）。
+   *
+   * @param stepType 自定义历史类型标识（勿与内置类型重名）
+   * @param options.event push/undo/redo 后派发的事件名，缺省为 `${stepType}-history-change`
+   * @param options.name 历史面板中的展示名称（tab / 分组标题等），缺省回退到 stepType 本身
+   */
+  public registerStepType(stepType: string, options: { event?: string; name?: string } = {}): void {
+    this.getStepBucket(stepType);
+    if (options.name !== undefined) this.state.stepNames[stepType] = options.name;
   }
 
-  public resetPage() {
-    this.state.pageId = undefined;
-    this.state.canRedo = false;
-    this.state.canUndo = false;
+  /**
+   * 读取指定历史类型的展示名称（用于历史面板 tab / 分组标题等）。
+   * 未登记名称时回退到 stepType 本身。
+   */
+  public getStepName(stepType: HistoryStepType): string {
+    return this.state.stepNames[stepType] ?? `${stepType}`;
   }
 
-  public changePage(page: MPage | MPageFragment): void {
-    if (!page) return;
-
-    this.state.pageId = page.id;
-
-    if (!this.state.pageSteps[this.state.pageId]) {
-      this.state.pageSteps[this.state.pageId] = new UndoRedo<StepValue>();
-    }
-
-    this.setCanUndoRedo();
+  /**
+   * 设置指定历史类型的展示名称（用于历史面板 tab / 分组标题等）。
+   * 内置 `page` / `codeBlock` / `dataSource` 也可在此覆盖默认中文名。
+   */
+  public setStepName(stepType: HistoryStepType, name: string): void {
+    this.state.stepNames[stepType] = name;
+  }
 
-    this.emit('page-change', this.state.pageSteps[this.state.pageId]);
+  public reset() {
+    this.clearAllSteps();
   }
 
   public resetState(): void {
-    this.state.pageId = undefined;
-    this.state.pageSteps = {};
-    this.state.canRedo = false;
-    this.state.canUndo = false;
-    this.state.codeBlockState = {};
-    this.state.dataSourceState = {};
+    this.clearAllSteps();
   }
 
   /**
-   * 为指定页面 / 页面片种入一条「初始基线」记录（如加载 DSL 时的「初始 / 加载」基线）。
+   * 为指定历史栈（默认 `page`，也适用于 codeBlock / dataSource / 扩展类型）种入一条「初始基线」记录。
    *
-   * 该记录是一条 `opType: 'initial'` 的 {@link StepValue}，作为页面历史栈 **index 0 的固定底线**：
+   * 该记录是一条 `opType: 'initial'` 的 step，作为对应栈 **index 0 的固定底线**：
    * - 它是一条真实入栈的 step（随栈一起持久化），但被钉为撤销/回滚的下限——cursor 永不低于它，
-   *   因此不会被 undo / goto / revert 触达（详见 {@link undo} / {@link setCanUndoRedo}）；
-   * - 历史面板把它过滤出分组列表（见 {@link getPageHistoryGroups}），改由底部「初始」行展示。
+   *   因此不会被 undo / goto / revert 触达（详见 {@link undo} / {@link undoFloor}）；
+   * - 历史面板把它过滤出分组列表（见 {@link getHistoryGroups}），改由底部「初始」行展示。
+   *
+   * 仅当目标栈为空时种入（保证 initial 一定位于 index 0）；已存在 initial 底线时不重复种入。
    *
-   * 仅当目标页面栈为空时种入（保证 initial 一定位于 index 0）；已存在 initial 底线时默认不重复种入，
-   * 传 `force=true` 且栈为空时按新基线种入。
+   * @param stepType 历史类型
+   * @param id       目标栈 id（page 为 pageId，其余类型为对应资源 id）
+   * @param options  基线展示信息（名称 / 描述 / 来源）
    */
-  public setPageMarker(
-    pageId: Id,
-    options: { name?: string; description?: string; source?: HistoryOpSource } = {},
+  public setMarker(
+    stepType: HistoryStepType,
+    id: Id,
+    options: { name?: string; description?: string; source?: HistoryOpSource; extra?: Record<string, any> } = {},
   ): StepValue | null {
-    if (pageId === undefined || pageId === null || `${pageId}` === '') return null;
+    if (!this.isValidStackId(id)) return null;
 
-    const existing = this.getPageMarker(pageId);
+    const existing = this.getMarker(stepType, id);
     if (existing) return existing;
 
-    const stack = getOrCreateStack(this.state.pageSteps, pageId);
+    const stack = getOrCreateStack(this.getStepBucket(stepType), id);
     // initial 必须是 index 0；栈非空（已有真实记录、却无 initial，如旧数据）时不强行前插，优雅降级为无基线。
     if (stack.getLength() > 0) return null;
 
@@ -138,205 +163,141 @@ class History extends BaseService {
       uuid: guid(),
       opType: 'initial',
       diff: [],
-      data: { name: options.name || '', id: pageId },
-      selectedBefore: [],
-      selectedAfter: [],
-      modifiedNodeIds: new Map(),
+      data: { name: options.name || '', id },
+      extra: {
+        ...(options.extra || {}),
+        ...(stepType === 'page'
+          ? {
+              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);
+    this.emit('marker-change', { id, marker, stepType });
     return marker;
   }
 
   /**
-   * 读取指定页面（缺省当前活动页）的初始基线 step（页面栈 index 0 且 `opType: 'initial'`）；
-   * 不存在时返回 undefined。
+   * 读取指定历史栈的初始基线 step（栈 index 0 且 `opType: 'initial'`）；
+   * 不存在或 id 缺省时返回 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;
+  public getMarker(stepType: HistoryStepType, id?: Id): StepValue | undefined {
+    if (!this.isValidStackId(id)) return undefined;
+    const first = this.state.steps[stepType]?.[id]?.getElementList()[0];
+    return first?.opType === 'initial' ? (first as StepValue) : undefined;
   }
 
   /**
-   * 把一条步骤推入指定页面的栈；不指定 pageId 时落到当前活动页。
+   * 把一条步骤推入指定历史栈。统一入口，所有类型（page / codeBlock / dataSource / 扩展）行为完全一致：
+   * 按 `stepType` 选择目标栈类型，按 `id`（必填）选择具体栈，按需建栈后入栈，并派发对应的历史变更事件
+   * （`page` 为 `change`，其余见 {@link registerStepType}），回调签名统一为 `(id, step)`。
    *
-   * 跨页操作（例如 `moveToContainer` 把节点搬到其它页）必须显式传入 `pageId`，
-   * 否则会把记录错误地落到操作发起页 / 当前激活页，破坏目标页 / 源页的撤销栈语义。
-   */
-  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 状态没影响。
-    if (pageId === undefined || `${pageId}` === `${this.state.pageId}`) {
-      this.emit('change', state);
-    }
-    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 栈。
+   * 跨页 / 跨资源操作（如 `moveToContainer` 把节点搬到其它页）必须显式传入目标 id，
+   * 否则无法落到正确的栈。step 可由 `createStackStep` 等构造后传入。
    *
-   * - 新增：oldContent = null，newContent = 新内容
-   * - 更新：oldContent / newContent 都为对应内容
-   * - 删除：newContent = null，oldContent = 删除前内容
-   * - `changeRecords` 来自 form 端，撤销/重做时若有则按 propPath 局部覆盖；缺省才退化为整内容替换。
-   * - 不直接驱动 codeBlockService，调用方负责实际写回。
+   * @param stepType 历史类型
+   * @param step     已构造好的历史记录（缺省自动补全 uuid / timestamp）
+   * @param id       目标栈 id（page 为 pageId，其余类型为对应资源 id），必填
    */
-  public pushCodeBlock(
-    codeBlockId: Id,
-    payload: {
-      oldContent: CodeBlockContent | null;
-      newContent: CodeBlockContent | null;
-      changeRecords?: ChangeRecord[];
-      /** 可选的人类可读描述（如「修改按钮颜色」），仅用于历史面板展示。 */
-      historyDescription?: string;
-      /** 可选的操作途径（配置面板 / 菜单 / 接口等），仅用于历史面板展示与埋点。 */
-      source?: HistoryOpSource;
-    },
-  ): CodeBlockStepValue | null {
-    const step = createStackStep<CodeBlockContent, CodeBlockStepValue>(codeBlockId, {
-      oldValue: payload.oldContent,
-      newValue: payload.newContent,
-      changeRecords: payload.changeRecords,
-      historyDescription: payload.historyDescription,
-      source: payload.source,
-    });
-    if (!step) return null;
-    getOrCreateStack(this.state.codeBlockState, codeBlockId).pushElement(step);
-    this.emit('code-block-history-change', codeBlockId, step);
+  public push(stepType: 'page', step: StepValue, id: Id): StepValue | null;
+  public push(stepType: 'codeBlock', step: CodeBlockStepValue, id: Id): CodeBlockStepValue | null;
+  public push(stepType: 'dataSource', step: DataSourceStepValue, id: Id): DataSourceStepValue | null;
+  public push<T extends BaseStepValue>(stepType: string, step: T, id: Id): T | null;
+  public push(stepType: HistoryStepType, step: BaseStepValue, id: Id): BaseStepValue | null {
+    if (!this.isValidStackId(id)) return null;
+    this.fillStepMeta(step);
+    getOrCreateStack(this.getStepBucket(stepType), id).pushElement(step);
+    this.emit('change', step, stepType, id);
     return step;
   }
 
   /**
-   * 推入一条数据源变更记录（与页面/节点完全无关），按 `dataSourceId` 维度独立一份 UndoRedo 栈。
-   * 行为同 pushCodeBlock（新增 oldSchema=null；删除 newSchema=null）。
+   * 撤销指定历史栈的最近一次变更。统一入口，所有类型行为一致：
+   * 按 `id`（必填）+ `stepType` 定位栈，不会越过 index 0 的 initial 基线（所有类型同等适用），
+   * 仅在确有可撤销 step 时派发对应的历史变更事件（`page` 为 `change`，回调签名 `(id, step)`）。
+   *
+   * @param stepType 历史类型
+   * @param id       目标栈 id（page 为 pageId，其余类型为对应资源 id），必填
    */
-  public pushDataSource(
-    dataSourceId: Id,
-    payload: {
-      oldSchema: DataSourceSchema | null;
-      newSchema: DataSourceSchema | null;
-      changeRecords?: ChangeRecord[];
-      /** 可选的人类可读描述，仅用于历史面板展示。 */
-      historyDescription?: string;
-      /** 可选的操作途径（配置面板 / 菜单 / 接口等），仅用于历史面板展示与埋点。 */
-      source?: HistoryOpSource;
-    },
-  ): DataSourceStepValue | null {
-    const step = createStackStep<DataSourceSchema, DataSourceStepValue>(dataSourceId, {
-      oldValue: payload.oldSchema,
-      newValue: payload.newSchema,
-      changeRecords: payload.changeRecords,
-      historyDescription: payload.historyDescription,
-      source: payload.source,
-    });
-    if (!step) return null;
-    getOrCreateStack(this.state.dataSourceState, dataSourceId).pushElement(step);
-    this.emit('data-source-history-change', dataSourceId, step);
-    return step;
-  }
-
-  /** 撤销指定代码块的最近一次变更。 */
-  public undoCodeBlock(codeBlockId: Id): CodeBlockStepValue | null {
-    const undoRedo = this.state.codeBlockState[codeBlockId];
+  public undo(stepType: 'page', id: Id): StepValue | null;
+  public undo(stepType: 'codeBlock', id: Id): CodeBlockStepValue | null;
+  public undo(stepType: 'dataSource', id: Id): DataSourceStepValue | null;
+  public undo<T extends BaseStepValue>(stepType: string, id: Id): T | null;
+  public undo(stepType: HistoryStepType, id: Id): BaseStepValue | null {
+    if (!this.isValidStackId(id)) return null;
+    const undoRedo = this.state.steps[stepType]?.[id];
     if (!undoRedo) return null;
+    // 不允许撤销越过初始基线（index 0 的 initial step）；无基线时 floor 为 0。
+    if (undoRedo.getCursor() <= undoFloor(undoRedo)) return null;
     const step = undoRedo.undo();
-    if (step) this.emit('code-block-history-change', codeBlockId, step);
+    if (step) this.emit('change', step, stepType, id);
     return step;
   }
 
-  /** 重做指定代码块的下一次变更。 */
-  public redoCodeBlock(codeBlockId: Id): CodeBlockStepValue | null {
-    const undoRedo = this.state.codeBlockState[codeBlockId];
+  /**
+   * 重做指定历史栈的下一次变更。语义与 {@link undo} 对称，详见其说明。
+   *
+   * @param stepType 历史类型
+   * @param id       目标栈 id（page 为 pageId，其余类型为对应资源 id），必填
+   */
+  public redo(stepType: 'page', id: Id): StepValue | null;
+  public redo(stepType: 'codeBlock', id: Id): CodeBlockStepValue | null;
+  public redo(stepType: 'dataSource', id: Id): DataSourceStepValue | null;
+  public redo<T extends BaseStepValue>(stepType: string, id: Id): T | null;
+  public redo(stepType: HistoryStepType, id: Id): BaseStepValue | null {
+    if (!this.isValidStackId(id)) return null;
+    const undoRedo = this.state.steps[stepType]?.[id];
     if (!undoRedo) return null;
     const step = undoRedo.redo();
-    if (step) this.emit('code-block-history-change', codeBlockId, step);
+    if (step) this.emit('change', step, stepType, id);
     return step;
   }
 
-  /** 是否可对指定代码块撤销。 */
-  public canUndoCodeBlock(codeBlockId: Id): boolean {
-    return this.state.codeBlockState[codeBlockId]?.canUndo() ?? false;
-  }
-
-  /** 是否可对指定代码块重做。 */
-  public canRedoCodeBlock(codeBlockId: Id): boolean {
-    return this.state.codeBlockState[codeBlockId]?.canRedo() ?? false;
-  }
-
-  /** 撤销指定数据源的最近一次变更。 */
-  public undoDataSource(dataSourceId: Id): DataSourceStepValue | null {
-    const undoRedo = this.state.dataSourceState[dataSourceId];
-    if (!undoRedo) return null;
-    const step = undoRedo.undo();
-    if (step) this.emit('data-source-history-change', dataSourceId, step);
-    return step;
+  /**
+   * 是否可对指定历史栈撤销（cursor 高于 initial 基线底线）。
+   * @param stepType 历史类型
+   * @param id       目标栈 id；缺省 / 无效时返回 false
+   */
+  public canUndo(stepType: HistoryStepType, id?: Id): boolean {
+    if (!this.isValidStackId(id)) return false;
+    const undoRedo = this.state.steps[stepType]?.[id];
+    return undoRedo ? undoRedo.getCursor() > undoFloor(undoRedo) : false;
   }
 
-  /** 重做指定数据源的下一次变更。 */
-  public redoDataSource(dataSourceId: Id): DataSourceStepValue | null {
-    const undoRedo = this.state.dataSourceState[dataSourceId];
-    if (!undoRedo) return null;
-    const step = undoRedo.redo();
-    if (step) this.emit('data-source-history-change', dataSourceId, step);
-    return step;
+  /**
+   * 是否可对指定历史栈重做。
+   * @param stepType 历史类型
+   * @param id       目标栈 id；缺省 / 无效时返回 false
+   */
+  public canRedo(stepType: HistoryStepType, id?: Id): boolean {
+    if (!this.isValidStackId(id)) return false;
+    return this.state.steps[stepType]?.[id]?.canRedo() ?? false;
   }
 
-  /** 是否可对指定数据源撤销。 */
-  public canUndoDataSource(dataSourceId: Id): boolean {
-    return this.state.dataSourceState[dataSourceId]?.canUndo() ?? false;
+  /** 读取指定页面历史栈当前游标所在的 step（cursor - 1）；无则返回 null。 */
+  public getCurrentPageStep(pageId: Id): StepValue | null {
+    if (!this.isValidStackId(pageId)) return null;
+    return this.state.steps.page[pageId]?.getCurrentElement() ?? null;
   }
 
-  /** 是否可对指定数据源重做。 */
-  public canRedoDataSource(dataSourceId: Id): boolean {
-    return this.state.dataSourceState[dataSourceId]?.canRedo() ?? false;
-  }
+  /**
+   * 用 `state` 替换指定页面栈当前游标所在的 step（并丢弃其后的重做尾部），游标不变。
+   * 用于「连续 set root 记录合并」等就地替换最新一条的场景；替换成功后派发 `change`。
+   */
+  public replaceCurrentStep(stepType: HistoryStepType, state: StepValue, id: Id): StepValue | null {
+    if (!this.isValidStackId(id)) return null;
+    const undoRedo = getOrCreateStack(this.getStepBucket(stepType), id);
 
-  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;
-  }
+    this.fillStepMeta(state);
 
-  public redo(): StepValue | null {
-    const undoRedo = this.getUndoRedo();
-    if (!undoRedo) return null;
-    const state = undoRedo.redo();
-    this.emit('change', state);
+    if (!undoRedo.replaceCurrentElement(state)) return null;
+    this.emit('change', state, stepType, id);
     return state;
   }
 
@@ -347,91 +308,53 @@ class History extends BaseService {
   }
 
   /**
-   * 清空指定页面（缺省当前活动页）的历史记录栈。
-   * 仅删除撤销/重做记录，不会改动当前 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` 仅清空该数据源，缺省清空全部数据源。
-   * 仅删除撤销/重做记录，不会改动数据源本身。
+   * 清空历史记录栈。统一入口，所有类型（page / codeBlock / dataSource / 扩展）行为一致：
+   * - 传入 `id`：仅清空 `stepType` 下该 id 对应的栈；
+   * - 缺省 `id`：清空 `stepType` 下的全部栈。
+   *
+   * 仅删除撤销/重做记录，不会改动 DSL / 代码块 / 数据源本身。清空时会**保留各栈原有的
+   * initial 基线**（文案 / 来源），无基线时清空成空栈。清空后派发 `clear`（签名 `(id, stepType)`）。
+   *
+   * @param stepType 历史类型
+   * @param id       目标栈 id；缺省表示清空该类型下全部栈
    */
-  public clearDataSource(dataSourceId?: Id): void {
-    if (dataSourceId !== undefined) {
-      delete this.state.dataSourceState[dataSourceId];
+  public clear(stepType: HistoryStepType, id?: Id): void {
+    const bucket = this.state.steps[stepType];
+    if (!bucket) return;
+
+    if (this.isValidStackId(id)) {
+      this.clearStack(stepType, id);
+    } else if (id === undefined) {
+      Object.keys(bucket).forEach((stackId) => this.clearStack(stepType, stackId as Id));
     } else {
-      this.state.dataSourceState = {};
+      return;
     }
+    this.emit('clear', { id: id as Id, stepType });
   }
 
   /**
-   * 清空代码块历史记录栈：传入 `codeBlockId` 仅清空该代码块，缺省清空全部代码块。
-   * 仅删除撤销/重做记录，不会改动代码块本身。
+   * 标记历史记录为「已保存」（把对应栈当前游标所在的记录标为 `saved`）。统一入口：
+   * - 缺省 `id`：标记**全部类型、全部栈**（整份 DSL 落库场景），派发 `mark-saved` 且 `kind: 'all'`；
+   * - 传入 `id`：仅标记 `stepType` 下该 id 对应的栈，派发 `mark-saved` 且 `kind` 为 `stepType`。
+   *
+   * 同一栈内任意时刻最多只有一条记录为 `saved`；从 IndexedDB 恢复时游标会被定位到最近一条已保存记录之后。
+   *
+   * @param stepType 历史类型
+   * @param id       目标栈 id；缺省表示标记全部类型 / 全部栈
    */
-  public clearCodeBlock(codeBlockId?: Id): void {
-    if (codeBlockId !== undefined) {
-      delete this.state.codeBlockState[codeBlockId];
-    } else {
-      this.state.codeBlockState = {};
+  public markSaved(stepType: HistoryStepType, id?: Id): void {
+    if (id === undefined) {
+      Object.values(this.state.steps).forEach((bucket) => Object.values(bucket).forEach(markStackSaved));
+      this.emit('mark-saved', { kind: 'all' });
+      return;
     }
+    if (!this.isValidStackId(id)) return;
+    markStackSaved(this.state.steps[stepType]?.[id]);
+    this.emit('mark-saved', { kind: stepType, id });
   }
 
   /**
-   * 标记「整份 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。
+   * 把当前内存中的全部历史栈（页面 / 代码块 / 数据源 / 扩展类型）序列化后写入本地 IndexedDB。
    *
    * - 每个 UndoRedo 栈连同其游标、容量一并保存，恢复后可继续 undo/redo；
    * - `key` 用于区分不同活动页 / 项目（同一 store 下可保存多份快照），缺省为 `default`；
@@ -443,12 +366,14 @@ class History extends BaseService {
 
     // serializeStacks 会在序列化各栈时只把每条 step 的 diff（可能含函数）序列化成字符串，其余字段原样保留，
     // 因此整份快照可直接按对象写入 IndexedDB（结构化克隆），避免序列化整份快照的开销；读取时再用 parseDSL 还原 diff。
+    const steps: PersistedHistoryState['steps'] = { page: {}, codeBlock: {}, dataSource: {} };
+    Object.entries(this.state.steps).forEach(([stepType, bucket]) => {
+      steps[stepType] = serializeStacks(bucket);
+    });
+
     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),
+      steps,
       savedAt: Date.now(),
     };
 
@@ -461,7 +386,7 @@ class History extends BaseService {
    * 从本地 IndexedDB 读取此前保存的历史快照并重建全部撤销/重做栈。
    *
    * - 读取到的每个栈都会经 {@link UndoRedo.fromSerialized} 还原（含游标），随后可直接 undo/redo；
-   * - 会整体覆盖当前内存中的历史状态，并把活动页恢复为快照中的 pageId；
+   * - 会整体覆盖当前内存中的历史状态（活动页由 editorService 维护，不在此恢复）；
    * - 找不到对应记录时返回 null，且不改动当前状态；
    * - 不支持 IndexedDB 的环境（如 SSR）会 reject。
    */
@@ -473,176 +398,168 @@ class History extends BaseService {
 
     // 各 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();
+    const steps: HistoryState['steps'] = { page: {}, codeBlock: {}, dataSource: {} };
+    Object.entries(snapshot.steps).forEach(([stepType, bucket]) => {
+      steps[stepType] = deserializeStacks(bucket, parseDSL);
+    });
+    this.state.steps = steps;
+    // initial 基线作为各栈 index 0 的 step 随 steps 一并还原，无需单独恢复；活动页由 editorService 维护。
     this.emit('restore-from-indexed-db', snapshot);
     return snapshot;
   }
 
   /**
-   * 取出当前活动页的历史步骤平铺列表（包含已应用 + 已撤销）。
-   * 列表按时间正序，最早一步在最前面。
-   * 通常 UI 应使用 `getPageHistoryGroups` 取已合并分组的版本；本方法仅为兼容/调试保留。
+   * 取出指定历史类型（页面 / 代码块 / 数据源 / 扩展类型）某个栈的平铺步骤列表（含 applied 标记）。
+   * 统一入口，替代旧的 `getPageStepList` / `getCodeBlockStepList` / `getDataSourceStepList`。
+   *
+   * 列表按时间正序，最早一步在最前面；`applied` 表示该步骤处于栈游标之前（已应用）。
+   * 供 revert / goto 等按 index 索引步骤的场景使用。通常 UI 应使用
+   * {@link getHistoryGroups} 取已合并分组的版本；本方法仅为兼容/调试保留。
+   *
+   * @param stepType 历史类型
+   * @param id       目标栈 id（page 为 pageId，其余类型为对应资源 id）；缺省 / 无效时返回空数组
    */
-  public getPageStepList(pageId?: Id): PageHistoryStepEntry[] {
-    const targetPageId = pageId ?? this.state.pageId;
-    if (!targetPageId) return [];
-    const undoRedo = this.state.pageSteps[targetPageId];
+  public getStepList(stepType: 'page', id?: Id): HistoryStepEntry<StepValue>[];
+  public getStepList(stepType: 'codeBlock', id: Id): HistoryStepEntry<CodeBlockStepValue>[];
+  public getStepList(stepType: 'dataSource', id: Id): HistoryStepEntry<DataSourceStepValue>[];
+  public getStepList<T extends BaseStepValue>(stepType: HistoryStepType, id?: Id): HistoryStepEntry<T>[];
+  public getStepList(stepType: HistoryStepType, id?: Id): HistoryStepEntry<any>[] {
+    if (!this.isValidStackId(id)) return [];
+    const undoRedo = this.state.steps[stepType]?.[id];
     if (!undoRedo) return [];
     const list = undoRedo.getElementList();
     const cursor = undoRedo.getCursor();
-    return list.map((step, index) => ({
-      step,
-      index,
-      applied: index < cursor,
-    }));
+    return list.map((step, index) => ({ step, index, applied: index < cursor }));
   }
 
   /**
-   * 取出当前活动页的历史栈，按"目标节点"做相邻合并：
-   * - 连续修改同一节点（单节点 update）的多步合并为一个 group，组内可展开查看每步；
-   * - add / remove / 多节点 update 始终独立成组。
-   * 用于历史面板的"页面"tab 展示。
+   * 取出指定历史类型的历史分组（页面 / 代码块 / 数据源 / 扩展类型统一入口）。
+   *
+   * 把目标栈的步骤列表按"目标"做相邻合并（连续修改同一目标的 update 合并为一组，组内可展开查看每步；
+   * add / remove / 多实体 update 始终独立成组），并过滤掉 index 0 的 initial 基线（底部「初始」行由
+   * {@link getMarker} 驱动）。各类型行为完全一致，仅 `kind` 与 step 快照类型不同。
+   *
+   * 作用域：
+   * - 传入 `id`：仅取该 id 对应的单个栈（页面历史按活动页查看，传入 pageId）；
+   * - 缺省 `id`：遍历该类型下全部栈并汇总（代码块 / 数据源按全部资源分桶展示）。
+   *
+   * @param stepType 历史类型，缺省 `page`
+   * @param id       目标栈 id；缺省表示遍历该类型下全部栈
    */
-  public getPageHistoryGroups(pageId?: Id): PageHistoryGroup[] {
-    const targetPageId = pageId ?? this.state.pageId;
-    if (!targetPageId) return [];
-    const undoRedo = this.state.pageSteps[targetPageId];
-    if (!undoRedo) return [];
-    const list = undoRedo.getElementList();
-    if (!list.length) return [];
-    const cursor = undoRedo.getCursor();
-    // initial 基线（index 0）不作为普通操作组展示，过滤掉；其余真实 step 的 index 保持不变，
-    // 以便面板 goto(index+1) / revert(index) 仍直接对应栈内位置。底部「初始」行由 getPageMarker 驱动。
-    return mergePageSteps(targetPageId, list, cursor).filter((group) => group.opType !== 'initial');
+  public getHistoryGroups(stepType: 'page', id?: Id): HistoryGroup<StepValue>[];
+  public getHistoryGroups(stepType: 'codeBlock', id?: Id): HistoryGroup<CodeBlockStepValue>[];
+  public getHistoryGroups(stepType: 'dataSource', id?: Id): HistoryGroup<DataSourceStepValue>[];
+  public getHistoryGroups<T extends BaseStepValue>(stepType: HistoryStepType, id?: Id): HistoryGroup<T>[];
+  public getHistoryGroups(stepType: HistoryStepType, id?: Id): HistoryGroup[] {
+    const bucket = this.state.steps[stepType];
+    if (!bucket) return [];
+    const kind = STEP_TYPE_KIND[stepType] ?? stepType;
+    const collect = (stackId: Id): HistoryGroup[] => {
+      const undoRedo = bucket[stackId];
+      if (!undoRedo) return [];
+      const list = undoRedo.getElementList();
+      if (!list.length) return [];
+      // initial 基线（index 0）不作为普通操作组展示，过滤掉；其余真实 step 的 index 保持不变，
+      // 以便面板 goto(index+1) / revert(index) 仍直接对应栈内位置。
+      return mergeSteps(kind, stackId, list, undoRedo.getCursor()).filter((group) => group.opType !== 'initial');
+    };
+    if (this.isValidStackId(id)) return collect(id);
+    return Object.keys(bucket).flatMap((stackId) => collect(stackId as Id));
   }
 
   /**
-   * 取出全部代码块的历史栈，按 codeBlockId 分桶展示。
-   * 同一栈内每条操作记录独立成组，不做相邻 update 合并。
+   * 读取指定历史栈的当前游标（已应用步骤数量）。统一入口，替代旧的
+   * `getPageCursor` / `getCodeBlockCursor` / `getDataSourceCursor`。
+   * - `id` 缺省或非法、或对应栈不存在时返回 0；
+   * - `stepType` 支持 `page` / `codeBlock` / `dataSource` / 扩展类型。
    */
-  public getCodeBlockHistoryGroups(): StackHistoryGroup<CodeBlockStepValue, 'code-block'>[] {
-    const groups: StackHistoryGroup<CodeBlockStepValue, 'code-block'>[] = [];
-    Object.entries(this.state.codeBlockState).forEach(([id, undoRedo]) => {
-      if (!undoRedo) return;
-      const list = undoRedo.getElementList();
-      if (!list.length) return;
-      const cursor = undoRedo.getCursor();
-      groups.push(...mergeStackSteps('code-block', id, list, cursor));
-    });
-    return groups;
+  public getCursor(stepType: HistoryStepType, id?: Id): number {
+    if (!this.isValidStackId(id)) return 0;
+    return this.state.steps[stepType]?.[id]?.getCursor() ?? 0;
   }
 
   /**
-   * 读取指定页面历史栈的当前游标（已应用步骤数量）。不传则取当前活动页。
-   * 没有对应栈时返回 0。
+   * 按历史记录 uuid 在指定历史类型的栈中查找其所属 id 与索引，统一入口，替代旧的
+   * `getPageStepIndexByUuid` / `findCodeBlockStepLocationByUuid` / `findDataSourceStepLocationByUuid`。
+   *
+   * - 传入 `id`：仅在该 id 对应的单个栈中查找（如页面历史按活动页查看，传入 pageId）；
+   * - 缺省 `id`：遍历该类型下全部栈查找（代码块 / 数据源等按全部资源分桶的场景）。
+   *
+   * 找不到时返回 null。供「按 uuid 回滚」等需要把 uuid 映射回 (id, index) 的场景使用。
+   *
+   * @param stepType 历史类型
+   * @param uuid     目标历史记录的 uuid
+   * @param id       目标栈 id；缺省表示遍历该类型下全部栈
    */
-  public getPageCursor(pageId?: Id): number {
-    const targetPageId = pageId ?? this.state.pageId;
-    if (!targetPageId) return 0;
-    return this.state.pageSteps[targetPageId]?.getCursor() ?? 0;
-  }
+  public findStepLocationByUuid(stepType: HistoryStepType, uuid: string, id?: Id): { id: Id; index: number } | null {
+    if (!uuid) return null;
+    const bucket = this.state.steps[stepType];
+    if (!bucket) return null;
 
-  /** 读取指定代码块历史栈的当前游标。 */
-  public getCodeBlockCursor(codeBlockId: Id): number {
-    return this.state.codeBlockState[codeBlockId]?.getCursor() ?? 0;
-  }
+    if (this.isValidStackId(id)) {
+      const index = this.getStepList(stepType, id).findIndex((entry) => entry.step.uuid === uuid);
+      return index >= 0 ? { id, index } : null;
+    }
 
-  /** 读取指定数据源历史栈的当前游标。 */
-  public getDataSourceCursor(dataSourceId: Id): number {
-    return this.state.dataSourceState[dataSourceId]?.getCursor() ?? 0;
+    for (const stackId of Object.keys(bucket)) {
+      const index = this.getStepList(stepType, stackId as Id).findIndex((entry) => entry.step.uuid === uuid);
+      if (index >= 0) return { id: stackId as Id, index };
+    }
+    return null;
   }
 
-  /**
-   * 取出指定代码块历史栈的平铺步骤列表（含 applied 标记）。供 revert 等按 index 索引步骤使用。
-   */
-  public getCodeBlockStepList(codeBlockId: Id): { step: CodeBlockStepValue; index: number; applied: boolean }[] {
-    const undoRedo = this.state.codeBlockState[codeBlockId];
-    if (!undoRedo) return [];
-    const list = undoRedo.getElementList();
-    const cursor = undoRedo.getCursor();
-    return list.map((step, index) => ({ step, index, applied: index < cursor }));
+  public usePlugin(options: SyncHookPlugin<SyncMethodName, History>): void {
+    super.usePlugin(options);
   }
 
-  /**
-   * 取出指定数据源历史栈的平铺步骤列表（含 applied 标记）。供 revert 等按 index 索引步骤使用。
-   */
-  public getDataSourceStepList(dataSourceId: Id): { step: DataSourceStepValue; index: number; applied: boolean }[] {
-    const undoRedo = this.state.dataSourceState[dataSourceId];
-    if (!undoRedo) return [];
-    const list = undoRedo.getElementList();
-    const cursor = undoRedo.getCursor();
-    return list.map((step, index) => ({ step, index, applied: index < cursor }));
+  public emit<Name extends keyof HistoryEvents, Param extends HistoryEvents[Name]>(eventName: Name, ...args: Param) {
+    return super.emit(eventName, ...args);
   }
 
   /**
-   * 按历史记录 uuid 在指定页面（默认当前活动页）的栈中查找其索引。
-   * 找不到时返回 -1。供「按 uuid 回滚」等需要把 uuid 映射回 index 的场景使用。
+   * 取出指定历史类型的栈桶（`Record<id, UndoRedo>`）；不存在时按需创建空桶，
+   * 从而支持通过 {@link registerStepType} 或首次 push 动态扩展历史类型。
    */
-  public getPageStepIndexByUuid(uuid: string, pageId?: Id): number {
-    if (!uuid) return -1;
-    return this.getPageStepList(pageId).findIndex((entry) => entry.step.uuid === uuid);
+  private getStepBucket(stepType: string): Record<Id, UndoRedo<any>> {
+    if (!this.state.steps[stepType]) {
+      this.state.steps[stepType] = {};
+    }
+    return this.state.steps[stepType];
   }
 
   /**
-   * 按历史记录 uuid 在全部代码块栈中查找其所属 codeBlockId 与索引。
-   * 找不到时返回 null。
+   * 清空单个历史栈并按需重建其 initial 基线（保留原基线的文案 / 来源）。
    */
-  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 };
+  private clearStack(stepType: HistoryStepType, id: Id): void {
+    // 保留原 initial 基线的文案 / 来源（仅清空其后的真实操作记录），无基线时清空成空栈。
+    const marker = this.getMarker(stepType, id);
+    this.getStepBucket(stepType)[id] = new UndoRedo<any>();
+    if (marker) {
+      this.setMarker(stepType, id, {
+        name: marker.data?.name,
+        description: marker.historyDescription,
+        source: marker.source,
+      });
     }
-    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;
+  /** 入栈前补全 step 的 uuid / timestamp（调用方未指定时）。 */
+  private fillStepMeta(step: BaseStepValue): void {
+    if (step.uuid === undefined) step.uuid = guid();
+    if (step.timestamp === undefined) step.timestamp = Date.now();
   }
 
-  /**
-   * 取出全部数据源的历史栈，按 dataSourceId 分桶展示。同上，每条操作独立成组。
-   */
-  public getDataSourceHistoryGroups(): StackHistoryGroup<DataSourceStepValue, 'data-source'>[] {
-    const groups: StackHistoryGroup<DataSourceStepValue, 'data-source'>[] = [];
-    Object.entries(this.state.dataSourceState).forEach(([id, undoRedo]) => {
-      if (!undoRedo) return;
-      const list = undoRedo.getElementList();
-      if (!list.length) return;
-      const cursor = undoRedo.getCursor();
-      groups.push(...mergeStackSteps('data-source', id, list, cursor));
-    });
-    return groups;
+  /** 校验「按 id 分栈」类型（codeBlock / dataSource / 扩展）的 id 是否有效。 */
+  private isValidStackId(id?: Id): id is Id {
+    return id !== undefined && id !== null && `${id}` !== '';
   }
 
-  /**
-   * 取出指定页面的栈；不传 pageId 时按当前活动页取。
-   *
-   * 跨页 push 时如果目标页的栈尚不存在（用户从未进入过该页），会按需创建一条空栈，
-   * 这样切到目标页时 Ctrl+Z 也能撤回该步骤。
-   */
-  private getUndoRedo(pageId?: Id) {
-    const targetPageId = pageId ?? this.state.pageId;
-    if (!targetPageId) return null;
-    if (!this.state.pageSteps[targetPageId]) {
-      this.state.pageSteps[targetPageId] = new UndoRedo<StepValue>();
-    }
-    return this.state.pageSteps[targetPageId];
+  /** 清空全部历史栈内容（保留已注册的类型键，使扩展类型在 reset 后仍可用）。 */
+  private clearAllSteps(): void {
+    Object.keys(this.state.steps).forEach((stepType) => {
+      this.state.steps[stepType] = {};
+    });
   }
 
   /**
@@ -654,13 +571,6 @@ class History extends BaseService {
     const resolvedAppId = appId ?? editorService.get('root')?.id;
     return resolvedAppId ? `${dbName}-${resolvedAppId}` : dbName;
   }
-
-  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;
-  }
 }
 
 export type HistoryService = History;