@tmagic/editor 1.8.0-beta.1 → 1.8.0-beta.11

package/src/type.ts

@@ -16,14 +16,24 @@
  * limitations under the License.
  */
 
-import type { Component } from 'vue';
+import type { AppContext, Component } from 'vue';
 import type EventEmitter from 'events';
 import type * as Monaco from 'monaco-editor';
 import type { default as Sortable, Options, SortableEvent } from 'sortablejs';
 import type { PascalCasedProperties, Writable } from 'type-fest';
 
-import type { CodeBlockContent, CodeBlockDSL, Id, MApp, MContainer, MNode, MPage, MPageFragment } from '@tmagic/core';
-import type { ChangeRecord, FormConfig, TableColumnConfig, TypeFunction } from '@tmagic/form';
+import type {
+  CodeBlockContent,
+  CodeBlockDSL,
+  DataSourceSchema,
+  Id,
+  MApp,
+  MContainer,
+  MNode,
+  MPage,
+  MPageFragment,
+} from '@tmagic/core';
+import type { ChangeRecord, FormConfig, FormState, TableColumnConfig, TypeFunction } from '@tmagic/form';
 import type StageCore from '@tmagic/stage';
 import type {
   CanDropIn,
@@ -46,7 +56,7 @@ import type { PropsService } from './services/props';
 import type { StageOverlayService } from './services/stageOverlay';
 import type { StorageService } from './services/storage';
 import type { UiService } from './services/ui';
-import type { UndoRedo } from './utils/undo-redo';
+import type { SerializedUndoRedo, UndoRedo } from './utils/undo-redo';
 
 export type EditorSlots = FrameworkSlots &
   WorkspaceSlots &
@@ -138,7 +148,7 @@ export interface EditorInstallOptions {
   customCreateMonacoDiffEditor: (
     monaco: typeof import('monaco-editor'),
     codeEditorEl: HTMLElement,
-    options: Monaco.editor.IStandaloneEditorConstructionOptions & { editorCustomType?: string },
+    options: Monaco.editor.IStandaloneDiffEditorConstructionOptions & { editorCustomType?: string },
   ) => Promise<Monaco.editor.IStandaloneDiffEditor> | Monaco.editor.IStandaloneDiffEditor;
   [key: string]: any;
 }
@@ -189,6 +199,11 @@ export interface StageOptions {
    */
   alwaysMultiSelect?: boolean;
   disabledRule?: boolean;
+  /**
+   * 禁用「非点击画布选中组件时（如从图层树、面包屑等外部选中），对选中区域做高亮闪烁提示」，
+   * 默认 false（即默认开启闪烁）
+   */
+  disabledFlashTip?: boolean;
   zoom?: number;
   /** 画布双击前的钩子函数，返回 false 则阻止默认的双击行为 */
   beforeDblclick?: (event: MouseEvent) => Promise<boolean | void> | boolean | void;
@@ -297,6 +312,8 @@ export interface UiState {
   hideSlideBar: boolean;
   /** 侧边栏面板配置 */
   sideBarItems: SideComponent[];
+  /** 当前激活的侧边栏面板 */
+  sideBarActiveTabName: string;
 
   // navMenu 的宽高
   navMenuRect: {
@@ -318,6 +335,7 @@ export interface EditorNodeInfo {
   node: MNode | null;
   parent: MContainer | null;
   page: MPage | MPageFragment | null;
+  path: MNode[];
 }
 // #endregion EditorNodeInfo
 
@@ -375,6 +393,9 @@ export interface MenuButton {
   items?: MenuButton[];
   /** 唯一标识，用于高亮 */
   id?: string | number;
+  buttonProps?: {
+    type?: string;
+  };
 }
 // #endregion MenuButton
 
@@ -407,6 +428,7 @@ export interface MenuComponent {
  * 'rule': 显示隐藏标尺
  * 'scale-to-original': 缩放到实际大小
  * 'scale-to-fit': 缩放以适应
+ * 'history-list': 历史记录面板（按 页面 / 数据源 / 代码块 三个 tab 展示，相邻同目标修改自动合并）
  */
 // #region MenuItem
 export type MenuItem =
@@ -421,6 +443,7 @@ export type MenuItem =
   | 'rule'
   | 'scale-to-original'
   | 'scale-to-fit'
+  | 'history-list'
   | MenuButton
   | MenuComponent
   | string;
@@ -463,6 +486,63 @@ export interface SideComponent extends MenuComponent {
 }
 // #endregion SideComponent
 
+// #region HistoryListExtraTab
+/**
+ * 历史记录面板（HistoryListPanel）的自定义扩展 tab。
+ *
+ * 业务方可通过 Editor 的 `historyListExtraTabs` 注入额外的历史记录 tab，
+ * 例如某个自定义模块维护自己的操作历史时，可以在历史记录面板中增加一个
+ * 独立的 tab 来展示与回滚。内置的「页面 / 数据源 / 代码块」三个 tab 之后
+ * 会依次追加这些扩展 tab。
+ */
+export interface HistoryListExtraTab {
+  /** tab 唯一标识，作为 TMagicTabs 的 name */
+  name: string;
+  /** tab 显示文案，支持传入函数以展示动态内容（如记录数量） */
+  label: string | (() => string);
+  /** tab 内容区渲染的组件（Vue 组件或字符串标签） */
+  component: any;
+  /** 传入内容组件的 props */
+  props?: Record<string, any>;
+  /** 内容组件的事件监听 */
+  listeners?: Record<string, (..._args: any[]) => any>;
+}
+// #endregion HistoryListExtraTab
+
+// #region CompareForm
+/**
+ * 对比表单（CompareForm）的对比类型：
+ * - node: 节点组件，按 `type` 从 propsService 获取属性表单配置
+ * - data-source: 数据源，按 `type`(base/http/...) 从 dataSourceService 获取数据源表单配置
+ * - code-block: 数据源代码块，使用内置的代码块表单配置
+ */
+export type CompareCategory = 'node' | 'data-source' | 'code-block' | string;
+
+/**
+ * 自定义 `loadConfig` 时回传的上下文，聚合了组件当前的对比入参，
+ * 方便调用方在外部按需拼装 FormConfig。
+ */
+export interface CompareFormLoadConfigContext {
+  /** 对比类型，见 CompareCategory */
+  category: string;
+  /** 节点 / 数据源类型 */
+  type?: string;
+  /** 数据源代码块场景下的数据源类型 */
+  dataSourceType?: string;
+  /**
+   * 内置的默认 FormConfig 加载逻辑（按 `category` 从 propsService / dataSourceService /
+   * 代码块工具取配置）。自定义 `loadConfig` 可调用它复用默认结果，再做二次加工。
+   */
+  defaultLoadConfig: () => Promise<FormConfig>;
+}
+
+/**
+ * 自定义 FormConfig 加载逻辑。传入后将接管内置的按 `category` 取配置逻辑，
+ * 可通过 `ctx.defaultLoadConfig()` 复用默认结果再做二次加工。
+ */
+export type CompareFormLoadConfig = (ctx: CompareFormLoadConfigContext) => FormConfig | Promise<FormConfig>;
+// #endregion CompareForm
+
 // #region SideItemKey
 export enum SideItemKey {
   COMPONENT_LIST = 'component-list',
@@ -606,38 +686,328 @@ export interface CodeParamStatement {
 }
 
 // #region HistoryOpType
-export type HistoryOpType = 'add' | 'remove' | 'update';
+/**
+ * 历史记录操作类型：
+ * - `add` / `remove` / `update`：普通可撤销/重做的节点变更；
+ * - `initial`：页面「未修改的初始状态」基线（设置 root 时生成），作为页面栈 index 0 的固定底线 step。
+ *   该 step 不可被撤销/回滚（cursor 不会低于它），仅用于历史面板底部的初始行展示。
+ */
+export type HistoryOpType = 'add' | 'remove' | 'update' | 'initial';
 // #endregion HistoryOpType
 
-// #region StepValue
-export interface StepValue {
-  /** 页面信息 */
+// #region HistoryOpSource
+/**
+ * 历史记录的「操作途径」——标记本次变更由哪条交互入口触发，仅用于历史面板展示 / 业务埋点，
+ * 不影响 undo/redo 行为。缺省（未传）时 UI 视为「未知」。
+ *
+ * - `stage`：画布（拖拽 / 缩放 / 排序等舞台直接操作）
+ * - `tree`：树形面板（图层 / 数据源 / 代码块等树形结构里的拖拽 / 菜单操作）
+ * - `component-panel`：组件面板（左侧组件列表点击 / 拖拽新增组件）
+ * - `props`：配置面板表单（属性表单字段编辑）
+ * - `code`：源码编辑器（配置面板「源码」面板里直接编辑 JSON/代码后保存）
+ * - `stage-contextmenu`：画布右键菜单（舞台上节点的右键上下文菜单）
+ * - `tree-contextmenu`：树面板右键菜单（图层 / 数据源 / 代码块等树形列表上的右键上下文菜单）
+ * - `toolbar`：工具栏菜单（顶部导航工具栏按钮）
+ * - `shortcut`：键盘快捷键
+ * - `rollback`：历史回滚（历史面板里对某条历史「回滚」，反向应用为一条新记录，类 git revert）
+ * - `api`：代码 / 接口调用（程序化触发）
+ * - `ai`：AI 生成 / 智能助手触发的变更
+ * - `unknown`：未知来源
+ *
+ * 通过 `(string & {})` 允许业务侧扩展自定义途径字符串，同时保留内置值的自动补全。
+ */
+export type HistoryOpSource =
+  | 'initial'
+  | 'stage'
+  | 'tree'
+  | 'component-panel'
+  | 'props'
+  | 'code'
+  | 'root-code'
+  | 'stage-contextmenu'
+  | 'tree-contextmenu'
+  | 'toolbar'
+  | 'shortcut'
+  | 'rollback'
+  | 'api'
+  | 'ai'
+  // 同步
+  | 'sync'
+  | 'unknown'
+  | (string & {});
+// #endregion HistoryOpSource
+
+// #region DslOpWithHistoryIdsResult
+/** *AndGetHistoryId 系列方法返回值：原操作结果 + 本次写入历史记录的 uuid 列表（未入栈时为 `[]`）。 */
+export type DslOpWithHistoryIdsResult<T> = {
+  result: T;
+  historyIds: string[];
+};
+// #endregion DslOpWithHistoryIdsResult
+
+// #region StepDiffItem
+/**
+ * 单条变更的 diff 描述，统一表达「页面节点 / 代码块 / 数据源」的变化内容，
+ * 被 {@link StepValue} / {@link CodeBlockStepValue} / {@link DataSourceStepValue} 的 `diff` 复用。
+ *
+ * 按 `opType` 区分携带的字段：
+ * - `add`：仅 `newSchema`（页面节点还带 `parentId` / `index`）；
+ * - `remove`：仅 `oldSchema`（页面节点还带 `parentId` / `index`）；
+ * - `update`：`oldSchema` + `newSchema`，并可带 `changeRecords` 做局部更新。
+ *
+ * 泛型 `T` 为变化内容的快照类型：页面节点为 `MNode`，代码块为 `CodeBlockContent`，数据源为 `DataSourceSchema`。
+ */
+export interface StepDiffItem<T = unknown> {
+  /** 变更后的内容快照。`opType` 为 `add` / `update` 时有，`remove` 时无。 */
+  newSchema?: T;
+  /** 变更前的内容快照。`opType` 为 `remove` / `update` 时有，`add` 时无。 */
+  oldSchema?: T;
+  /** 父节点 id。仅页面节点有（数据源 / 代码块没有父节点）。 */
+  parentId?: Id;
+  /** 在父节点 items 数组中的索引。仅页面节点有（数据源 / 代码块无需排序）。 */
+  index?: number;
+  /**
+   * form 端 propPath/value 变更列表，仅 `opType` 为 `update` 时有；
+   * 撤销/重做时若有则按 propPath 局部更新，缺省才退化为整内容替换。
+   */
+  changeRecords?: ChangeRecord[];
+}
+// #endregion StepDiffItem
+
+// #region BaseStepValue
+/**
+ * 历史记录条目公共字段，被 {@link StepValue} / {@link CodeBlockStepValue} / {@link DataSourceStepValue} 复用。
+ *
+ * 泛型 `T` 为 `diff` 中变化内容的快照类型（页面节点 `MNode` / 代码块 `CodeBlockContent` / 数据源 `DataSourceSchema`）。
+ */
+export interface BaseStepValue<T = unknown, U extends Record<string, any> = {}> {
+  /**
+   * 历史记录唯一标识（uuid）。入栈时自动写入（若调用方未指定），
+   * 用于精确定位 / 引用某一条历史记录（如 revert、埋点、跨端同步等）。
+   * 注意与 `data.id`（关联的页面 / 代码块 / 数据源 id）区分。
+   */
+  uuid: string;
+  /**
+   * 关联目标信息：`id` 为关联的页面 / 代码块 / 数据源等资源 id（也是历史栈的分组 key），
+   * `name` 为展示名。所有历史类型统一携带。
+   */
   data: { name: string; id: Id };
+  /** 操作类型：新增 / 删除 / 更新（三类历史记录统一携带）。 */
   opType: HistoryOpType;
-  /** 操作前选中的节点 ID，用于撤销后恢复选择状态 */
-  selectedBefore: Id[];
-  /** 操作后选中的节点 ID，用于重做后恢复选择状态 */
-  selectedAfter: Id[];
-  modifiedNodeIds: Map<Id, Id>;
-  /** opType 'add': 新增的节点 */
-  nodes?: MNode[];
-  /** opType 'add': 父节点 ID */
-  parentId?: Id;
-  /** opType 'add': 每个新增节点在父节点 items 中的索引 */
-  indexMap?: Record<string, number>;
-  /** opType 'remove': 被删除的节点及其位置信息 */
-  removedItems?: { node: MNode; parentId: Id; index: number }[];
-  /** opType 'update': 变更前后的节点快照 */
-  updatedItems?: { oldNode: MNode; newNode: MNode }[];
+  /**
+   * 本次变更的内容（统一 diff 表达），每项见 {@link StepDiffItem}。
+   * 页面节点（add/remove 多节点、update 多节点）会有多项，代码块 / 数据源通常只有一项。
+   */
+  diff: StepDiffItem<T>[];
+  /**
+   * 调用方可选传入的人类可读描述（如「调整按钮颜色」），用于历史面板展示。
+   * 不影响 undo/redo 行为；缺省时面板会根据节点 / propPath 自动生成描述。
+   */
+  historyDescription?: string;
+  /**
+   * 操作途径：标记本次变更由哪条交互入口触发，取值见 {@link HistoryOpSource}
+   * （画布 / 树面板 / 组件面板 / 配置面板 / 源码编辑器 / 右键菜单 / 工具栏 / 快捷键 / 回滚 / 接口 等）。
+   * 仅用于历史面板展示与业务埋点，不影响 undo/redo 行为；缺省时面板视为「未知」。
+   */
+  source?: HistoryOpSource;
+  /**
+   * 入栈时间戳（毫秒）。入栈时自动写入（若调用方未指定），仅用于历史面板展示。
+   */
+  timestamp?: number;
+  /**
+   * 是否为「已保存」记录：DSL 落库（如保存到后端 / 本地）时由 historyService.markSaved 标记。
+   * 同一栈内任意时刻最多只有一条记录为 true；从 IndexedDB 恢复时游标会被定位到最近一条已保存记录之后。
+   */
+  saved?: boolean;
+  /**
+   * 是否为「整体设置 root」（set root）产生的记录（由 {@link Editor.pushRootDiffHistory} 写入）。
+   * 用于「连续 set root 合并」：当某页栈最新一条已是 root 记录时，下一条 set root 会替换它而非新增，
+   * 避免源码反复保存 / 外部重设 DSL 时堆积多条 root 记录。
+   */
+  rootStep?: boolean;
+  /** 操作人 */
+  operator?: string;
+  /** 扩展信息 */
+  extra?: U;
+}
+// #endregion BaseStepValue
+
+// #region StepExtra
+/**
+ * 历史记录的扩展上下文（{@link BaseStepValue.extra}）。
+ * 内置字段供 `page` 类型在撤销 / 重做时恢复选区与受影响节点；扩展类型可自由附加其它键。
+ */
+export interface StepExtra {
+  /** 操作前选中的节点 ID，用于撤销后恢复选择状态（page 类型） */
+  selectedBefore?: Id[];
+  /** 操作后选中的节点 ID，用于重做后恢复选择状态（page 类型） */
+  selectedAfter?: Id[];
+  /** 本次操作涉及的节点 id 集合（page 类型） */
+  modifiedNodeIds?: Map<Id, Id>;
+  [key: string]: any;
 }
+// #endregion StepExtra
+
+// #region StepValue
+/**
+ * 页面节点历史记录条目（`diff` 内容为 {@link MNode}）。结构已与代码块 / 数据源统一收敛到
+ * {@link BaseStepValue}：关联 id 见 `data.id`，选区等上下文见 `extra`。
+ */
+export type StepValue = BaseStepValue<MNode, StepExtra>;
 // #endregion StepValue
 
+// #region CodeBlockStepValue
+/**
+ * 代码块历史记录条目（`diff` 内容为 {@link CodeBlockContent}），按 `data.id`（codeBlock.id）
+ * 分组保存到 historyState.steps.codeBlock。结构与 {@link StepValue} / {@link DataSourceStepValue}
+ * 一致，仅 `diff` 快照类型不同。
+ */
+export type CodeBlockStepValue = BaseStepValue<CodeBlockContent>;
+// #endregion CodeBlockStepValue
+
+// #region DataSourceStepValue
+/**
+ * 数据源历史记录条目（`diff` 内容为 {@link DataSourceSchema}），按 `data.id`（dataSource.id）
+ * 分组保存到 historyState.steps.dataSource。结构与 {@link StepValue} / {@link CodeBlockStepValue}
+ * 一致，仅 `diff` 快照类型不同。
+ */
+export type DataSourceStepValue = BaseStepValue<DataSourceSchema>;
+// #endregion DataSourceStepValue
+
+// #region HistorySteps
+/**
+ * 历史记录类型标识：内置 `page` / `codeBlock` / `dataSource`，并允许业务扩展自定义类型。
+ * `(string & {})` 保留对内置字面量的智能提示，同时不限制扩展取值。
+ */
+export type HistoryStepType = 'page' | 'codeBlock' | 'dataSource' | (string & {});
+
+/**
+ * 全部历史栈的统一容器，按「类型 -> id -> UndoRedo 栈」两级分组。
+ *
+ * - `page`：页面历史栈，按 page.id 分组（每页一份 UndoRedo）；
+ * - `codeBlock`：代码块历史栈，按 codeBlock.id 分组；
+ * - `dataSource`：数据源历史栈，按 dataSource.id 分组；
+ * - 其余键：业务通过 {@link HistoryService.registerStepType} 注册的自定义历史类型。
+ *
+ * 所有类型（含扩展类型）一视同仁：均按 id 独立分栈、独立 undo/redo，且都可通过
+ * {@link HistoryService.setMarker} 在 index 0 种入 `initial` 基线（撤销 / 回滚不会越过该基线）。
+ */
+export interface HistorySteps {
+  page: Record<Id, UndoRedo<StepValue>>;
+  codeBlock: Record<Id, UndoRedo<CodeBlockStepValue>>;
+  dataSource: Record<Id, UndoRedo<DataSourceStepValue>>;
+  /** 扩展历史类型：按 id 分组的 UndoRedo 栈。 */
+  [stepType: string]: Record<Id, UndoRedo<any>>;
+}
+// #endregion HistorySteps
+
 export interface HistoryState {
-  pageId?: Id;
-  pageSteps: Record<Id, UndoRedo<StepValue>>;
-  canRedo: boolean;
-  canUndo: boolean;
+  /**
+   * 全部历史栈的统一容器（页面 / 代码块 / 数据源 / 扩展类型），见 {@link HistorySteps}。
+   * 各类型互不影响，支持按 id 独立 undo/redo；是否可撤销 / 重做改用 {@link HistoryService.canUndo} /
+   * {@link HistoryService.canRedo}（按 stepType + id 查询）替代旧的全局 canUndo / canRedo 字段。
+   */
+  steps: HistorySteps;
+  /**
+   * 各历史类型的展示名称，用于历史面板（{@link HistorySteps} 的 tab / 分组标题等）。
+   * 内置 `page` / `codeBlock` / `dataSource` 有默认中文名（页面 / 代码块 / 数据源），
+   * 扩展类型可通过 {@link HistoryService.registerStepType} 的 `name` 选项或
+   * {@link HistoryService.setStepName} 登记；读取请用 {@link HistoryService.getStepName}。
+   */
+  stepNames: Record<string, string>;
+}
+
+// #region PersistedHistoryState
+/**
+ * 历史记录的可持久化快照。由 historyService.saveToIndexedDB 写入 IndexedDB，
+ * 再由 historyService.restoreFromIndexedDB 读出并重建各 UndoRedo 栈。
+ */
+export interface PersistedHistoryState {
+  /** 快照结构版本号，便于后续兼容升级。 */
+  version: number;
+  /**
+   * 全部历史栈的序列化快照，按「类型 -> id」两级分组，与 {@link HistorySteps} 对应。
+   * 内置 `page` / `codeBlock` / `dataSource`，并包含业务注册的扩展类型。
+   */
+  steps: {
+    page: Record<Id, SerializedUndoRedo<StepValue>>;
+    codeBlock: Record<Id, SerializedUndoRedo<CodeBlockStepValue>>;
+    dataSource: Record<Id, SerializedUndoRedo<DataSourceStepValue>>;
+    [stepType: string]: Record<Id, SerializedUndoRedo<any>>;
+  };
+  /** 保存时间戳（毫秒）。 */
+  savedAt: number;
+}
+// #endregion PersistedHistoryState
+
+// #region HistoryPersistOptions
+/** historyService 持久化相关 API 的可选配置。 */
+export interface HistoryPersistOptions {
+  /** IndexedDB 数据库名，默认 `tmagic-editor`（最终库名会拼上当前 DSL app id）。 */
+  dbName?: string;
+  /** objectStore 名，默认 `history`。 */
+  storeName?: string;
+  /** 记录 key，用于区分不同活动页 / 项目，默认 `default`。 */
+  key?: IDBValidKey;
+  /**
+   * 显式指定用于库名隔离的 DSL app id。
+   * 缺省时回退到当前 editorService 的 `root.id`；在「先恢复历史再 set root」场景下 root 尚未设置，
+   * 需由调用方（如从待加载 DSL 取 id）显式传入，否则会读 / 写到未按 app 隔离的默认库。
+   */
+  appId?: Id;
+}
+// #endregion HistoryPersistOptions
+
+// #region HistoryListEntry
+/**
+ * 历史面板用：当前页面的一条历史步骤（包含位置和是否已应用）。
+ */
+export interface HistoryStepEntry<T> {
+  /** 步骤内容 */
+  step: T;
+  /** 在所属栈中的索引（0 为最早） */
+  index: number;
+  /** 是否处于"已应用"段（即位于栈游标之前）。撤销后变为 false。 */
+  applied: boolean;
+  /** 是否为当前所在的步骤（栈中最近一次已应用的那一步，即 index === cursor - 1）。 */
+  isCurrent?: boolean;
+}
+
+/**
+ * 历史面板分组（页面 / 数据源 / 代码块 / 扩展类型统一结构）。
+ *
+ * 把指定历史栈的步骤列表按"目标"做相邻合并：
+ * - 连续修改同一目标（单实体 update，targetId 一致）的多步合并成一组，组内可展开查看每步；
+ * - add / remove / 多实体 update 始终独立成组（无法明确归属单一目标）；
+ * - targetId 为 undefined 表示"无明确目标"，不参与合并。
+ *
+ * 各类型仅 `kind` 与 step 快照类型不同，统一由泛型描述：
+ * - 页面：`HistoryGroup<StepValue>`，`kind: 'page'`，`id` 为 pageId，`targetId` 为被改节点 id；
+ * - 数据源：`HistoryGroup<DataSourceStepValue>`，`kind: 'data-source'`，`id` 为 dataSource.id；
+ * - 代码块：`HistoryGroup<CodeBlockStepValue>`，`kind: 'code-block'`，`id` 为 codeBlock.id。
+ */
+export interface HistoryGroup<T extends BaseStepValue = BaseStepValue> {
+  /** 历史类型标识：page / code-block / data-source（扩展类型同理）。 */
+  kind: string;
+  /** 所属栈 id（page 为 pageId，代码块 / 数据源为对应资源 id）。 */
+  id: Id;
+  /** 该分组的操作类型。 */
+  opType: HistoryOpType;
+  /**
+   * 合并的目标 id：仅"单实体 update"有值，并按此与相邻同 id 的 update 合并。
+   * undefined 表示该分组不可被合并（add / remove / 多实体 update）。
+   */
+  targetId?: Id;
+  /** 目标可读名（取最后一步快照的 name/type/id）。 */
+  targetName?: string;
+  /** 组内所有步骤，按时间正序。 */
+  steps: { step: T; index: number; applied: boolean; isCurrent?: boolean }[];
+  /** 组内最后一步是否已应用。 */
+  applied: boolean;
+  /** 是否为当前所在的分组（包含栈中最近一次已应用步骤的那一组）。 */
+  isCurrent?: boolean;
 }
+// #endregion HistoryListEntry
 
 export enum KeyBindingCommand {
   /** 复制 */
@@ -801,6 +1171,8 @@ export type SyncHookPlugin<
 
 export interface EventBusEvent {
   'edit-data-source': [id: string];
+  'edit-data-source-method': [id: string, methodName: string];
+  'edit-data-source-field': [id: string, fieldPath: string[]];
   'remove-data-source': [id: string];
   'edit-code': [id: string];
 }
@@ -834,7 +1206,11 @@ export type CustomContentMenuFunction = (
 ) => (MenuButton | MenuComponent)[];
 
 export interface EditorEvents {
-  'root-change': [value: StoreState['root'], preValue?: StoreState['root']];
+  'root-change': [
+    value: StoreState['root'],
+    preValue?: StoreState['root'],
+    options?: { historySource?: HistoryOpSource },
+  ];
   select: [node: MNode | null];
   add: [nodes: MNode[]];
   remove: [nodes: MNode[]];
@@ -842,6 +1218,54 @@ export interface EditorEvents {
   'move-layer': [offset: number | LayerOffset];
   'drag-to': [data: { targetIndex: number; configs: MNode | MNode[]; targetParent: MContainer }];
   'history-change': [data: MPage | MPageFragment];
+  /**
+   * DSL 发生变更后统一触发，免去分别监听 add / remove / update / move-layer / drag-to。
+   * 回调参数为 {@link EditorChangeEvent}，按 `type` 区分操作类型并携带各自的操作内容（payload）
+   * 以及变更所在的当前 page（可能为 null）。撤销 / 重做内部同样会经由
+   * add / remove / update 触发本事件；如需区分「用户操作」与「撤销重做」请配合 `history-change`。
+   */
+  change: [event: EditorChangeEvent];
+}
+
+// #region EditorChangeEvent
+/** `change` 事件中单个变更项：变更的 node 及其所属的 page（可能为 null）。 */
+export interface EditorChangeItem {
+  node: MNode;
+  page: StoreState['page'];
+}
+
+/** `update` 类型变更项：node 为前后快照及 form 端变更记录，page 为其所属页面。 */
+export interface EditorUpdateChangeItem {
+  node: { newNode: MNode; oldNode: MNode; changeRecords?: ChangeRecord[] };
+  page: StoreState['page'];
+}
+
+/**
+ * {@link EditorEvents.change} 的回调参数：以 `type` 区分操作类型，并携带对应的操作内容。
+ * `data` 为本次变更的节点列表，每项包含 node 及其所属的 page（可能为 null）；
+ * `move-layer` 额外带层级偏移 `offset`，`drag-to` 额外带目标位置 `targetIndex` / `targetParent`。
+ */
+export type EditorChangeEvent =
+  | { type: 'add'; data: EditorChangeItem[] }
+  | { type: 'remove'; data: EditorChangeItem[] }
+  | { type: 'update'; data: EditorUpdateChangeItem[] }
+  | { type: 'move-layer'; data: EditorChangeItem[]; offset: number | LayerOffset }
+  | { type: 'drag-to'; data: EditorChangeItem[]; targetIndex: number; targetParent: MContainer };
+// #endregion EditorChangeEvent
+
+export interface HistoryEvents {
+  change: [
+    state: BaseStepValue | StepValue | CodeBlockStepValue | DataSourceStepValue,
+    stepType: HistoryStepType,
+    id: Id,
+  ];
+  'code-block-history-change': [id: Id, state: CodeBlockStepValue];
+  'data-source-history-change': [id: Id, state: DataSourceStepValue];
+  'restore-from-indexed-db': [snapshot: PersistedHistoryState | null];
+  'save-to-indexed-db': [snapshot: PersistedHistoryState];
+  'mark-saved': [{ kind: HistoryStepType; id?: Id }];
+  clear: [{ id: Id; stepType: HistoryStepType }];
+  'marker-change': [{ id: Id; marker: StepValue; stepType: HistoryStepType }];
 }
 
 export const canUsePluginMethods = {
@@ -874,12 +1298,170 @@ export const canUsePluginMethods = {
 
 export type AsyncMethodName = Writable<(typeof canUsePluginMethods)['async']>;
 
+// #region HistoryOpOptions
+/**
+ * 历史记录写入相关的通用配置（codeBlock / dataSource / editor 共用）
+ * - doNotPushHistory: 操作完成后是否不要将本次操作压入历史栈（撤销/重做记录），默认 false
+ * - historyDescription: 入栈时附带的人类可读描述，用于历史面板展示；不影响 undo/redo 行为，缺省时面板会自动生成描述
+ * - historySource: 操作途径，取值见 {@link HistoryOpSource}（画布 / 树面板 / 组件面板 / 配置面板 / 源码编辑器 / 右键菜单 / 工具栏 / 快捷键 / 回滚 / 接口 等），用于历史面板展示与埋点；不影响 undo/redo 行为
+ */
+export interface HistoryOpOptions {
+  doNotPushHistory?: boolean;
+  historyDescription?: string;
+  historySource?: HistoryOpSource;
+}
+// #endregion HistoryOpOptions
+
+// #region HistoryOpOptionsWithChangeRecords
+/**
+ * 在 HistoryOpOptions 基础上携带 form 端 propPath/value 变更记录，
+ * 用于历史记录的精细化撤销/重做（按 propPath 局部 patch）。
+ */
+export interface HistoryOpOptionsWithChangeRecords extends HistoryOpOptions {
+  changeRecords?: ChangeRecord[];
+}
+// #endregion HistoryOpOptionsWithChangeRecords
+
+// #region DslOpOptions
 /**
  * DSL 修改类操作的通用配置
  * - doNotSelect: 操作后是否不要自动触发选中（不调用 this.select / this.multiSelect / stage.select / stage.multiSelect）
  * - doNotSwitchPage: 操作若会引发当前页面切换（如新增 / 删除 / 跨页移动），是否跳过这次切换
  */
-export type DslOpOptions = {
+export interface DslOpOptions extends HistoryOpOptions {
   doNotSelect?: boolean;
   doNotSwitchPage?: boolean;
-};
+}
+// #endregion DslOpOptions
+
+/** 差异对话框的入参 */
+export interface DiffDialogPayload {
+  /** 表单类别 */
+  category?: CompareCategory;
+  /** 节点类型 / 数据源类型 */
+  type?: string;
+  /** 代码块场景下的数据源类型 */
+  dataSourceType?: string;
+  /** 该 step 修改前的值（oldNode / oldSchema / oldContent） */
+  lastValue: Record<string, any>;
+  /** 该 step 修改后的值（newNode / newSchema / newContent） */
+  value: Record<string, any>;
+  /** 当前编辑器中实际的最新值；不传或为 null 时禁用「与当前对比」 */
+  currentValue?: Record<string, any> | null;
+  /** 用于标题展示的目标名称 */
+  targetLabel?: string;
+  /** 用于标题展示的目标 id */
+  id?: string | number;
+  /**
+   * 指定打开时的初始对比模式：
+   * - before：该步骤修改前 vs 修改后
+   * - current：该步骤修改后 vs 当前最新值
+   * 不传时按是否存在「修改后的值」/「当前值」自动推断。
+   * 若指定的模式当前不可用（对应数据缺失），将回退到自动推断结果。
+   */
+  mode?: 'before' | 'current';
+}
+
+/**
+ * 一组「描述 + 可操作性」的判定函数集合。页面 / 数据源 / 代码块及业务自定义历史
+ * 各自实现一份，作为整体注入，避免把 describe* / isStep* 拆成多个独立 props 反复透传。
+ */
+export interface HistoryRowDescriptor<T extends BaseStepValue = BaseStepValue> {
+  /**
+   * 组级描述文案生成器，接收一个 group，返回展示文本。
+   * 不传时回退到对组内最后一步调用 {@link describeStep}（适用于不做相邻合并、每组恒为单步的历史，如数据源/代码块）。
+   */
+  describeGroup?: (_group: any) => string;
+  /** 单步描述文案生成器，接收一个 step，返回展示文本（合并组展开后的子步列表用）。 */
+  describeStep: (_step: T) => string;
+  /** 判断某个 step 是否可查看差异（前后值都存在）。不传则一律不展示差异入口。 */
+  isStepDiffable?: (_step: T) => boolean;
+  /** 判断某个 step 是否支持回滚（如更新需带 changeRecords）。不传则已应用即可回滚。 */
+  isStepRevertable?: (_step: T) => boolean;
+}
+
+/**
+ * 通用 bucket（数据源 / 代码块 / 业务自定义历史）的整体渲染配置。
+ * 把原先散落在 Bucket / BucketTab 上的 title / prefix / describe* / isStep* / showInitial / gotoEnabled
+ * 收敛成一个对象作为单一 prop 传递，调用方一次配齐、组件内部按需读取。
+ */
+export interface HistoryBucketConfig<T extends BaseStepValue = BaseStepValue> extends HistoryRowDescriptor<T> {
+  /** bucket 头部标题，例如 "数据源" / "代码块"。 */
+  title: string;
+  /** 子项 key 的命名空间前缀（`ds` 数据源 / `cb` 代码块 / 业务自定义如 `mod`）。 */
+  prefix: string;
+  /** 是否展示底部「回到初始状态」入口，默认 true。无 undo cursor 语义的自定义历史可传 false。 */
+  showInitial?: boolean;
+  /** 是否支持「跳转到该记录」(goto)，默认 true。 */
+  gotoEnabled?: boolean;
+  /** 是否展示顶部「清空」按钮，默认 true。无需提供清空能力的自定义历史可传 false。 */
+  showClear?: boolean;
+}
+
+export interface UseHistoryRevertOptions {
+  /**
+   * 父级应用上下文，用于让动态挂载的「差异确认弹窗」继承全局组件 / 指令 / provide / 插件
+   * （Element Plus、@tmagic/form 字段组件等）。未显式传入时，会自动取调用方所在组件的 appContext
+   * （`getCurrentInstance()?.appContext`）。业务方若在组件 setup 之外调用，需手动传入（如 `editorApp._context`）。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 透传给差异确认弹窗的 `extendState`（即 Editor 的 `extendFormState`），
+   * 使对比表单中依赖业务上下文的 `display` / `disabled` 等 filterFunction 正常工作。
+   */
+  extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+  /**
+   * 返回 PropsPanel 主属性表单（FormPanel -> MForm）的 formState。
+   * 仅页面历史「查看差异 / 回滚确认」场景会使用该 formState 覆盖 CompareForm 中同名扩展字段，
+   * 以保证两处 filterFunction 读取到一致的运行态上下文。
+   */
+  getPropsPanelFormState?: () => FormState | undefined;
+  /**
+   * 内置页面 / 数据源 / 代码块的差异 / 回滚确认弹窗默认宽度（透传给 TMagicDialog 的 `width`），
+   * 如 `'1200px'` / `'80%'`。缺省时使用弹窗内置默认宽度（900px）。
+   * 业务自有历史（`viewDiff` / `confirmAndRevert`）可在调用时通过各自入参的 `width` 单独覆盖。
+   */
+  dialogWidth?: string;
+}
+
+/**
+ * 业务自有历史（如管理台「模块」）做差异对比时所需的额外渲染入参。
+ * 内置的页面 / 数据源 / 代码块按 `category` 自动取表单配置，无需传这些；
+ * 业务自有类别可通过 `loadConfig` 注入自定义表单配置加载逻辑。
+ */
+export interface CustomDiffFormOptions {
+  /**
+   * 自定义差异表单配置加载逻辑（如「模块」按 c_type 重建表单配置），
+   * 透传给弹窗内部的 CompareForm；缺省时按 `category` 走内置加载。
+   */
+  loadConfig?: CompareFormLoadConfig;
+  /** 需要走 self diff 的字段类型（如模块的 mod-cond）。 */
+  selfDiffFieldTypes?: string[];
+  /**
+   * 可选：外部提供的 formState（通常来自 PropsPanel 主表单），
+   * 对比弹窗会用它覆盖 CompareForm 中同名扩展字段，避免上下文不一致。
+   */
+  compareFormState?: FormState;
+  /**
+   * 差异 / 确认回滚弹窗宽度（透传给 HistoryDiffDialog 的 TMagicDialog `width`），
+   * 如 `'1200px'` / `'80%'`。缺省时使用弹窗内置默认宽度（900px）。
+   */
+  width?: string;
+}
+
+/**
+ * 业务自有历史复用「单步回滚」交互（{@link useHistoryRevert} 的 `confirmAndRevert`）的入参。
+ * 与内置页面 / 数据源 / 代码块回滚共用「目标校验 → 差异/二次确认弹窗 → 反向回滚」流程，
+ * 业务方只需提供：差异弹窗入参（可选）、表单配置加载（可选）、实际回滚执行函数。
+ */
+export interface ConfirmAndRevertOptions<T = unknown> extends CustomDiffFormOptions {
+  /**
+   * 差异确认弹窗入参；可对比的步骤（单实体 update）传入后弹差异确认弹窗，
+   * 传 null / 省略则退化为普通二次确认框（add / remove / 不可对比）。
+   */
+  diffPayload?: DiffDialogPayload | null;
+  /** 回滚前置校验：返回 true 表示目标数据已删除等不可回滚，给出统一提示并中止。 */
+  isTargetMissing?: () => boolean;
+  /** 用户确认后执行的实际回滚逻辑。 */
+  revert: () => T | Promise<T>;
+}