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

package/dist/es/services/history.js

@@ -1,322 +1,196 @@
+import { getEditorConfig } from "../utils/config.js";
 import BaseService from "./BaseService.js";
 import { UndoRedo } from "../utils/undo-redo.js";
+import { deserializeStacks, getOrCreateStack, markStackSaved, mergeSteps, serializeStacks, undoFloor } from "../utils/history.js";
+import { idbGet, idbSet } from "../utils/indexed-db.js";
+import editor_default from "./editor.js";
+import { guid } from "@tmagic/utils";
 import { reactive } from "vue";
-import { cloneDeep } from "lodash-es";
-var history_default = new class History extends BaseService {
-	/**
-	* 把单个代码块栈拆成若干 group：
-	* - 把"新增/删除"独立成组（语义上属于一次性事件，不应与 update 合并）；
-	* - 连续 'update' 合并到同一组，组内 steps 顺序就是发生顺序。
-	*/
-	static mergeCodeBlockSteps(codeBlockId, list, cursor) {
-		const groups = [];
-		let current = null;
-		const currentIndex = cursor - 1;
-		list.forEach((step, index) => {
-			const opType = History.detectOpType(step.oldContent, step.newContent);
-			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: "code-block",
-					id: codeBlockId,
-					opType,
-					steps: [{
-						step,
-						index,
-						applied,
-						isCurrent
-					}],
-					applied,
-					isCurrent
-				};
-				groups.push(current);
-			}
-		});
-		return groups;
-	}
-	static mergeDataSourceSteps(dataSourceId, list, cursor) {
-		const groups = [];
-		let current = null;
-		const currentIndex = cursor - 1;
-		list.forEach((step, index) => {
-			const opType = History.detectOpType(step.oldSchema, step.newSchema);
-			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: "data-source",
-					id: dataSourceId,
-					opType,
-					steps: [{
-						step,
-						index,
-						applied,
-						isCurrent
-					}],
-					applied,
-					isCurrent
-				};
-				groups.push(current);
-			}
-		});
-		return groups;
+//#region packages/editor/src/services/history.ts
+var canUsePluginMethods = { sync: [
+	"push",
+	"undo",
+	"redo"
+] };
+/** 各内置历史类型的默认展示名称（用于历史面板 tab / 分组标题等）。扩展类型可通过 registerStepType / setStepName 登记。 */
+var DEFAULT_STEP_NAMES = {
+	page: "页面",
+	codeBlock: "代码块",
+	dataSource: "数据源"
+};
+/** 各历史类型对应的分组 `kind`（展示用）：page→page，codeBlock→code-block，dataSource→data-source。扩展类型缺省回退到 stepType 本身。 */
+var STEP_TYPE_KIND = {
+	page: "page",
+	codeBlock: "code-block",
+	dataSource: "data-source"
+};
+/** 历史记录持久化快照的默认存储位置与结构版本。 */
+var DEFAULT_DB_NAME = "tmagic-editor";
+var DEFAULT_STORE_NAME = "history";
+var DEFAULT_KEY = "default";
+var PERSIST_VERSION = 3;
+var History = class extends BaseService {
+	state = reactive({
+		steps: {
+			page: {},
+			codeBlock: {},
+			dataSource: {}
+		},
+		stepNames: { ...DEFAULT_STEP_NAMES }
+	});
+	constructor() {
+		super([...canUsePluginMethods.sync.map((methodName) => ({
+			name: methodName,
+			isAsync: false
+		}))]);
 	}
 	/**
-	* 根据 old/new 是否为 null 推断 opType（与 push 时的约定一致）。
+	* 注册一个扩展历史类型，使其可与内置 `page` / `codeBlock` / `dataSource` 一样走统一的
+	* {@link push} / {@link undo} / {@link redo}（按 id 分栈、独立 undo/redo）。
+	*
+	* @param stepType 自定义历史类型标识（勿与内置类型重名）
+	* @param options.event push/undo/redo 后派发的事件名，缺省为 `${stepType}-history-change`
+	* @param options.name 历史面板中的展示名称（tab / 分组标题等），缺省回退到 stepType 本身
 	*/
-	static detectOpType(oldVal, newVal) {
-		if (oldVal === null && newVal !== null) return "add";
-		if (oldVal !== null && newVal === null) return "remove";
-		return "update";
+	registerStepType(stepType, options = {}) {
+		this.getStepBucket(stepType);
+		if (options.name !== void 0) this.state.stepNames[stepType] = options.name;
 	}
 	/**
-	* 把页面栈拆成若干 group：
-	* - 单节点的 'update' 按 targetId 与相邻同 targetId 的 update 合并到一个 group；
-	* - 'add' / 'remove' 始终独立成组（语义上是结构变更，不应被收纳进单节点修改组）；
-	* - 多节点 'update'（如批量改属性）也独立成组（无明确单一目标，避免误合并）。
+	* 读取指定历史类型的展示名称（用于历史面板 tab / 分组标题等）。
+	* 未登记名称时回退到 stepType 本身。
 	*/
-	static 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 = History.detectPageTargetId(step);
-			const targetName = History.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;
+	getStepName(stepType) {
+		return this.state.stepNames[stepType] ?? `${stepType}`;
 	}
 	/**
-	* 解析 StepValue 中的"目标节点 id"用于合并：
-	* - 单节点 update：取唯一一项 updatedItems 的节点 id；
-	* - 其它情形（多节点 update / add / remove）：返回 undefined，表示不参与合并。
+	* 设置指定历史类型的展示名称（用于历史面板 tab / 分组标题等）。
+	* 内置 `page` / `codeBlock` / `dataSource` 也可在此覆盖默认中文名。
 	*/
-	static detectPageTargetId(step) {
-		if (step.opType !== "update") return void 0;
-		const items = step.updatedItems;
-		if (items?.length !== 1) return void 0;
-		return items[0].newNode?.id ?? items[0].oldNode?.id;
-	}
-	/** 解析 StepValue 中的目标节点可读名（用于 UI 展示）。 */
-	static detectPageTargetName(step) {
-		if (step.opType === "update") {
-			const items = step.updatedItems;
-			if (items?.length === 1) {
-				const node = items[0].newNode || items[0].oldNode;
-				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 (step.nodes?.length === 1) {
-				const n = step.nodes[0];
-				return n.name || n.type || `${n.id}`;
-			}
-			return step.nodes?.length ? `${step.nodes.length} 个节点` : void 0;
-		}
-		if (step.opType === "remove") {
-			if (step.removedItems?.length === 1) {
-				const n = step.removedItems[0].node;
-				return n.name || n.type || `${n.id}`;
-			}
-			return step.removedItems?.length ? `${step.removedItems.length} 个节点` : void 0;
-		}
-	}
-	state = reactive({
-		pageSteps: {},
-		pageId: void 0,
-		canRedo: false,
-		canUndo: false,
-		codeBlockState: {},
-		dataSourceState: {}
-	});
-	constructor() {
-		super([]);
-		this.on("change", this.setCanUndoRedo);
+	setStepName(stepType, name) {
+		this.state.stepNames[stepType] = name;
 	}
 	reset() {
-		this.state.pageSteps = {};
-		this.state.codeBlockState = {};
-		this.state.dataSourceState = {};
-		this.resetPage();
-	}
-	resetPage() {
-		this.state.pageId = void 0;
-		this.state.canRedo = false;
-		this.state.canUndo = false;
-	}
-	changePage(page) {
-		if (!page) return;
-		this.state.pageId = page.id;
-		if (!this.state.pageSteps[this.state.pageId]) this.state.pageSteps[this.state.pageId] = new UndoRedo();
-		this.setCanUndoRedo();
-		this.emit("page-change", this.state.pageSteps[this.state.pageId]);
+		this.clearAllSteps();
 	}
 	resetState() {
-		this.state.pageId = void 0;
-		this.state.pageSteps = {};
-		this.state.canRedo = false;
-		this.state.canUndo = false;
-		this.state.codeBlockState = {};
-		this.state.dataSourceState = {};
+		this.clearAllSteps();
 	}
 	/**
-	* 把一条步骤推入指定页面的栈；不指定 pageId 时落到当前活动页。
+	* 为指定历史栈（默认 `page`，也适用于 codeBlock / dataSource / 扩展类型）种入一条「初始基线」记录。
 	*
-	* 跨页操作（例如 `moveToContainer` 把节点搬到其它页）必须显式传入 `pageId`，
-	* 否则会把记录错误地落到操作发起页 / 当前激活页，破坏目标页 / 源页的撤销栈语义。
-	*/
-	push(state, pageId) {
-		const undoRedo = this.getUndoRedo(pageId);
-		if (!undoRedo) return null;
-		undoRedo.pushElement(state);
-		if (pageId === void 0 || `${pageId}` === `${this.state.pageId}`) this.emit("change", state);
-		return state;
-	}
-	/**
-	* 推入一条代码块变更记录（与页面/节点完全无关），按 `codeBlockId` 维度独立一份 UndoRedo 栈。
+	* 该记录是一条 `opType: 'initial'` 的 step，作为对应栈 **index 0 的固定底线**：
+	* - 它是一条真实入栈的 step（随栈一起持久化），但被钉为撤销/回滚的下限——cursor 永不低于它，
+	*   因此不会被 undo / goto / revert 触达（详见 {@link undo} / {@link undoFloor}）；
+	* - 历史面板把它过滤出分组列表（见 {@link getHistoryGroups}），改由底部「初始」行展示。
+	*
+	* 仅当目标栈为空时种入（保证 initial 一定位于 index 0）；已存在 initial 底线时不重复种入。
 	*
-	* - 新增：oldContent = null，newContent = 新内容
-	* - 更新：oldContent / newContent 都为对应内容
-	* - 删除：newContent = null，oldContent = 删除前内容
-	* - `changeRecords` 来自 form 端，撤销/重做时若有则按 propPath 局部覆盖；缺省才退化为整内容替换。
-	* - 不直接驱动 codeBlockService，调用方负责实际写回。
+	* @param stepType 历史类型
+	* @param id       目标栈 id（page 为 pageId，其余类型为对应资源 id）
+	* @param options  基线展示信息（名称 / 描述 / 来源）
 	*/
-	pushCodeBlock(codeBlockId, payload) {
-		if (!codeBlockId) return null;
-		const step = {
-			id: codeBlockId,
-			oldContent: payload.oldContent ? cloneDeep(payload.oldContent) : null,
-			newContent: payload.newContent ? cloneDeep(payload.newContent) : null,
-			changeRecords: payload.changeRecords?.length ? cloneDeep(payload.changeRecords) : void 0,
-			historyDescription: payload.historyDescription
+	setMarker(stepType, id, options = {}) {
+		if (!this.isValidStackId(id)) return null;
+		const existing = this.getMarker(stepType, id);
+		if (existing) return existing;
+		const stack = getOrCreateStack(this.getStepBucket(stepType), id);
+		if (stack.getLength() > 0) return null;
+		const marker = {
+			uuid: guid(),
+			opType: "initial",
+			diff: [],
+			data: {
+				name: options.name || "",
+				id
+			},
+			extra: {
+				...options.extra || {},
+				...stepType === "page" ? {
+					selectedBefore: [],
+					selectedAfter: [],
+					modifiedNodeIds: /* @__PURE__ */ new Map()
+				} : {}
+			},
+			historyDescription: options.description || "未修改的初始状态",
+			timestamp: Date.now(),
+			...options.source ? { source: options.source } : {}
 		};
-		this.getCodeBlockUndoRedo(codeBlockId).pushElement(step);
-		this.emit("code-block-history-change", codeBlockId, step);
-		return step;
+		stack.pushElement(marker);
+		this.emit("marker-change", {
+			id,
+			marker,
+			stepType
+		});
+		return marker;
 	}
 	/**
-	* 推入一条数据源变更记录（与页面/节点完全无关），按 `dataSourceId` 维度独立一份 UndoRedo 栈。
-	* 行为同 pushCodeBlock（新增 oldSchema=null；删除 newSchema=null）。
+	* 读取指定历史栈的初始基线 step（栈 index 0 且 `opType: 'initial'`）；
+	* 不存在或 id 缺省时返回 undefined。
 	*/
-	pushDataSource(dataSourceId, payload) {
-		if (!dataSourceId) return null;
-		const step = {
-			id: dataSourceId,
-			oldSchema: payload.oldSchema ? cloneDeep(payload.oldSchema) : null,
-			newSchema: payload.newSchema ? cloneDeep(payload.newSchema) : null,
-			changeRecords: payload.changeRecords?.length ? cloneDeep(payload.changeRecords) : void 0,
-			historyDescription: payload.historyDescription
-		};
-		this.getDataSourceUndoRedo(dataSourceId).pushElement(step);
-		this.emit("data-source-history-change", dataSourceId, step);
+	getMarker(stepType, id) {
+		if (!this.isValidStackId(id)) return void 0;
+		const first = this.state.steps[stepType]?.[id]?.getElementList()[0];
+		return first?.opType === "initial" ? first : void 0;
+	}
+	push(stepType, step, id) {
+		if (!this.isValidStackId(id)) return null;
+		this.fillStepMeta(step);
+		getOrCreateStack(this.getStepBucket(stepType), id).pushElement(step);
+		this.emit("change", step, stepType, id);
 		return step;
 	}
-	/** 撤销指定代码块的最近一次变更。 */
-	undoCodeBlock(codeBlockId) {
-		const undoRedo = this.state.codeBlockState[codeBlockId];
+	undo(stepType, id) {
+		if (!this.isValidStackId(id)) return null;
+		const undoRedo = this.state.steps[stepType]?.[id];
 		if (!undoRedo) return null;
+		if (undoRedo.getCursor() <= undoFloor(undoRedo)) return null;
 		const step = undoRedo.undo();
-		if (step) this.emit("code-block-history-change", codeBlockId, step);
+		if (step) this.emit("change", step, stepType, id);
 		return step;
 	}
-	/** 重做指定代码块的下一次变更。 */
-	redoCodeBlock(codeBlockId) {
-		const undoRedo = this.state.codeBlockState[codeBlockId];
+	redo(stepType, id) {
+		if (!this.isValidStackId(id)) return null;
+		const undoRedo = this.state.steps[stepType]?.[id];
 		if (!undoRedo) return null;
 		const step = undoRedo.redo();
-		if (step) this.emit("code-block-history-change", codeBlockId, step);
+		if (step) this.emit("change", step, stepType, id);
 		return step;
 	}
-	/** 是否可对指定代码块撤销。 */
-	canUndoCodeBlock(codeBlockId) {
-		return this.state.codeBlockState[codeBlockId]?.canUndo() ?? false;
-	}
-	/** 是否可对指定代码块重做。 */
-	canRedoCodeBlock(codeBlockId) {
-		return this.state.codeBlockState[codeBlockId]?.canRedo() ?? false;
-	}
-	/** 撤销指定数据源的最近一次变更。 */
-	undoDataSource(dataSourceId) {
-		const undoRedo = this.state.dataSourceState[dataSourceId];
-		if (!undoRedo) return null;
-		const step = undoRedo.undo();
-		if (step) this.emit("data-source-history-change", dataSourceId, step);
-		return step;
-	}
-	/** 重做指定数据源的下一次变更。 */
-	redoDataSource(dataSourceId) {
-		const undoRedo = this.state.dataSourceState[dataSourceId];
-		if (!undoRedo) return null;
-		const step = undoRedo.redo();
-		if (step) this.emit("data-source-history-change", dataSourceId, step);
-		return step;
-	}
-	/** 是否可对指定数据源撤销。 */
-	canUndoDataSource(dataSourceId) {
-		return this.state.dataSourceState[dataSourceId]?.canUndo() ?? false;
+	/**
+	* 是否可对指定历史栈撤销（cursor 高于 initial 基线底线）。
+	* @param stepType 历史类型
+	* @param id       目标栈 id；缺省 / 无效时返回 false
+	*/
+	canUndo(stepType, id) {
+		if (!this.isValidStackId(id)) return false;
+		const undoRedo = this.state.steps[stepType]?.[id];
+		return undoRedo ? undoRedo.getCursor() > undoFloor(undoRedo) : false;
 	}
-	/** 是否可对指定数据源重做。 */
-	canRedoDataSource(dataSourceId) {
-		return this.state.dataSourceState[dataSourceId]?.canRedo() ?? false;
+	/**
+	* 是否可对指定历史栈重做。
+	* @param stepType 历史类型
+	* @param id       目标栈 id；缺省 / 无效时返回 false
+	*/
+	canRedo(stepType, id) {
+		if (!this.isValidStackId(id)) return false;
+		return this.state.steps[stepType]?.[id]?.canRedo() ?? false;
 	}
-	undo() {
-		const undoRedo = this.getUndoRedo();
-		if (!undoRedo) return null;
-		const state = undoRedo.undo();
-		this.emit("change", state);
-		return state;
+	/** 读取指定页面历史栈当前游标所在的 step（cursor - 1）；无则返回 null。 */
+	getCurrentPageStep(pageId) {
+		if (!this.isValidStackId(pageId)) return null;
+		return this.state.steps.page[pageId]?.getCurrentElement() ?? null;
 	}
-	redo() {
-		const undoRedo = this.getUndoRedo();
-		if (!undoRedo) return null;
-		const state = undoRedo.redo();
-		this.emit("change", state);
+	/**
+	* 用 `state` 替换指定页面栈当前游标所在的 step（并丢弃其后的重做尾部），游标不变。
+	* 用于「连续 set root 记录合并」等就地替换最新一条的场景；替换成功后派发 `change`。
+	*/
+	replaceCurrentStep(stepType, state, id) {
+		if (!this.isValidStackId(id)) return null;
+		const undoRedo = getOrCreateStack(this.getStepBucket(stepType), id);
+		this.fillStepMeta(state);
+		if (!undoRedo.replaceCurrentElement(state)) return null;
+		this.emit("change", state, stepType, id);
 		return state;
 	}
 	destroy() {
@@ -325,93 +199,121 @@ var history_default = new class History extends BaseService {
 		this.removeAllPlugins();
 	}
 	/**
-	* 取出当前活动页的历史步骤平铺列表（包含已应用 + 已撤销）。
-	* 列表按时间正序，最早一步在最前面。
-	* 通常 UI 应使用 `getPageHistoryGroups` 取已合并分组的版本；本方法仅为兼容/调试保留。
-	*/
-	getPageStepList(pageId) {
-		const targetPageId = pageId ?? this.state.pageId;
-		if (!targetPageId) return [];
-		const undoRedo = this.state.pageSteps[targetPageId];
-		if (!undoRedo) return [];
-		const list = undoRedo.getElementList();
-		const cursor = undoRedo.getCursor();
-		return list.map((step, index) => ({
-			step,
-			index,
-			applied: index < cursor
-		}));
-	}
-	/**
-	* 取出当前活动页的历史栈，按"目标节点"做相邻合并：
-	* - 连续修改同一节点（单节点 update）的多步合并为一个 group，组内可展开查看每步；
-	* - add / remove / 多节点 update 始终独立成组。
-	* 用于历史面板的"页面"tab 展示。
+	* 清空历史记录栈。统一入口，所有类型（page / codeBlock / dataSource / 扩展）行为一致：
+	* - 传入 `id`：仅清空 `stepType` 下该 id 对应的栈；
+	* - 缺省 `id`：清空 `stepType` 下的全部栈。
+	*
+	* 仅删除撤销/重做记录，不会改动 DSL / 代码块 / 数据源本身。清空时会**保留各栈原有的
+	* initial 基线**（文案 / 来源），无基线时清空成空栈。清空后派发 `clear`（签名 `(id, stepType)`）。
+	*
+	* @param stepType 历史类型
+	* @param id       目标栈 id；缺省表示清空该类型下全部栈
 	*/
-	getPageHistoryGroups(pageId) {
-		const targetPageId = pageId ?? this.state.pageId;
-		if (!targetPageId) return [];
-		const undoRedo = this.state.pageSteps[targetPageId];
-		if (!undoRedo) return [];
-		const list = undoRedo.getElementList();
-		if (!list.length) return [];
-		const cursor = undoRedo.getCursor();
-		return History.mergePageSteps(targetPageId, list, cursor);
+	clear(stepType, id) {
+		const bucket = this.state.steps[stepType];
+		if (!bucket) return;
+		if (this.isValidStackId(id)) this.clearStack(stepType, id);
+		else if (id === void 0) Object.keys(bucket).forEach((stackId) => this.clearStack(stepType, stackId));
+		else return;
+		this.emit("clear", {
+			id,
+			stepType
+		});
 	}
 	/**
-	* 取出全部代码块的历史栈，按 codeBlockId 分组。
-	* 同一栈内相邻、同 opType 且作用于同一 id 的多步会被合并为一个 group：
-	* - 这正是"代码块/数据源各自按 id 分栈"的天然表现，再叠加"连续修改同目标的相邻步骤合并展示"。
-	* - 合并后 group 暴露子步骤数组，UI 可展开查看每一步的 changeRecords。
-	* - applied 字段：组内最后一步是否处于已应用段。
+	* 标记历史记录为「已保存」（把对应栈当前游标所在的记录标为 `saved`）。统一入口：
+	* - 缺省 `id`：标记**全部类型、全部栈**（整份 DSL 落库场景），派发 `mark-saved` 且 `kind: 'all'`；
+	* - 传入 `id`：仅标记 `stepType` 下该 id 对应的栈，派发 `mark-saved` 且 `kind` 为 `stepType`。
+	*
+	* 同一栈内任意时刻最多只有一条记录为 `saved`；从 IndexedDB 恢复时游标会被定位到最近一条已保存记录之后。
+	*
+	* @param stepType 历史类型
+	* @param id       目标栈 id；缺省表示标记全部类型 / 全部栈
 	*/
-	getCodeBlockHistoryGroups() {
-		const groups = [];
-		Object.entries(this.state.codeBlockState).forEach(([id, undoRedo]) => {
-			if (!undoRedo) return;
-			const list = undoRedo.getElementList();
-			if (!list.length) return;
-			const cursor = undoRedo.getCursor();
-			groups.push(...History.mergeCodeBlockSteps(id, list, cursor));
+	markSaved(stepType, id) {
+		if (id === void 0) {
+			Object.values(this.state.steps).forEach((bucket) => Object.values(bucket).forEach(markStackSaved));
+			this.emit("mark-saved", { kind: "all" });
+			return;
+		}
+		if (!this.isValidStackId(id)) return;
+		markStackSaved(this.state.steps[stepType]?.[id]);
+		this.emit("mark-saved", {
+			kind: stepType,
+			id
 		});
-		return groups;
 	}
 	/**
-	* 读取指定页面历史栈的当前游标（已应用步骤数量）。不传则取当前活动页。
-	* 没有对应栈时返回 0。
+	* 派发「页面 / 页面片结构变更」事件（`page-structure-change`）。
+	*
+	* 常规 `editorService.add` / `remove` 页面节点不会写入 `page` 历史栈（见 editor.add / remove 中
+	* 对 isPageOrFragment 的分支），因此不会产生任何 historyService 事件。该方法用于在这些
+	* 场景（以及 setRoot 整体替换 DSL 增删页面）下，向外统一通知页面结构的增删变化，供业务方感知。
+	*
+	* 一次操作涉及多个页面时，调用方应把本次增删的页面**合并为一个 change 一次性传入**，
+	* 使一次操作只派发一个事件；`add` / `remove` 分别为本次新增与删除的页面列表（其一可为空数组）。
+	*
+	* @param change 本次结构变更：{ add: 新增的页面列表, remove: 删除的页面列表 }
 	*/
-	getPageCursor(pageId) {
-		const targetPageId = pageId ?? this.state.pageId;
-		if (!targetPageId) return 0;
-		return this.state.pageSteps[targetPageId]?.getCursor() ?? 0;
-	}
-	/** 读取指定代码块历史栈的当前游标。 */
-	getCodeBlockCursor(codeBlockId) {
-		return this.state.codeBlockState[codeBlockId]?.getCursor() ?? 0;
-	}
-	/** 读取指定数据源历史栈的当前游标。 */
-	getDataSourceCursor(dataSourceId) {
-		return this.state.dataSourceState[dataSourceId]?.getCursor() ?? 0;
+	notifyPageStructureChange(change) {
+		if (!change.add.length && !change.remove.length) return;
+		this.emit("page-structure-change", change);
 	}
 	/**
-	* 取出指定代码块历史栈的平铺步骤列表（含 applied 标记）。供 revert 等按 index 索引步骤使用。
+	* 把当前内存中的全部历史栈（页面 / 代码块 / 数据源 / 扩展类型）序列化后写入本地 IndexedDB。
+	*
+	* - 每个 UndoRedo 栈连同其游标、容量一并保存，恢复后可继续 undo/redo；
+	* - `key` 用于区分不同活动页 / 项目（同一 store 下可保存多份快照），缺省为 `default`；
+	* - 返回写入成功的快照对象，便于调用方记录 savedAt 等信息；
+	* - 不支持 IndexedDB 的环境（如 SSR）会 reject。
 	*/
-	getCodeBlockStepList(codeBlockId) {
-		const undoRedo = this.state.codeBlockState[codeBlockId];
-		if (!undoRedo) return [];
-		const list = undoRedo.getElementList();
-		const cursor = undoRedo.getCursor();
-		return list.map((step, index) => ({
-			step,
-			index,
-			applied: index < cursor
-		}));
+	async saveToIndexedDB(options = {}) {
+		const { dbName = DEFAULT_DB_NAME, storeName = DEFAULT_STORE_NAME, key = DEFAULT_KEY, appId } = options;
+		const steps = {
+			page: {},
+			codeBlock: {},
+			dataSource: {}
+		};
+		Object.entries(this.state.steps).forEach(([stepType, bucket]) => {
+			steps[stepType] = serializeStacks(bucket);
+		});
+		const snapshot = {
+			version: PERSIST_VERSION,
+			steps,
+			savedAt: Date.now()
+		};
+		await idbSet(this.resolveDbName(dbName, appId), storeName, key, snapshot);
+		this.emit("save-to-indexed-db", snapshot);
+		return snapshot;
 	}
 	/**
-	* 取出指定数据源历史栈的平铺步骤列表（含 applied 标记）。供 revert 等按 index 索引步骤使用。
+	* 从本地 IndexedDB 读取此前保存的历史快照并重建全部撤销/重做栈。
+	*
+	* - 读取到的每个栈都会经 {@link UndoRedo.fromSerialized} 还原（含游标），随后可直接 undo/redo；
+	* - 会整体覆盖当前内存中的历史状态（活动页由 editorService 维护，不在此恢复）；
+	* - 找不到对应记录时返回 null，且不改动当前状态；
+	* - 不支持 IndexedDB 的环境（如 SSR）会 reject。
 	*/
-	getDataSourceStepList(dataSourceId) {
-		const undoRedo = this.state.dataSourceState[dataSourceId];
+	async restoreFromIndexedDB(options = {}) {
+		const { dbName = DEFAULT_DB_NAME, storeName = DEFAULT_STORE_NAME, key = DEFAULT_KEY, appId } = options;
+		const snapshot = await idbGet(this.resolveDbName(dbName, appId), storeName, key);
+		if (!snapshot) return null;
+		const parseDSL = getEditorConfig("parseDSL");
+		const steps = {
+			page: {},
+			codeBlock: {},
+			dataSource: {}
+		};
+		Object.entries(snapshot.steps).forEach(([stepType, bucket]) => {
+			steps[stepType] = deserializeStacks(bucket, parseDSL);
+		});
+		this.state.steps = steps;
+		this.emit("restore-from-indexed-db", snapshot);
+		return snapshot;
+	}
+	getStepList(stepType, id) {
+		if (!this.isValidStackId(id)) return [];
+		const undoRedo = this.state.steps[stepType]?.[id];
 		if (!undoRedo) return [];
 		const list = undoRedo.getElementList();
 		const cursor = undoRedo.getCursor();
@@ -421,51 +323,113 @@ var history_default = new class History extends BaseService {
 			applied: index < cursor
 		}));
 	}
+	getHistoryGroups(stepType, id) {
+		const bucket = this.state.steps[stepType];
+		if (!bucket) return [];
+		const kind = STEP_TYPE_KIND[stepType] ?? stepType;
+		const collect = (stackId) => {
+			const undoRedo = bucket[stackId];
+			if (!undoRedo) return [];
+			const list = undoRedo.getElementList();
+			if (!list.length) return [];
+			return mergeSteps(kind, stackId, list, undoRedo.getCursor()).filter((group) => group.opType !== "initial");
+		};
+		if (this.isValidStackId(id)) return collect(id);
+		return Object.keys(bucket).flatMap((stackId) => collect(stackId));
+	}
 	/**
-	* 取出全部数据源的历史栈，按 dataSourceId 分组。同上。
+	* 读取指定历史栈的当前游标（已应用步骤数量）。统一入口，替代旧的
+	* `getPageCursor` / `getCodeBlockCursor` / `getDataSourceCursor`。
+	* - `id` 缺省或非法、或对应栈不存在时返回 0；
+	* - `stepType` 支持 `page` / `codeBlock` / `dataSource` / 扩展类型。
 	*/
-	getDataSourceHistoryGroups() {
-		const groups = [];
-		Object.entries(this.state.dataSourceState).forEach(([id, undoRedo]) => {
-			if (!undoRedo) return;
-			const list = undoRedo.getElementList();
-			if (!list.length) return;
-			const cursor = undoRedo.getCursor();
-			groups.push(...History.mergeDataSourceSteps(id, list, cursor));
-		});
-		return groups;
+	getCursor(stepType, id) {
+		if (!this.isValidStackId(id)) return 0;
+		return this.state.steps[stepType]?.[id]?.getCursor() ?? 0;
 	}
 	/**
-	* 取出指定页面的栈；不传 pageId 时按当前活动页取。
+	* 按历史记录 uuid 在指定历史类型的栈中查找其所属 id 与索引，统一入口，替代旧的
+	* `getPageStepIndexByUuid` / `findCodeBlockStepLocationByUuid` / `findDataSourceStepLocationByUuid`。
+	*
+	* - 传入 `id`：仅在该 id 对应的单个栈中查找（如页面历史按活动页查看，传入 pageId）；
+	* - 缺省 `id`：遍历该类型下全部栈查找（代码块 / 数据源等按全部资源分桶的场景）。
 	*
-	* 跨页 push 时如果目标页的栈尚不存在（用户从未进入过该页），会按需创建一条空栈，
-	* 这样切到目标页时 Ctrl+Z 也能撤回该步骤。
+	* 找不到时返回 null。供「按 uuid 回滚」等需要把 uuid 映射回 (id, index) 的场景使用。
+	*
+	* @param stepType 历史类型
+	* @param uuid     目标历史记录的 uuid
+	* @param id       目标栈 id；缺省表示遍历该类型下全部栈
 	*/
-	getUndoRedo(pageId) {
-		const targetPageId = pageId ?? this.state.pageId;
-		if (!targetPageId) return null;
-		if (!this.state.pageSteps[targetPageId]) this.state.pageSteps[targetPageId] = new UndoRedo();
-		return this.state.pageSteps[targetPageId];
+	findStepLocationByUuid(stepType, uuid, id) {
+		if (!uuid) return null;
+		const bucket = this.state.steps[stepType];
+		if (!bucket) return null;
+		if (this.isValidStackId(id)) {
+			const index = this.getStepList(stepType, id).findIndex((entry) => entry.step.uuid === uuid);
+			return index >= 0 ? {
+				id,
+				index
+			} : null;
+		}
+		for (const stackId of Object.keys(bucket)) {
+			const index = this.getStepList(stepType, stackId).findIndex((entry) => entry.step.uuid === uuid);
+			if (index >= 0) return {
+				id: stackId,
+				index
+			};
+		}
+		return null;
 	}
-	setCanUndoRedo() {
-		const undoRedo = this.getUndoRedo();
-		this.state.canRedo = undoRedo?.canRedo() || false;
-		this.state.canUndo = undoRedo?.canUndo() || false;
+	usePlugin(options) {
+		super.usePlugin(options);
+	}
+	emit(eventName, ...args) {
+		return super.emit(eventName, ...args);
 	}
 	/**
-	* 按 id 获取（或创建）指定代码块的 UndoRedo 栈。
+	* 取出指定历史类型的栈桶（`Record<id, UndoRedo>`）；不存在时按需创建空桶，
+	* 从而支持通过 {@link registerStepType} 或首次 push 动态扩展历史类型。
 	*/
-	getCodeBlockUndoRedo(codeBlockId) {
-		if (!this.state.codeBlockState[codeBlockId]) this.state.codeBlockState[codeBlockId] = new UndoRedo();
-		return this.state.codeBlockState[codeBlockId];
+	getStepBucket(stepType) {
+		if (!this.state.steps[stepType]) this.state.steps[stepType] = {};
+		return this.state.steps[stepType];
+	}
+	/**
+	* 清空单个历史栈并按需重建其 initial 基线（保留原基线的文案 / 来源）。
+	*/
+	clearStack(stepType, id) {
+		const marker = this.getMarker(stepType, id);
+		this.getStepBucket(stepType)[id] = new UndoRedo();
+		if (marker) this.setMarker(stepType, id, {
+			name: marker.data?.name,
+			description: marker.historyDescription,
+			source: marker.source
+		});
+	}
+	/** 入栈前补全 step 的 uuid / timestamp（调用方未指定时）。 */
+	fillStepMeta(step) {
+		if (step.uuid === void 0) step.uuid = guid();
+		if (step.timestamp === void 0) step.timestamp = Date.now();
+	}
+	/** 校验「按 id 分栈」类型（codeBlock / dataSource / 扩展）的 id 是否有效。 */
+	isValidStackId(id) {
+		return id !== void 0 && id !== null && `${id}` !== "";
+	}
+	/** 清空全部历史栈内容（保留已注册的类型键，使扩展类型在 reset 后仍可用）。 */
+	clearAllSteps() {
+		Object.keys(this.state.steps).forEach((stepType) => {
+			this.state.steps[stepType] = {};
+		});
 	}
 	/**
-	* 按 id 获取（或创建）指定数据源的 UndoRedo 栈。
+	* 把基础 dbName 与当前 DSL（root app）的 id 拼成最终库名，实现不同应用历史隔离。
+	* 取不到 app id（如尚未加载 DSL）时退回基础 dbName。
 	*/
-	getDataSourceUndoRedo(dataSourceId) {
-		if (!this.state.dataSourceState[dataSourceId]) this.state.dataSourceState[dataSourceId] = new UndoRedo();
-		return this.state.dataSourceState[dataSourceId];
+	resolveDbName(dbName, appId) {
+		const resolvedAppId = appId ?? editor_default.get("root")?.id;
+		return resolvedAppId ? `${dbName}-${resolvedAppId}` : dbName;
 	}
-}();
+};
+var history_default = new History();
 //#endregion
 export { history_default as default };