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

package/dist/es/style.css

@@ -592,7 +592,7 @@ fieldset.m-fieldset .m-form-tip {
   position: absolute;
   top: 4px;
   right: 4px;
-  z-index: 1;
+  z-index: 2;
   display: flex;
   align-items: center;
   height: 40px;
@@ -617,6 +617,23 @@ fieldset.m-fieldset .m-form-tip {
   padding: 0;
   list-style: none;
 }
+.m-editor-history-list-popover .m-editor-history-list-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  padding: 0 4px 4px;
+}
+.m-editor-history-list-popover .m-editor-history-list-clear {
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 12px;
+  color: #f56c6c;
+  cursor: pointer;
+  user-select: none;
+}
+.m-editor-history-list-popover .m-editor-history-list-clear:hover {
+  background-color: rgba(245, 108, 108, 0.12);
+}
 .m-editor-history-list-popover .m-editor-history-list-item {
   display: flex;
   align-items: center;
@@ -750,12 +767,18 @@ fieldset.m-fieldset .m-form-tip {
 }
 .m-editor-history-list-popover .m-editor-history-list-item-index {
   flex: 0 0 auto;
+  min-width: 30px;
+  text-align: right;
   color: #909399;
   font-family: Menlo, Monaco, Consolas, "Courier New", monospace;
   font-size: 11px;
   font-weight: 400;
   white-space: nowrap;
 }
+.m-editor-history-list-popover .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-popover .m-editor-history-list-item-time {
   flex: 0 0 auto;
   color: #a8abb2;
@@ -804,6 +827,30 @@ fieldset.m-fieldset .m-form-tip {
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+.m-editor-history-list-popover .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;
+}
+.m-editor-history-list-popover .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;
+}
 .m-editor-history-list-popover .m-editor-history-list-item-merge {
   flex: 0 0 auto;
   padding: 0 8px;
@@ -815,6 +862,17 @@ fieldset.m-fieldset .m-form-tip {
   font-weight: 500;
   letter-spacing: 0.2px;
 }
+.m-editor-history-list-popover .m-editor-history-list-item-actions {
+  display: none;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 6px;
+}
+.m-editor-history-list-popover .m-editor-history-list-group-head:hover > .m-editor-history-list-item-actions,
+.m-editor-history-list-popover .m-editor-history-list-substeps > li:hover > .m-editor-history-list-item-actions,
+.m-editor-history-list-popover .m-editor-history-list-initial:hover > .m-editor-history-list-item-actions {
+  display: flex;
+}
 .m-editor-history-list-popover .m-editor-history-list-item-diff {
   flex: 0 0 auto;
   padding: 0 6px;
@@ -835,13 +893,13 @@ fieldset.m-fieldset .m-form-tip {
   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;
 }
 .m-editor-history-list-popover .m-editor-history-list-item-goto:hover {
-  background-color: rgba(96, 98, 102, 0.18);
+  background-color: rgba(103, 194, 58, 0.24);
 }
 .m-editor-history-list-popover .m-editor-history-list-item-revert {
   flex: 0 0 auto;
@@ -1384,9 +1442,6 @@ fieldset.m-fieldset .m-form-tip {
   transition: all 0.2s ease 0s;
   padding: 5px 14px;
 }
-.page-bar-popover .menu-item .tmagic-design-button {
-  color: #313a40;
-}
 .page-bar-popover .menu-item:hover {
   background-color: #f3f5f9;
 }
@@ -1452,7 +1507,7 @@ fieldset.m-fieldset .m-form-tip {
   position: absolute;
   right: 15px;
   bottom: 15px;
-  z-index: 30;
+  z-index: 32;
   opacity: 0.5;
 }
 .m-editor-props-panel .m-editor-props-panel-src-icon:hover {
@@ -1462,7 +1517,7 @@ fieldset.m-fieldset .m-form-tip {
   position: absolute;
   right: 15px;
   bottom: 60px;
-  z-index: 30;
+  z-index: 31;
   opacity: 0.5;
 }
 .m-editor-props-panel .m-editor-props-panel-style-icon:hover {
@@ -1472,7 +1527,7 @@ fieldset.m-fieldset .m-form-tip {
   position: absolute;
   left: 0;
   top: 0;
-  z-index: 10;
+  z-index: 31;
 }
 .m-editor-props-panel .m-editor-resizer {
   position: absolute;

package/dist/es/utils/content-menu.js

@@ -4,7 +4,12 @@ import { NodeType, cloneDeep } from "@tmagic/core";
 import { computed, markRaw } from "vue";
 import { CopyDocument, Delete, DocumentCopy } from "@element-plus/icons-vue";
 //#region packages/editor/src/utils/content-menu.ts
-var useDeleteMenu = () => ({
+/**
+* 共享的右键菜单项构造器（画布 ViewerMenu 与图层树 LayerMenu 共用）。
+* `historySource` 用于标记本次操作的途径，调用方按所在面板传入：
+* 画布传 `'stage-contextmenu'`，树形面板传 `'tree-contextmenu'`。
+*/
+var useDeleteMenu = (historySource) => ({
 	type: "button",
 	text: "删除",
 	icon: Delete,
@@ -14,7 +19,7 @@ var useDeleteMenu = () => ({
 	},
 	handler: ({ editorService }) => {
 		const nodes = editorService.get("nodes");
-		nodes && editorService.remove(nodes);
+		nodes && editorService.remove(nodes, { historySource });
 	}
 });
 var useCopyMenu = () => ({
@@ -26,7 +31,7 @@ var useCopyMenu = () => ({
 		nodes && editorService?.copy(nodes);
 	}
 });
-var usePasteMenu = (menu) => ({
+var usePasteMenu = (historySource, menu) => ({
 	type: "button",
 	text: "粘贴",
 	icon: markRaw(DocumentCopy),
@@ -43,17 +48,20 @@ var usePasteMenu = (menu) => ({
 			editorService.paste({
 				left: initialLeft,
 				top: initialTop
-			});
-		} else editorService.paste();
+			}, void 0, { historySource });
+		} else editorService.paste(void 0, void 0, { historySource });
 	}
 });
-var moveTo = async (id, { editorService }) => {
+var moveTo = async (id, { editorService }, historySource) => {
 	const nodes = editorService.get("nodes") || [];
 	const parent = editorService.getNodeById(id);
 	if (!parent || nodes.length === 0) return;
-	await editorService.moveToContainer(cloneDeep(nodes), parent.id, { doNotSwitchPage: true });
+	await editorService.moveToContainer(cloneDeep(nodes), parent.id, {
+		doNotSwitchPage: true,
+		historySource
+	});
 };
-var useMoveToMenu = ({ editorService }) => {
+var useMoveToMenu = ({ editorService }, historySource) => {
 	return {
 		type: "button",
 		text: "移动至",
@@ -66,7 +74,7 @@ var useMoveToMenu = ({ editorService }) => {
 			text: `${page.name}(${page.id})`,
 			type: "button",
 			handler: (services) => {
-				moveTo(page.id, services);
+				moveTo(page.id, services, historySource);
 			}
 		}))
 	};

package/dist/es/utils/editor.js

@@ -431,5 +431,39 @@ var classifyDragSources = (configs, targetParent, getNodeInfo) => {
 		aborted: false
 	};
 };
+/**
+* 给「回滚」生成的新 step 用的简短描述生成器。
+* 与 UI 层 `describePageStep` 同义，但避免 service 反向依赖 layouts/，故放在此工具函数中。
+*/
+var describeStepForRevert = (step) => {
+	const items = step.diff ?? [];
+	const withId = (node, label) => {
+		const id = node?.id;
+		if (id === void 0 || id === null || `${id}` === "") return label;
+		return label ? `${label}（id: ${id}）` : `id: ${id}`;
+	};
+	switch (step.opType) {
+		case "add": {
+			const count = items.length;
+			const node = items[0]?.newSchema;
+			const label = node?.name || node?.type || "";
+			return `撤回新增 ${count} 个节点${count === 1 ? `（${withId(node, label)}）` : ""}`;
+		}
+		case "remove": {
+			const count = items.length;
+			const node = items[0]?.oldSchema;
+			const label = node?.name || node?.type || "";
+			return `还原已删除的 ${count} 个节点${count === 1 ? `（${withId(node, label)}）` : ""}`;
+		}
+		default:
+			if (items.length === 1) {
+				const { newSchema, oldSchema, changeRecords } = items[0];
+				const target = withId(newSchema || oldSchema, newSchema?.name || newSchema?.type || oldSchema?.name || oldSchema?.type || "");
+				const propPath = changeRecords?.[0]?.propPath;
+				return propPath ? `还原 ${target} · ${propPath}` : `还原 ${target}`;
+			}
+			return `还原 ${items.length} 个节点的修改`;
+	}
+};
 //#endregion
-export { COPY_CODE_STORAGE_KEY, COPY_DS_STORAGE_KEY, COPY_STORAGE_KEY, Fixed2Other, buildChangeRecords, calcAlignCenterStyle, calcLayerTargetIndex, calcMoveStyle, change2Fixed, classifyDragSources, collectRelatedNodes, editorNodeMergeCustomizer, fixNodeLeft, fixNodePosition, generatePageName, generatePageNameByApp, getGuideLineFromCache, getInitPositionStyle, getNodeIndex, getPageFragmentList, getPageList, getPageNameList, getRelativeStyle, isIncludeDataSource, moveItemsInContainer, resolveSelectedNode, serializeConfig, setChildrenLayout, setLayout, toggleFixedPosition };
+export { COPY_CODE_STORAGE_KEY, COPY_DS_STORAGE_KEY, COPY_STORAGE_KEY, Fixed2Other, buildChangeRecords, calcAlignCenterStyle, calcLayerTargetIndex, calcMoveStyle, change2Fixed, classifyDragSources, collectRelatedNodes, describeStepForRevert, editorNodeMergeCustomizer, fixNodeLeft, fixNodePosition, generatePageName, generatePageNameByApp, getGuideLineFromCache, getInitPositionStyle, getNodeIndex, getPageFragmentList, getPageList, getPageNameList, getRelativeStyle, isIncludeDataSource, moveItemsInContainer, resolveSelectedNode, serializeConfig, setChildrenLayout, setLayout, toggleFixedPosition };

package/dist/es/utils/history.js

@@ -0,0 +1,223 @@
+import { UndoRedo } from "./undo-redo.js";
+import { guid } from "@tmagic/utils";
+import { cloneDeep } from "lodash-es";
+//#region packages/editor/src/utils/history.ts
+/**
+* 「回滚」生成的新 step 简短描述。代码块 / 数据源共用。
+* 二者逻辑一致，仅展示名取值字段不同（代码块取 `name`，数据源取 `title`），
+* 因此通过 `getLabel` 注入取值方式。
+*
+* @param id 关联的代码块 / 数据源 id
+* @param diff 单条变更 diff（缺省视为空）
+* @param getLabel 从快照取展示名
+*/
+var describeRevertStep = (id, { oldSchema, newSchema, changeRecords } = {}, getLabel) => {
+	const labelOf = (schema) => getLabel(schema) || schema.id;
+	if (!oldSchema && newSchema) return `撤回新增 ${labelOf(newSchema) || id}`;
+	if (oldSchema && !newSchema) return `还原已删除的 ${labelOf(oldSchema) || id}`;
+	const label = newSchema && getLabel(newSchema) || oldSchema && getLabel(oldSchema) || `${id}`;
+	const propPath = changeRecords?.[0]?.propPath;
+	return propPath ? `还原 ${label} · ${propPath}` : `还原 ${label}`;
+};
+/**
+* 根据 old/new 是否为 null 推断 opType（与 push 时的约定一致）。
+*/
+var detectStackOpType = (oldVal, newVal) => {
+	if (oldVal === null && newVal !== null) return "add";
+	if (oldVal !== null && newVal === null) return "remove";
+	return "update";
+};
+/**
+* 构造一条代码块 / 数据源「按 id 分栈」的历史记录：两者除 payload 字段命名外完全一致。
+*
+* - `add`：oldValue = null；`remove`：newValue = null；`update`：两者都有，可带 changeRecords 做局部更新。
+* - 内容会做 cloneDeep 防止后续被外部引用篡改；opType 依据 old/new 是否为 null 推断。
+* - 仅负责构造 step 并返回，入栈与事件 emit 由各公共方法（pushCodeBlock / pushDataSource）自行处理。
+* - 不直接驱动业务 service，调用方负责实际写回。
+*/
+var createStackStep = (id, payload) => {
+	if (!id) return null;
+	const oldSchema = payload.oldValue ? cloneDeep(payload.oldValue) : null;
+	const newSchema = payload.newValue ? cloneDeep(payload.newValue) : null;
+	const changeRecords = payload.changeRecords?.length ? cloneDeep(payload.changeRecords) : void 0;
+	const opType = detectStackOpType(payload.oldValue, payload.newValue);
+	return {
+		uuid: guid(),
+		id,
+		opType,
+		diff: [{
+			...newSchema !== null ? { newSchema } : {},
+			...oldSchema !== null ? { oldSchema } : {},
+			...opType === "update" && changeRecords ? { changeRecords } : {}
+		}],
+		historyDescription: payload.historyDescription,
+		source: payload.source,
+		timestamp: Date.now()
+	};
+};
+var markStackSaved = (undoRedo) => {
+	if (!undoRedo) return;
+	undoRedo.updateElements((element) => {
+		element.saved = false;
+	});
+	undoRedo.updateCurrentElement((element) => {
+		element.saved = true;
+	});
+};
+/**
+* 把单个「按 id 分栈」的历史栈（代码块 / 数据源）拆成若干 group：
+* - 把"新增/删除"独立成组（语义上属于一次性事件，不应与 update 合并）；
+* - 连续 'update' 合并到同一组，组内 steps 顺序就是发生顺序。
+*
+* 代码块与数据源除 `kind` 外结构完全一致，统一由本方法处理；`kind` 决定返回的具体分组类型。
+*/
+var mergeStackSteps = (kind, id, list, cursor) => {
+	const groups = [];
+	let current = null;
+	const currentIndex = cursor - 1;
+	list.forEach((step, index) => {
+		const { opType } = step;
+		const applied = index < cursor;
+		const isCurrent = index === currentIndex;
+		if (opType === "update" && current?.opType === "update") {
+			current.steps.push({
+				step,
+				index,
+				applied,
+				isCurrent
+			});
+			current.applied = applied;
+			if (isCurrent) current.isCurrent = true;
+		} else {
+			current = {
+				kind,
+				id,
+				opType,
+				steps: [{
+					step,
+					index,
+					applied,
+					isCurrent
+				}],
+				applied,
+				isCurrent
+			};
+			groups.push(current);
+		}
+	});
+	return groups;
+};
+/**
+* 把页面栈拆成若干 group：
+* - 单节点的 'update' 按 targetId 与相邻同 targetId 的 update 合并到一个 group；
+* - 'add' / 'remove' 始终独立成组（语义上是结构变更，不应被收纳进单节点修改组）；
+* - 多节点 'update'（如批量改属性）也独立成组（无明确单一目标，避免误合并）。
+*/
+var mergePageSteps = (pageId, list, cursor) => {
+	const groups = [];
+	let current = null;
+	const currentIndex = cursor - 1;
+	list.forEach((step, index) => {
+		const applied = index < cursor;
+		const isCurrent = index === currentIndex;
+		const targetId = detectPageTargetId(step);
+		const targetName = detectPageTargetName(step);
+		const entry = {
+			step,
+			index,
+			applied,
+			isCurrent
+		};
+		const mergeable = step.opType === "update" && targetId !== void 0;
+		if (mergeable && current?.opType === "update" && current.targetId === targetId) {
+			current.steps.push(entry);
+			current.applied = applied;
+			if (isCurrent) current.isCurrent = true;
+			if (targetName) current.targetName = targetName;
+		} else {
+			current = {
+				kind: "page",
+				pageId,
+				opType: step.opType,
+				targetId: mergeable ? targetId : void 0,
+				targetName,
+				steps: [entry],
+				applied,
+				isCurrent
+			};
+			groups.push(current);
+		}
+	});
+	return groups;
+};
+/**
+* 解析 StepValue 中的"目标节点 id"用于合并：
+* - 单节点 update：取唯一一项 updatedItems 的节点 id；
+* - 其它情形（多节点 update / add / remove）：返回 undefined，表示不参与合并。
+*/
+var detectPageTargetId = (step) => {
+	if (step.opType !== "update") return void 0;
+	const items = step.diff;
+	if (items?.length !== 1) return void 0;
+	return items[0].newSchema?.id ?? items[0].oldSchema?.id;
+};
+/** 解析 StepValue 中的目标节点可读名（用于 UI 展示）。 */
+var detectPageTargetName = (step) => {
+	const items = step.diff;
+	if (step.opType === "update") {
+		if (items?.length === 1) {
+			const node = items[0].newSchema || items[0].oldSchema;
+			return node?.name || node?.type || (node?.id !== void 0 ? `${node.id}` : void 0);
+		}
+		return items?.length ? `${items.length} 个节点` : void 0;
+	}
+	if (step.opType === "add") {
+		if (items?.length === 1) {
+			const n = items[0].newSchema;
+			return n?.name || n?.type || `${n?.id}`;
+		}
+		return items?.length ? `${items.length} 个节点` : void 0;
+	}
+	if (step.opType === "remove") {
+		if (items?.length === 1) {
+			const n = items[0].oldSchema;
+			return n?.name || n?.type || `${n?.id}`;
+		}
+		return items?.length ? `${items.length} 个节点` : void 0;
+	}
+};
+/** 把 `Record<Id, UndoRedo>` 整体序列化为 `Record<Id, SerializedUndoRedo>`。 */
+var serializeStacks = (stacks) => {
+	const result = {};
+	Object.entries(stacks).forEach(([id, undoRedo]) => {
+		if (undoRedo) result[id] = undoRedo.serialize();
+	});
+	return result;
+};
+/**
+* 把 `Record<Id, SerializedUndoRedo>` 整体还原为 `Record<Id, UndoRedo>`。
+* 还原时把每个栈的游标定位到最近一条已保存（`saved === true`）记录之后。
+*/
+var deserializeStacks = (stacks = {}) => {
+	const result = {};
+	Object.entries(stacks).forEach(([id, serialized]) => {
+		if (serialized) result[id] = UndoRedo.fromSerialized(serialized, { isSavedStep: (element) => element.saved === true });
+	});
+	return result;
+};
+/**
+* 按 id 从「按 id 分栈」的记录表（代码块 / 数据源）中获取（或创建）对应的 UndoRedo 栈。
+*/
+var getOrCreateStack = (stacks, id) => {
+	if (!stacks[id]) stacks[id] = new UndoRedo();
+	return stacks[id];
+};
+/**
+* 撤销下限：当页面栈 index 0 是 `opType: 'initial'` 的基线 step 时为 1（基线不可被撤销），否则为 0。
+* 用于把 cursor 钉在基线之上，保证 undo / canUndo / goto 都不会越过初始基线。
+*/
+var undoFloor = (undoRedo) => {
+	return undoRedo.getElementList()[0]?.opType === "initial" ? 1 : 0;
+};
+//#endregion
+export { createStackStep, describeRevertStep, deserializeStacks, detectPageTargetId, detectPageTargetName, detectStackOpType, getOrCreateStack, markStackSaved, mergePageSteps, mergeStackSteps, serializeStacks, undoFloor };

package/dist/es/utils/indexed-db.js

@@ -0,0 +1,86 @@
+//#region packages/editor/src/utils/indexed-db.ts
+/**
+* 一组极简的、基于原生 IndexedDB 的 Promise KV 工具，避免引入额外依赖。
+* 仅用于浏览器环境；在不支持 IndexedDB 的环境（如 SSR / 部分测试环境）下会 reject。
+*/
+/** 是否处于支持 IndexedDB 的环境。 */
+var isIndexedDBSupported = () => typeof indexedDB !== "undefined" && indexedDB !== null;
+/**
+* 打开（必要时升级）数据库，确保目标 objectStore 存在后返回连接。
+*
+* 由于 objectStore 只能在 `onupgradeneeded` 内创建，这里先以当前版本打开，
+* 若发现 store 不存在则关闭连接、以更高版本重开来按需创建，兼容动态 storeName。
+*/
+var openIndexedDB = (dbName, storeName) => new Promise((resolve, reject) => {
+	if (!isIndexedDBSupported()) {
+		reject(/* @__PURE__ */ new Error("当前环境不支持 IndexedDB"));
+		return;
+	}
+	const request = indexedDB.open(dbName);
+	request.onupgradeneeded = () => {
+		const db = request.result;
+		if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName);
+	};
+	request.onerror = () => reject(request.error);
+	request.onsuccess = () => {
+		const db = request.result;
+		if (db.objectStoreNames.contains(storeName)) {
+			resolve(db);
+			return;
+		}
+		const nextVersion = db.version + 1;
+		db.close();
+		const upgradeRequest = indexedDB.open(dbName, nextVersion);
+		upgradeRequest.onupgradeneeded = () => {
+			const upgradeDb = upgradeRequest.result;
+			if (!upgradeDb.objectStoreNames.contains(storeName)) upgradeDb.createObjectStore(storeName);
+		};
+		upgradeRequest.onerror = () => reject(upgradeRequest.error);
+		upgradeRequest.onsuccess = () => resolve(upgradeRequest.result);
+	};
+});
+/** 写入（覆盖）一条记录。value 通过结构化克隆存储，支持 Map / Set 等结构。 */
+var idbSet = async (dbName, storeName, key, value) => {
+	const db = await openIndexedDB(dbName, storeName);
+	try {
+		await new Promise((resolve, reject) => {
+			const tx = db.transaction(storeName, "readwrite");
+			tx.objectStore(storeName).put(value, key);
+			tx.oncomplete = () => resolve();
+			tx.onabort = () => reject(tx.error);
+			tx.onerror = () => reject(tx.error);
+		});
+	} finally {
+		db.close();
+	}
+};
+/** 读取一条记录，不存在时返回 undefined。 */
+var idbGet = async (dbName, storeName, key) => {
+	const db = await openIndexedDB(dbName, storeName);
+	try {
+		return await new Promise((resolve, reject) => {
+			const request = db.transaction(storeName, "readonly").objectStore(storeName).get(key);
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error);
+		});
+	} finally {
+		db.close();
+	}
+};
+/** 删除一条记录。 */
+var idbDelete = async (dbName, storeName, key) => {
+	const db = await openIndexedDB(dbName, storeName);
+	try {
+		await new Promise((resolve, reject) => {
+			const tx = db.transaction(storeName, "readwrite");
+			tx.objectStore(storeName).delete(key);
+			tx.oncomplete = () => resolve();
+			tx.onabort = () => reject(tx.error);
+			tx.onerror = () => reject(tx.error);
+		});
+	} finally {
+		db.close();
+	}
+};
+//#endregion
+export { idbDelete, idbGet, idbSet, isIndexedDBSupported, openIndexedDB };

package/dist/es/utils/undo-redo.js

@@ -1,6 +1,32 @@
 import { cloneDeep } from "lodash-es";
 //#region packages/editor/src/utils/undo-redo.ts
-var UndoRedo = class {
+var UndoRedo = class UndoRedo {
+	/**
+	* 由 {@link UndoRedo.serialize} 产出的快照重建一个 UndoRedo 实例。
+	* 游标会被夹紧到 [0, length] 区间，避免脏数据导致越界。
+	*
+	* @param options.isSavedStep 可选谓词：若提供，则把游标定位到「最近一条满足该谓词的记录」之后
+	*   （即恢复到最近一个已保存点）；找不到匹配记录时退回快照中的原游标。
+	*/
+	static fromSerialized(data, options = {}) {
+		const undoRedo = new UndoRedo(data.listMaxSize);
+		const list = Array.isArray(data.elementList) ? data.elementList.map((item) => cloneDeep(item)) : [];
+		let cursor = Number.isFinite(data.listCursor) ? data.listCursor : list.length;
+		const overflow = list.length - undoRedo.listMaxSize;
+		if (overflow > 0) {
+			list.splice(0, overflow);
+			cursor -= overflow;
+		}
+		if (options.isSavedStep) {
+			for (let i = list.length - 1; i >= 0; i--) if (options.isSavedStep(list[i])) {
+				cursor = i + 1;
+				break;
+			}
+		}
+		undoRedo.elementList = list;
+		undoRedo.listCursor = Math.max(0, Math.min(cursor, list.length));
+		return undoRedo;
+	}
 	elementList;
 	listCursor;
 	listMaxSize;
@@ -10,6 +36,17 @@ var UndoRedo = class {
 		this.listCursor = 0;
 		this.listMaxSize = listMaxSize > minListMaxSize ? listMaxSize : minListMaxSize;
 	}
+	/**
+	* 导出当前栈的可序列化快照（深克隆，避免外部改动污染内部状态）。
+	* 配合 {@link UndoRedo.fromSerialized} 可在持久化后完整还原撤销/重做栈。
+	*/
+	serialize() {
+		return {
+			elementList: this.elementList.map((item) => cloneDeep(item)),
+			listCursor: this.listCursor,
+			listMaxSize: this.listMaxSize
+		};
+	}
 	pushElement(element) {
 		this.elementList.splice(this.listCursor, this.elementList.length - this.listCursor, cloneDeep(element));
 		this.listCursor += 1;
@@ -42,6 +79,28 @@ var UndoRedo = class {
 		return cloneDeep(this.elementList[this.listCursor - 1]);
 	}
 	/**
+	* 用 `element` 替换当前游标所在元素（cursor - 1），并丢弃其后的重做尾部（与 {@link pushElement} 的丢尾一致），
+	* 游标位置保持不变（元素数量不增）。cursor 为 0（无已应用元素）时不做任何操作并返回 false。
+	* 用于「连续同类记录合并」等就地替换最新一条的场景。
+	*/
+	replaceCurrentElement(element) {
+		if (this.listCursor < 1) return false;
+		this.elementList.splice(this.listCursor - 1, this.elementList.length - (this.listCursor - 1), cloneDeep(element));
+		return true;
+	}
+	/**
+	* 对当前游标所在元素（cursor - 1）做就地更新；cursor 为 0（全部已撤销）时不做任何操作。
+	* 用于给「当前步骤」打标记（如标记为已保存）等元数据写入场景。
+	*/
+	updateCurrentElement(updater) {
+		if (this.listCursor < 1) return;
+		updater(this.elementList[this.listCursor - 1]);
+	}
+	/** 对栈内全部元素做就地更新。用于批量清理元数据（如清空所有元素的已保存标记）。 */
+	updateElements(updater) {
+		this.elementList.forEach(updater);
+	}
+	/**
 	* 返回栈内全部元素的浅克隆数组（按时间顺序，索引 0 为最早一步）。
 	* 仅用于历史面板等只读展示场景，不应直接修改返回值。
 	*/