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

package/src/type.ts

@@ -16,7 +16,7 @@
  * 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';
@@ -33,7 +33,8 @@ import type {
   MPage,
   MPageFragment,
 } from '@tmagic/core';
-import type { ChangeRecord, FormConfig, TableColumnConfig, TypeFunction } from '@tmagic/form';
+import type { FieldSize } from '@tmagic/design';
+import type { ChangeRecord, FormConfig, FormState, TableColumnConfig, TypeFunction } from '@tmagic/form';
 import type StageCore from '@tmagic/stage';
 import type {
   CanDropIn,
@@ -56,7 +57,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 &
@@ -76,7 +77,7 @@ export interface FrameworkSlots {
   empty(props: {}): any;
   workspace(props: {}): any;
   'props-panel'(props: {}): any;
-  'footer'(props: {}): any;
+  footer(props: {}): any;
   'page-bar'(props: {}): any;
   'page-bar-add-button'(props: {}): any;
   'page-bar-title'(props: { page: MPage | MPageFragment }): any;
@@ -139,6 +140,7 @@ export type BeforeAdd = (config: MNode, parent: MContainer) => Promise<MNode> |
 export type GetConfig = (config: FormConfig) => Promise<FormConfig> | FormConfig;
 
 export interface EditorInstallOptions {
+  flat?: boolean;
   parseDSL: <T = any>(dsl: string) => T;
   customCreateMonacoEditor: (
     monaco: typeof import('monaco-editor'),
@@ -176,6 +178,11 @@ export interface StageOptions {
   containerHighlightClassName?: string;
   containerHighlightDuration?: number;
   containerHighlightType?: ContainerHighlightType;
+  /**
+   * 是否仅在新增组件（从组件列表拖入新组件）时才启用识别容器，
+   * 开启后在画布中拖动已有组件不会识别容器，默认 false
+   */
+  containerHighlightAddOnly?: boolean;
   disabledDragStart?: boolean;
   render?: (stage: StageCore) => HTMLDivElement | void | Promise<HTMLDivElement | void>;
   moveableOptions?: CustomizeMoveableOptions;
@@ -199,11 +206,32 @@ export interface StageOptions {
    */
   alwaysMultiSelect?: boolean;
   disabledRule?: boolean;
+  /**
+   * 禁用「非点击画布选中组件时（如从图层树、面包屑等外部选中），对选中区域做高亮闪烁提示」，
+   * 默认 false（即默认开启闪烁）
+   */
+  disabledFlashTip?: boolean;
   zoom?: number;
   /** 画布双击前的钩子函数，返回 false 则阻止默认的双击行为 */
   beforeDblclick?: (event: MouseEvent) => Promise<boolean | void> | boolean | void;
 }
 
+/**
+ * 节点校验错误信息，按来源（属性表单 / 样式表单）分别保存错误文案。
+ * 属性表单与样式表单是两个独立的 FormPanel，均指向同一节点，故以来源为键，
+ * 避免某个面板校验通过时误清另一个面板记录的错误。
+ * 节点视为存在错误当且仅当任一来源存在非空文本。
+ */
+export interface NodeInvalidInfo {
+  /** 属性表单校验错误文案（可能为包含 <br> 的 HTML） */
+  props?: string;
+  /** 样式表单校验错误文案（可能为包含 <br> 的 HTML） */
+  style?: string;
+}
+
+/** 节点校验错误来源 */
+export type NodeInvalidSource = keyof NodeInvalidInfo;
+
 export interface StoreState {
   root: MApp | null;
   page: MPage | MPageFragment | null;
@@ -214,6 +242,8 @@ export interface StoreState {
   stage: StageCore | null;
   stageLoading: boolean;
   modifiedNodeIds: Map<Id, Id>;
+  /** 校验失败的节点错误信息，按节点 id 存储，供组件树标记与保存拦截读取 */
+  invalidNodeIds: Map<Id, NodeInvalidInfo>;
   pageLength: number;
   pageFragmentLength: number;
   disabledMultiSelect: boolean;
@@ -291,6 +321,12 @@ export interface UiState {
   stageRect: StageRect;
   /** 编辑器列布局每一列的宽度，分为左中右三列 */
   columnWidth: GetColumnWidth;
+  /** 编辑器列布局左侧列最小宽度 */
+  minLeftColumnWidth: number;
+  /** 编辑器列布局中间列最小宽度 */
+  minCenterColumnWidth: number;
+  /** 编辑器列布局右侧列最小宽度 */
+  minRightColumnWidth: number;
   /** 是否显示画布参考线，true: 显示，false: 不显示，默认为true */
   showGuides: boolean;
   /** 画布上是否存在参考线 */
@@ -307,6 +343,8 @@ export interface UiState {
   hideSlideBar: boolean;
   /** 侧边栏面板配置 */
   sideBarItems: SideComponent[];
+  /** 当前激活的侧边栏面板 */
+  sideBarActiveTabName: string;
 
   // navMenu 的宽高
   navMenuRect: {
@@ -328,6 +366,7 @@ export interface EditorNodeInfo {
   node: MNode | null;
   parent: MContainer | null;
   page: MPage | MPageFragment | null;
+  path: MNode[];
 }
 // #endregion EditorNodeInfo
 
@@ -385,6 +424,9 @@ export interface MenuButton {
   items?: MenuButton[];
   /** 唯一标识，用于高亮 */
   id?: string | number;
+  buttonProps?: {
+    type?: string;
+  };
 }
 // #endregion MenuButton
 
@@ -475,6 +517,115 @@ 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>;
+
+/**
+ * CompareForm / ViewForm 共用的基础 props。
+ * 两者都基于同一套「按 category 加载 FormConfig + 注入 services/stage」的逻辑（见 useCompareForm），
+ * 差异仅在于是否做新旧值对比。这里抽出公共字段避免重复定义。
+ */
+export interface CompareFormBaseProps {
+  /** 当前值（对比场景下为修改后的值） */
+  value: Partial<MNode> | Partial<DataSourceSchema> | Partial<CodeBlockContent> | Record<string, any>;
+  /**
+   * 类型说明：
+   * - `category` 为 `node` 时，`type` 为节点组件的类型，例如 'text'、'button'、'page'、'container' 等
+   * - `category` 为 `data-source` 时，`type` 为数据源类型，例如 'base'、'http'
+   * - `category` 为 `code-block` 时，`type` 可不传
+   */
+  type?: string;
+  /** 表单配置类别，决定从哪里取 FormConfig */
+  category?: CompareCategory;
+  /** 数据源代码块场景下的数据源类型（base/http），用于代码块表单中"执行时机"展示 */
+  dataSourceType?: string;
+  labelWidth?: string;
+  /**
+   * 外层容器高度。设置后表单内容超出时会在组件内部出现滚动条，
+   * 避免 dialog / 面板使用方需要自行处理滚动。可传任意 CSS 长度，例如 `60vh` / `400px` / `100%`。
+   */
+  height?: string;
+  /**
+   * 用户自定义注入到 MForm.formState 的扩展字段，与 Editor 顶层的 `extendFormState`、
+   * PropsPanel 的 `extend-state` 语义一致。表单 item 的 `display` / `disabled` 等
+   * filterFunction 经常依赖这里注入的字段（如 stage、自定义业务上下文等），
+   * 因此在对比 / 展示场景下也需要透传，避免出现 `formState.xxx is undefined` 的运行时错误。
+   */
+  extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+  /**
+   * 外部透传的基础 formState（通常来自 PropsPanel 主属性表单）。
+   * 组件会提取其中的扩展字段覆盖到自己的 formState，保证 filterFunction 上下文一致。
+   */
+  baseFormState?: FormState;
+  /**
+   * 表单内组件的尺寸（透传给 MForm 的 `size`），可选 'large' | 'default' | 'small'。
+   * 缺省时使用 MForm 内置默认尺寸。
+   */
+  size?: FieldSize;
+  /**
+   * 自定义 FormConfig 加载逻辑。传入后将接管内置的按 `category`(node/data-source/code-block)
+   * 取配置逻辑，调用方可根据业务自行返回（或异步返回）表单配置。可通过
+   * `ctx.defaultLoadConfig()` 复用默认结果再做二次加工。
+   */
+  loadConfig?: CompareFormLoadConfig;
+  /** 编辑器服务集合，由调用方传入（不再通过 inject('services') 获取）。 */
+  services?: Services;
+}
+// #endregion CompareForm
+
 // #region SideItemKey
 export enum SideItemKey {
   COMPONENT_LIST = 'component-list',
@@ -618,114 +769,289 @@ 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': 变更前后的节点快照
-   *
-   * `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
-   * 缺省（未传 / 空数组）才退化为整节点替换。
+   * 本次变更的内容（统一 diff 表达），每项见 {@link StepDiffItem}。
+   * 页面节点（add/remove 多节点、update 多节点）会有多项，代码块 / 数据源通常只有一项。
    */
-  updatedItems?: { oldNode: MNode; newNode: MNode; changeRecords?: ChangeRecord[] }[];
+  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>;
+  /** 操作前的节点校验错误快照，撤销后还原（使撤销一个「校验失败」的改动后错误消失） */
+  invalidNodeIdsBefore?: Map<Id, NodeInvalidInfo>;
+  /** 操作后的节点校验错误快照，重做后还原（使重做后错误恢复） */
+  invalidNodeIdsAfter?: Map<Id, NodeInvalidInfo>;
+  [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
 /**
- * 代码块历史记录条目。按 codeBlock.id 分组保存到 historyState.codeBlockState。
- * - 新增：oldContent = null，newContent = 新内容
- * - 更新：oldContent / newContent 都为对应内容
- * - 删除：newContent = null，oldContent = 删除前内容
+ * 代码块历史记录条目（`diff` 内容为 {@link CodeBlockContent}），按 `data.id`（codeBlock.id）
+ * 分组保存到 historyState.steps.codeBlock。结构与 {@link StepValue} / {@link DataSourceStepValue}
+ * 一致，仅 `diff` 快照类型不同。
  */
-export interface CodeBlockStepValue {
-  /** 关联的代码块 id */
-  id: Id;
-  /** 变更前的代码块内容，新增时为 null */
-  oldContent: CodeBlockContent | null;
-  /** 变更后的代码块内容，删除时为 null */
-  newContent: CodeBlockContent | null;
-  /**
-   * form 端 propPath/value 列表。撤销/重做时若有则按 propPath 局部更新；
-   * 缺省才退化为整内容替换。新增/删除场景通常无 changeRecords。
-   */
-  changeRecords?: ChangeRecord[];
-  /** 调用方可选传入的人类可读描述，用于历史面板展示；不影响 undo/redo 行为。 */
-  historyDescription?: string;
-}
+export type CodeBlockStepValue = BaseStepValue<CodeBlockContent>;
 // #endregion CodeBlockStepValue
 
 // #region DataSourceStepValue
 /**
- * 数据源历史记录条目。按 dataSource.id 分组保存到 historyState.dataSourceState。
- * - 新增：oldSchema = null，newSchema = 新 schema
- * - 更新：oldSchema / newSchema 都为对应 schema
- * - 删除：newSchema = null，oldSchema = 删除前 schema
+ * 数据源历史记录条目（`diff` 内容为 {@link DataSourceSchema}），按 `data.id`（dataSource.id）
+ * 分组保存到 historyState.steps.dataSource。结构与 {@link StepValue} / {@link CodeBlockStepValue}
+ * 一致，仅 `diff` 快照类型不同。
  */
-export interface DataSourceStepValue {
-  /** 关联的数据源 id */
-  id: Id;
-  /** 变更前的数据源 schema，新增时为 null */
-  oldSchema: DataSourceSchema | null;
-  /** 变更后的数据源 schema，删除时为 null */
-  newSchema: DataSourceSchema | null;
+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 {
   /**
-   * form 端 propPath/value 列表。撤销/重做时若有则按 propPath 局部更新；
-   * 缺省才退化为整 schema 替换。新增/删除场景通常无 changeRecords。
+   * 全部历史栈的统一容器（页面 / 代码块 / 数据源 / 扩展类型），见 {@link HistorySteps}。
+   * 各类型互不影响，支持按 id 独立 undo/redo；是否可撤销 / 重做改用 {@link HistoryService.canUndo} /
+   * {@link HistoryService.canRedo}（按 stepType + id 查询）替代旧的全局 canUndo / canRedo 字段。
    */
-  changeRecords?: ChangeRecord[];
-  /** 调用方可选传入的人类可读描述，用于历史面板展示；不影响 undo/redo 行为。 */
-  historyDescription?: string;
+  steps: HistorySteps;
+  /**
+   * 各历史类型的展示名称，用于历史面板（{@link HistorySteps} 的 tab / 分组标题等）。
+   * 内置 `page` / `codeBlock` / `dataSource` 有默认中文名（页面 / 代码块 / 数据源），
+   * 扩展类型可通过 {@link HistoryService.registerStepType} 的 `name` 选项或
+   * {@link HistoryService.setStepName} 登记；读取请用 {@link HistoryService.getStepName}。
+   */
+  stepNames: Record<string, string>;
 }
-// #endregion DataSourceStepValue
 
-export interface HistoryState {
-  pageId?: Id;
-  pageSteps: Record<Id, UndoRedo<StepValue>>;
-  canRedo: boolean;
-  canUndo: boolean;
+// #region PersistedHistoryState
+/**
+ * 历史记录的可持久化快照。由 historyService.saveToIndexedDB 写入 IndexedDB，
+ * 再由 historyService.restoreFromIndexedDB 读出并重建各 UndoRedo 栈。
+ */
+export interface PersistedHistoryState {
+  /** 快照结构版本号，便于后续兼容升级。 */
+  version: number;
   /**
-   * 代码块历史栈，按 codeBlock.id 分组（每个代码块独立一份 UndoRedo）。
-   * 与页面/节点无关，支持独立 undo/redo。
+   * 全部历史栈的序列化快照，按「类型 -> id」两级分组，与 {@link HistorySteps} 对应。
+   * 内置 `page` / `codeBlock` / `dataSource`，并包含业务注册的扩展类型。
    */
-  codeBlockState: Record<Id, UndoRedo<CodeBlockStepValue>>;
+  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;
   /**
-   * 数据源历史栈，按 dataSource.id 分组（每个数据源独立一份 UndoRedo）。
-   * 与页面/节点无关，支持独立 undo/redo。
+   * 显式指定用于库名隔离的 DSL app id。
+   * 缺省时回退到当前 editorService 的 `root.id`；在「先恢复历史再 set root」场景下 root 尚未设置，
+   * 需由调用方（如从待加载 DSL 取 id）显式传入，否则会读 / 写到未按 app 隔离的默认库。
    */
-  dataSourceState: Record<Id, UndoRedo<DataSourceStepValue>>;
+  appId?: Id;
 }
+// #endregion HistoryPersistOptions
 
 // #region HistoryListEntry
 /**
  * 历史面板用：当前页面的一条历史步骤（包含位置和是否已应用）。
  */
-export interface PageHistoryStepEntry {
+export interface HistoryStepEntry<T> {
   /** 步骤内容 */
-  step: StepValue;
+  step: T;
   /** 在所属栈中的索引（0 为最早） */
   index: number;
   /** 是否处于"已应用"段（即位于栈游标之前）。撤销后变为 false。 */
@@ -735,63 +1061,39 @@ export interface PageHistoryStepEntry {
 }
 
 /**
- * 页面历史面板分组。
- * - 连续修改同一目标节点（updatedItems[0].oldNode.id 一致）的 'update' 步骤合并成一组；
- * - 多节点更新 / add / remove 始终独立成组（无法明确归属单一目标）。
- * - targetId 为 undefined 表示"无明确目标"（如 add/remove/多节点 update），不参与合并。
+ * 历史面板分组（页面 / 数据源 / 代码块 / 扩展类型统一结构）。
+ *
+ * 把指定历史栈的步骤列表按"目标"做相邻合并：
+ * - 连续修改同一目标（单实体 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 PageHistoryGroup {
-  kind: 'page';
-  /** 所属页面 id */
-  pageId: 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 与相邻同 id 的 update 合并。
-   * undefined 表示该分组不可被合并（add / remove / 多节点 update）。
+   * 合并的目标 id：仅"单实体 update"有值，并按此与相邻同 id 的 update 合并。
+   * undefined 表示该分组不可被合并（add / remove / 多实体 update）。
    */
   targetId?: Id;
-  /** 目标节点的可读名（取最后一步的 newNode.name/type/id） */
+  /** 目标可读名（取最后一步快照的 name/type/id）。 */
   targetName?: string;
-  /** 组内所有步骤，按时间正序 */
-  steps: PageHistoryStepEntry[];
-  /** 组内最后一步是否已应用 */
+  /** 组内所有步骤，按时间正序。 */
+  steps: { step: T; index: number; applied: boolean; isCurrent?: boolean }[];
+  /** 组内最后一步是否已应用。 */
   applied: boolean;
   /** 是否为当前所在的分组（包含栈中最近一次已应用步骤的那一组）。 */
   isCurrent?: boolean;
 }
-
-/**
- * 代码块历史面板分组。
- * - 同一 codeBlockId 的栈内，相邻的 'update' 操作会合并成一个 group；
- * - 'add' / 'remove' 始终独立成组（语义上是一次性事件）。
- */
-export interface CodeBlockHistoryGroup {
-  kind: 'code-block';
-  /** 关联的 codeBlock id */
-  id: Id;
-  /** 该分组的操作类型 */
-  opType: HistoryOpType;
-  /** 组内所有步骤，按时间正序 */
-  steps: { step: CodeBlockStepValue; index: number; applied: boolean; isCurrent?: boolean }[];
-  /** 组内最后一步是否已应用，用于整组的状态展示 */
-  applied: boolean;
-  /** 是否为当前所在的分组（包含该栈最近一次已应用步骤的那一组）。 */
-  isCurrent?: boolean;
-}
-
-/**
- * 数据源历史面板分组，结构同 CodeBlockHistoryGroup。
- */
-export interface DataSourceHistoryGroup {
-  kind: 'data-source';
-  id: Id;
-  opType: HistoryOpType;
-  steps: { step: DataSourceStepValue; index: number; applied: boolean; isCurrent?: boolean }[];
-  applied: boolean;
-  /** 是否为当前所在的分组（包含该栈最近一次已应用步骤的那一组）。 */
-  isCurrent?: boolean;
-}
 // #endregion HistoryListEntry
 
 export enum KeyBindingCommand {
@@ -956,6 +1258,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];
 }
@@ -983,13 +1287,32 @@ export interface PageBarSortOptions extends PartSortableOptions {
 }
 // #endregion PageBarSortOptions
 
+/**
+ * 右键菜单当前目标（侧栏树节点等）。
+ * 数据源 / 代码块面板通过 `customContentMenu` 的 `getTarget` 暴露，业务在 handler 内自行读取。
+ */
+export interface ContentMenuTarget {
+  /** 目标 ID */
+  id: string;
+  /** 原始节点数据（树节点等） */
+  data?: TreeNodeData;
+}
+
+export type ContentMenuType = 'layer' | 'data-source' | 'viewer' | 'code-block';
+
 export type CustomContentMenuFunction = (
   menus: (MenuButton | MenuComponent)[],
-  type: 'layer' | 'data-source' | 'viewer' | 'code-block',
+  type: ContentMenuType,
+  /** 读取当前右键目标；数据源 / 代码块面板会传入，图层 / 画布一般不需要 */
+  getTarget?: () => ContentMenuTarget | null,
 ) => (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[]];
@@ -997,6 +1320,82 @@ 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];
+  /** 节点校验错误状态发生变化时触发，携带当前完整的错误 Map（供非响应式消费方订阅） */
+  'invalid-node-change': [invalidNodeIds: Map<Id, NodeInvalidInfo>];
+}
+
+// #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} 各操作类型共有的历史相关字段。 */
+export interface EditorChangeEventHistoryMeta {
+  /**
+   * 本次变更的「历史来源」（调用 DSL 操作时传入的 {@link HistoryOpOptions.historySource}，
+   * 撤销 / 重做时则为被应用 step 上记录的 `source`），未携带时为 undefined。
+   */
+  historySource?: HistoryOpSource;
+  /**
+   * 本次操作是否未写入历史记录（即调用时传入的 {@link HistoryOpOptions.doNotPushHistory}，缺省为 false）；
+   * 撤销 / 重做路径补发的事件恒为 true（撤销/重做本身不再入栈）。
+   */
+  doNotPushHistory?: boolean;
+}
+
+/**
+ * {@link EditorEvents.change} 的回调参数：以 `type` 区分操作类型，并携带对应的操作内容。
+ * `data` 为本次变更的节点列表，每项包含 node 及其所属的 page（可能为 null）；
+ * `move-layer` 额外带层级偏移 `offset`，`drag-to` 额外带目标位置 `targetIndex` / `targetParent`；
+ * 历史相关字段（historySource / doNotPushHistory）见 {@link EditorChangeEventHistoryMeta}。
+ */
+export type EditorChangeEvent =
+  | ({ type: 'add'; data: EditorChangeItem[] } & EditorChangeEventHistoryMeta)
+  | ({ type: 'remove'; data: EditorChangeItem[] } & EditorChangeEventHistoryMeta)
+  | ({ type: 'update'; data: EditorUpdateChangeItem[] } & EditorChangeEventHistoryMeta)
+  | ({ type: 'move-layer'; data: EditorChangeItem[]; offset: number | LayerOffset } & EditorChangeEventHistoryMeta)
+  | ({
+      type: 'drag-to';
+      data: EditorChangeItem[];
+      targetIndex: number;
+      targetParent: MContainer;
+    } & EditorChangeEventHistoryMeta);
+// #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 }];
+  /**
+   * 页面 / 页面片结构变更（新增 / 删除）时派发，见 {@link HistoryService.notifyPageStructureChange}。
+   * 一次操作（add / remove / setRoot 整体替换）涉及多个页面时合并为**一个**事件；
+   * `add` / `remove` 分别为本次新增与删除的页面列表（其一可为空数组）。
+   */
+  'page-structure-change': [change: { add: (MPage | MPageFragment)[]; remove: (MPage | MPageFragment)[] }];
 }
 
 export const canUsePluginMethods = {
@@ -1029,16 +1428,21 @@ 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）。
@@ -1046,7 +1450,9 @@ export interface HistoryOpOptions {
 export interface HistoryOpOptionsWithChangeRecords extends HistoryOpOptions {
   changeRecords?: ChangeRecord[];
 }
+// #endregion HistoryOpOptionsWithChangeRecords
 
+// #region DslOpOptions
 /**
  * DSL 修改类操作的通用配置
  * - doNotSelect: 操作后是否不要自动触发选中（不调用 this.select / this.multiSelect / stage.select / stage.multiSelect）
@@ -1056,3 +1462,141 @@ 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;
+  /**
+   * 差异 / 确认回滚弹窗内 form 表单的尺寸（透传给 CompareForm 的 `size`），
+   * 可选 `'large' | 'default' | 'small'`，缺省时使用表单内置默认尺寸。
+   */
+  size?: FieldSize;
+}
+
+/**
+ * 业务自有历史复用「单步回滚」交互（{@link useHistoryRevert} 的 `confirmAndRevert`）的入参。
+ * 与内置页面 / 数据源 / 代码块回滚共用「目标校验 → 差异/二次确认弹窗 → 反向回滚」流程，
+ * 业务方只需提供：差异弹窗入参（可选）、表单配置加载（可选）、实际回滚执行函数。
+ */
+export interface ConfirmAndRevertOptions<T = unknown> extends CustomDiffFormOptions {
+  /**
+   * 差异确认弹窗入参；可对比的步骤（单实体 update）传入后弹差异确认弹窗，
+   * 传 null / 省略则退化为普通二次确认框（add / remove / 不可对比）。
+   */
+  diffPayload?: DiffDialogPayload | null;
+  /** 回滚前置校验：返回 true 表示目标数据已删除等不可回滚，给出统一提示并中止。 */
+  isTargetMissing?: () => boolean;
+  /** 用户确认后执行的实际回滚逻辑。 */
+  revert: () => T | Promise<T>;
+}