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

package/src/theme/history-list-panel.scss

@@ -13,7 +13,7 @@
     position: absolute;
     top: 4px;
     right: 4px;
-    z-index: 1;
+    z-index: 2;
     display: flex;
     align-items: center;
     height: 40px;
@@ -45,6 +45,28 @@
     list-style: none;
   }
 
+  // 历史列表工具条：放置「清空」等列表级操作，右对齐。
+  .m-editor-history-list-toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    padding: 0 4px 4px;
+  }
+
+  // 「清空」按钮：红色文字按钮，强调破坏性操作（点击后会二次确认）。
+  .m-editor-history-list-clear {
+    padding: 2px 8px;
+    border-radius: 4px;
+    font-size: 12px;
+    color: #f56c6c;
+    cursor: pointer;
+    user-select: none;
+
+    &:hover {
+      background-color: rgba(245, 108, 108, 0.12);
+    }
+  }
+
   .m-editor-history-list-item {
     display: flex;
     align-items: center;
@@ -215,6 +237,10 @@
 
   .m-editor-history-list-item-index {
     flex: 0 0 auto;
+    // 固定最小宽度并右对齐：序号位数不一（#6 / #16）时右边界仍统一，
+    // 使紧随其后的「类型」徽标在各行间对齐成整齐的一列。
+    min-width: 30px;
+    text-align: right;
     color: #909399;
     font-family: Menlo, Monaco, Consolas, "Courier New", monospace;
     font-size: 11px;
@@ -222,6 +248,15 @@
     white-space: nowrap;
   }
 
+  // 合并组头部展示的是步骤区间（如 #10-#20），宽度本就不定、也无需与单步行对齐，
+  // 恢复自然宽度与左对齐，避免被强制成固定列后显得突兀。
+  .m-editor-history-list-group.is-merged
+    > .m-editor-history-list-group-head
+    > .m-editor-history-list-item-index {
+    min-width: 0;
+    text-align: left;
+  }
+
   // 操作时间：弱化展示，紧贴在描述之后、各操作按钮之前。
   .m-editor-history-list-item-time {
     flex: 0 0 auto;
@@ -281,6 +316,34 @@
     white-space: nowrap;
   }
 
+  // 「操作途径」徽标：浅灰描边胶囊，弱化展示来源（画布 / 图层 / 配置面板…），不抢占描述焦点。
+  .m-editor-history-list-item-source {
+    flex: 0 0 auto;
+    padding: 0 6px;
+    border: 1px solid #dcdfe6;
+    border-radius: 8px;
+    font-size: 10px;
+    line-height: 14px;
+    color: #909399;
+    background-color: #f4f4f5;
+    white-space: nowrap;
+    font-weight: 400; // 防止被合并组头部的粗体继承
+  }
+
+  // 「已保存」徽标：绿色实心胶囊，标记最近一次保存对应的历史记录（与 historyService.markSaved 对应）。
+  .m-editor-history-list-item-saved {
+    flex: 0 0 auto;
+    padding: 0 6px;
+    border-radius: 8px;
+    font-size: 10px;
+    line-height: 16px;
+    color: #fff;
+    background-color: #67c23a;
+    white-space: nowrap;
+    font-weight: 500;
+    letter-spacing: 0.2px;
+  }
+
   // 「合并 N 步」徽标：紫色实心胶囊，与合并组卡片色系一致，醒目区分单步条目。
   .m-editor-history-list-item-merge {
     flex: 0 0 auto;
@@ -294,6 +357,24 @@
     letter-spacing: 0.2px;
   }
 
+  // 操作区：把「回滚 / 回到 / 查看差异」收敛为一个统一容器，默认隐藏，
+  // 仅在指针悬停于所在行时显示。静止状态下每行最右侧固定为「时间」，
+  // 各行因此能对齐成整齐的右侧列，避免按钮数量不一导致的参差错乱。
+  .m-editor-history-list-item-actions {
+    display: none;
+    flex: 0 0 auto;
+    align-items: center;
+    gap: 6px;
+  }
+
+  .m-editor-history-list-group-head:hover > .m-editor-history-list-item-actions,
+  .m-editor-history-list-substeps
+    > li:hover
+    > .m-editor-history-list-item-actions,
+  .m-editor-history-list-initial:hover > .m-editor-history-list-item-actions {
+    display: flex;
+  }
+
   .m-editor-history-list-item-diff {
     flex: 0 0 auto;
     padding: 0 6px;
@@ -310,21 +391,21 @@
     }
   }
 
-  // 「跳转」按钮：将历史游标移动到该 step，替代原先点击整行跳转的交互。
-  // 使用与组卡片一致的紫色色系，与「查看差异」「回滚」区分开。
+  // 「回到」按钮：将历史游标移动到该 step。使用绿色色系，
+  // 与红色「回滚」、蓝色「查看差异」区分，也避免与紧邻的灰色「来源」徽标混淆。
   .m-editor-history-list-item-goto {
     flex: 0 0 auto;
     padding: 0 6px;
     border-radius: 2px;
     font-size: 10px;
     line-height: 16px;
-    color: #606266;
-    background-color: rgba(96, 98, 102, 0.1);
+    color: #529b2e;
+    background-color: rgba(103, 194, 58, 0.12);
     cursor: pointer;
     user-select: none;
 
     &:hover {
-      background-color: rgba(96, 98, 102, 0.18);
+      background-color: rgba(103, 194, 58, 0.24);
     }
   }
 

package/src/theme/page-bar.scss

@@ -102,10 +102,6 @@
     transition: all 0.2s ease 0s;
     padding: 5px 14px;
 
-    .tmagic-design-button {
-      color: $font-color;
-    }
-
     &:hover {
       background-color: $hover-color;
     }

package/src/theme/props-panel.scss

@@ -58,7 +58,7 @@
     position: absolute;
     right: 15px;
     bottom: 15px;
-    z-index: 30;
+    z-index: 32;
     opacity: 0.5;
 
     &:hover {
@@ -70,7 +70,7 @@
     position: absolute;
     right: 15px;
     bottom: 60px;
-    z-index: 30;
+    z-index: 31;
     opacity: 0.5;
 
     &:hover {
@@ -82,7 +82,7 @@
     position: absolute;
     left: 0;
     top: 0;
-    z-index: 10;
+    z-index: 31;
   }
 
   .m-editor-resizer {

package/src/type.ts

@@ -56,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 &
@@ -312,6 +312,8 @@ export interface UiState {
   hideSlideBar: boolean;
   /** 侧边栏面板配置 */
   sideBarItems: SideComponent[];
+  /** 当前激活的侧边栏面板 */
+  sideBarActiveTabName: string;
 
   // navMenu 的宽高
   navMenuRect: {
@@ -390,6 +392,9 @@ export interface MenuButton {
   items?: MenuButton[];
   /** 唯一标识，用于高亮 */
   id?: string | number;
+  buttonProps?: {
+    type?: string;
+  };
 }
 // #endregion MenuButton
 
@@ -510,7 +515,7 @@ export interface HistoryListExtraTab {
  * - data-source: 数据源，按 `type`(base/http/...) 从 dataSourceService 获取数据源表单配置
  * - code-block: 数据源代码块，使用内置的代码块表单配置
  */
-export type CompareCategory = 'node' | 'data-source' | 'code-block';
+export type CompareCategory = 'node' | 'data-source' | 'code-block' | string;
 
 /**
  * 自定义 `loadConfig` 时回传的上下文，聚合了组件当前的对比入参，
@@ -680,95 +685,172 @@ 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 {
-  /** 页面信息 */
-  data: { name: string; id: Id };
-  opType: HistoryOpType;
-  /** 操作前选中的节点 ID，用于撤销后恢复选择状态 */
-  selectedBefore: Id[];
-  /** 操作后选中的节点 ID，用于重做后恢复选择状态 */
-  selectedAfter: Id[];
-  modifiedNodeIds: Map<Id, Id>;
-  /** opType 'add': 新增的节点 */
-  nodes?: MNode[];
-  /** opType 'add': 父节点 ID */
+// #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 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;
-  /** opType 'add': 每个新增节点在父节点 items 中的索引 */
-  indexMap?: Record<string, number>;
-  /** opType 'remove': 被删除的节点及其位置信息 */
-  removedItems?: { node: MNode; parentId: Id; index: number }[];
+  /** 在父节点 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> {
   /**
-   * opType 'update': 变更前后的节点快照
-   *
-   * `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
-   * 缺省（未传 / 空数组）才退化为整节点替换。
+   * 历史记录唯一标识（uuid）。入栈时自动写入（若调用方未指定），
+   * 用于精确定位 / 引用某一条历史记录（如 revert、埋点、跨端同步等）。
+   * 注意与各自的 `id`（关联的页面 / 代码块 / 数据源 id）区分。
    */
-  updatedItems?: { oldNode: MNode; newNode: MNode; changeRecords?: ChangeRecord[] }[];
+  uuid: string;
+  /** 操作类型：新增 / 删除 / 更新（三类历史记录统一携带）。 */
+  opType: HistoryOpType;
+  /**
+   * 本次变更的内容（统一 diff 表达），每项见 {@link StepDiffItem}。
+   * 页面节点（add/remove 多节点、update 多节点）会有多项，代码块 / 数据源通常只有一项。
+   */
+  diff: StepDiffItem<T>[];
   /**
    * 调用方可选传入的人类可读描述（如「调整按钮颜色」），用于历史面板展示。
    * 不影响 undo/redo 行为；缺省时面板会根据节点 / propPath 自动生成描述。
    */
   historyDescription?: string;
   /**
-   * 入栈时间戳（毫秒）。在 historyService.push 时自动写入（若调用方未指定），仅用于历史面板展示。
+   * 操作途径：标记本次变更由哪条交互入口触发，取值见 {@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;
+}
+// #endregion BaseStepValue
+
+// #region StepValue
+export interface StepValue extends BaseStepValue<MNode> {
+  /** 页面信息 */
+  data: { name: string; id: Id };
+  /** 操作前选中的节点 ID，用于撤销后恢复选择状态 */
+  selectedBefore: Id[];
+  /** 操作后选中的节点 ID，用于重做后恢复选择状态 */
+  selectedAfter: Id[];
+  modifiedNodeIds: Map<Id, Id>;
 }
 // #endregion StepValue
 
 // #region CodeBlockStepValue
 /**
  * 代码块历史记录条目。按 codeBlock.id 分组保存到 historyState.codeBlockState。
- * - 新增：oldContent = null，newContent = 新内容
- * - 更新：oldContent / newContent 都为对应内容
- * - 删除：newContent = null，oldContent = 删除前内容
+ * 变更内容统一由 `diff`（单项）表达，每项见 {@link StepDiffItem}：
+ * - 新增（opType 'add'）：仅 `newSchema`（新内容）；
+ * - 更新（opType 'update'）：`oldSchema` + `newSchema`，并可带 `changeRecords` 做局部更新；
+ * - 删除（opType 'remove'）：仅 `oldSchema`（删除前内容）。
  */
-export interface CodeBlockStepValue {
+export interface CodeBlockStepValue extends BaseStepValue<CodeBlockContent> {
   /** 关联的代码块 id */
   id: Id;
-  /** 变更前的代码块内容，新增时为 null */
-  oldContent: CodeBlockContent | null;
-  /** 变更后的代码块内容，删除时为 null */
-  newContent: CodeBlockContent | null;
-  /**
-   * form 端 propPath/value 列表。撤销/重做时若有则按 propPath 局部更新；
-   * 缺省才退化为整内容替换。新增/删除场景通常无 changeRecords。
-   */
-  changeRecords?: ChangeRecord[];
-  /** 调用方可选传入的人类可读描述，用于历史面板展示；不影响 undo/redo 行为。 */
-  historyDescription?: string;
-  /** 入栈时间戳（毫秒），入栈时自动写入，仅用于历史面板展示。 */
-  timestamp?: number;
 }
 // #endregion CodeBlockStepValue
 
 // #region DataSourceStepValue
 /**
  * 数据源历史记录条目。按 dataSource.id 分组保存到 historyState.dataSourceState。
- * - 新增：oldSchema = null，newSchema = 新 schema
- * - 更新：oldSchema / newSchema 都为对应 schema
- * - 删除：newSchema = null，oldSchema = 删除前 schema
+ * 变更内容统一由 `diff`（单项）表达，每项见 {@link StepDiffItem}：
+ * - 新增（opType 'add'）：仅 `newSchema`（新 schema）；
+ * - 更新（opType 'update'）：`oldSchema` + `newSchema`，并可带 `changeRecords` 做局部更新；
+ * - 删除（opType 'remove'）：仅 `oldSchema`（删除前 schema）。
  */
-export interface DataSourceStepValue {
+export interface DataSourceStepValue extends BaseStepValue<DataSourceSchema> {
   /** 关联的数据源 id */
   id: Id;
-  /** 变更前的数据源 schema，新增时为 null */
-  oldSchema: DataSourceSchema | null;
-  /** 变更后的数据源 schema，删除时为 null */
-  newSchema: DataSourceSchema | null;
-  /**
-   * form 端 propPath/value 列表。撤销/重做时若有则按 propPath 局部更新；
-   * 缺省才退化为整 schema 替换。新增/删除场景通常无 changeRecords。
-   */
-  changeRecords?: ChangeRecord[];
-  /** 调用方可选传入的人类可读描述，用于历史面板展示；不影响 undo/redo 行为。 */
-  historyDescription?: string;
-  /** 入栈时间戳（毫秒），入栈时自动写入，仅用于历史面板展示。 */
-  timestamp?: number;
 }
 // #endregion DataSourceStepValue
 
@@ -789,6 +871,45 @@ export interface HistoryState {
   dataSourceState: Record<Id, UndoRedo<DataSourceStepValue>>;
 }
 
+// #region PersistedHistoryState
+/**
+ * 历史记录的可持久化快照。由 historyService.saveToIndexedDB 写入 IndexedDB，
+ * 再由 historyService.restoreFromIndexedDB 读出并重建各 UndoRedo 栈。
+ */
+export interface PersistedHistoryState {
+  /** 快照结构版本号，便于后续兼容升级。 */
+  version: number;
+  /** 保存时的活动页 id。 */
+  pageId?: Id;
+  /** 各页面历史栈的序列化快照，按 pageId 分组。 */
+  pageSteps: Record<Id, SerializedUndoRedo<StepValue>>;
+  /** 各代码块历史栈的序列化快照，按 codeBlockId 分组。 */
+  codeBlockState: Record<Id, SerializedUndoRedo<CodeBlockStepValue>>;
+  /** 各数据源历史栈的序列化快照，按 dataSourceId 分组。 */
+  dataSourceState: Record<Id, SerializedUndoRedo<DataSourceStepValue>>;
+  /** 保存时间戳（毫秒）。 */
+  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
 /**
  * 历史面板用：当前页面的一条历史步骤（包含位置和是否已应用）。
@@ -1099,16 +1220,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）。
@@ -1116,7 +1242,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）
@@ -1126,11 +1254,12 @@ export interface DslOpOptions extends HistoryOpOptions {
   doNotSelect?: boolean;
   doNotSwitchPage?: boolean;
 }
+// #endregion DslOpOptions
 
 /** 差异对话框的入参 */
 export interface DiffDialogPayload {
   /** 表单类别 */
-  category: CompareCategory;
+  category?: CompareCategory;
   /** 节点类型 / 数据源类型 */
   type?: string;
   /** 代码块场景下的数据源类型 */
@@ -1146,3 +1275,34 @@ export interface DiffDialogPayload {
   /** 用于标题展示的目标 id */
   id?: string | number;
 }
+
+/**
+ * 一组「描述 + 可操作性」的判定函数集合。页面 / 数据源 / 代码块及业务自定义历史
+ * 各自实现一份，作为整体注入，避免把 describe* / isStep* 拆成多个独立 props 反复透传。
+ */
+export interface HistoryRowDescriptor<T extends BaseStepValue = BaseStepValue> {
+  /** 组级描述文案生成器，接收一个 group，返回展示文本。 */
+  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;
+}

package/src/utils/content-menu.ts

@@ -5,11 +5,16 @@ import { cloneDeep, Id, MContainer, NodeType } from '@tmagic/core';
 import { calcValueByFontsize, isPage, isPageFragment } from '@tmagic/utils';
 
 import ContentMenu from '@editor/components/ContentMenu.vue';
-import type { MenuButton, Services } from '@editor/type';
+import type { HistoryOpSource, MenuButton, Services } from '@editor/type';
 
 import { COPY_STORAGE_KEY } from './editor';
 
-export const useDeleteMenu = (): MenuButton => ({
+/**
+ * 共享的右键菜单项构造器（画布 ViewerMenu 与图层树 LayerMenu 共用）。
+ * `historySource` 用于标记本次操作的途径，调用方按所在面板传入：
+ * 画布传 `'stage-contextmenu'`，树形面板传 `'tree-contextmenu'`。
+ */
+export const useDeleteMenu = (historySource?: HistoryOpSource): MenuButton => ({
   type: 'button',
   text: '删除',
   icon: Delete,
@@ -19,7 +24,7 @@ export const useDeleteMenu = (): MenuButton => ({
   },
   handler: ({ editorService }) => {
     const nodes = editorService.get('nodes');
-    nodes && editorService.remove(nodes);
+    nodes && editorService.remove(nodes, { historySource });
   },
 });
 
@@ -33,7 +38,10 @@ export const useCopyMenu = (): MenuButton => ({
   },
 });
 
-export const usePasteMenu = (menu?: ShallowRef<InstanceType<typeof ContentMenu> | null>): MenuButton => ({
+export const usePasteMenu = (
+  historySource?: HistoryOpSource,
+  menu?: ShallowRef<InstanceType<typeof ContentMenu> | null>,
+): MenuButton => ({
   type: 'button',
   text: '粘贴',
   icon: markRaw(DocumentCopy),
@@ -52,14 +60,14 @@ export const usePasteMenu = (menu?: ShallowRef<InstanceType<typeof ContentMenu>
       const initialTop =
         calcValueByFontsize(stage?.renderer?.getDocument(), (rect.top || 0) - (parentRect?.top || 0)) /
         uiService.get('zoom');
-      editorService.paste({ left: initialLeft, top: initialTop });
+      editorService.paste({ left: initialLeft, top: initialTop }, undefined, { historySource });
     } else {
-      editorService.paste();
+      editorService.paste(undefined, undefined, { historySource });
     }
   },
 });
 
-const moveTo = async (id: Id, { editorService }: Services) => {
+const moveTo = async (id: Id, { editorService }: Services, historySource?: HistoryOpSource) => {
   const nodes = editorService.get('nodes') || [];
   const parent = editorService.getNodeById(id) as MContainer;
 
@@ -69,10 +77,11 @@ const moveTo = async (id: Id, { editorService }: Services) => {
   // 不要再走 remove + add 两步，否则会被切成两条历史（且语义也不正确）。
   await editorService.moveToContainer(cloneDeep(nodes), parent.id, {
     doNotSwitchPage: true,
+    historySource,
   });
 };
 
-export const useMoveToMenu = ({ editorService }: Services): MenuButton => {
+export const useMoveToMenu = ({ editorService }: Services, historySource?: HistoryOpSource): MenuButton => {
   const root = computed(() => editorService.get('root'));
 
   return {
@@ -89,7 +98,7 @@ export const useMoveToMenu = ({ editorService }: Services): MenuButton => {
         text: `${page.name}(${page.id})`,
         type: 'button',
         handler: (services: Services) => {
-          moveTo(page.id, services);
+          moveTo(page.id, services, historySource);
         },
       })),
   };