@hmg-report-editor/core 1.0.0

package/dist/editor/ReportEditorCore.d.ts

@@ -0,0 +1,137 @@
+/** 报告编辑器 core facade，封装 Tiptap 实例和业务命令。 */
+import { Editor } from '@tiptap/core';
+import type { HtmlOutputMode, ReportControlAttrs, ReportControlSnapshot, ReportDocument, ReportEditorInstance, ReportEditorOptions, ReportPageBreakSnapshot, ReportPlainTextOptions, ReportTemplate, StructuredFieldValue } from '../types/index.js';
+/** 将模板、序列化、选择、编号和控件身份服务组合成统一编辑器实例。 */
+export declare class ReportEditorCore implements ReportEditorInstance {
+    private readonly options;
+    private readonly editor;
+    private readonly registry;
+    private readonly errors;
+    private readonly serializer;
+    private readonly templateEngine;
+    private readonly selectionManager;
+    private readonly identity;
+    private readonly pageBreakIdentity;
+    private readonly pasteSanitizer;
+    private readonly numberingService;
+    private readonly editorId;
+    private readonly controlPlugins;
+    private readonly controlPluginContext;
+    private readonly documentVersion;
+    private controlSnapshots;
+    private controlSnapshotsDirty;
+    private currentOperationBatchId;
+    private initializing;
+    /** 初始化 Tiptap 编辑器并注入报告扩展和回调。 */
+    constructor(options?: ReportEditorOptions);
+    /** 返回底层 Tiptap editor，供高级集成场景直接调用。 */
+    getTiptapEditor(): Editor;
+    /** 将焦点移动到编辑器。 */
+    focus(): void;
+    /** 销毁底层编辑器实例并释放事件监听。 */
+    destroy(): void;
+    /** 执行当前编辑器的撤销命令。 */
+    undo(): boolean;
+    /** 执行当前编辑器的重做命令。 */
+    redo(): boolean;
+    /** 导出报告 JSON 文档。 */
+    getJSON(): ReportDocument;
+    /** 按指定模式导出报告 HTML。 */
+    getHTML(mode?: HtmlOutputMode): string;
+    /** 导出报告纯文本内容。 */
+    getPlainText(options?: ReportPlainTextOptions): string;
+    /** 用报告 JSON 或 HTML 字符串替换当前内容。 */
+    setContent(content: ReportDocument | string): void;
+    /** 清空当前内容并保留编辑器文档版本。 */
+    clearContent(): void;
+    /** 将模板替换为当前文档内容。 */
+    applyTemplate(template: ReportTemplate): boolean;
+    /** 将模板追加到当前选区之后，并在成功后把选区放到新增内容末端。 */
+    appendTemplate(template: ReportTemplate): boolean;
+    /** 插入已注册的结构化控件节点。 */
+    insertControl(nodeType: string, attrs: ReportControlAttrs): boolean;
+    /** 按 controlId 更新单个控件的属性。 */
+    updateControlAttrs(controlId: string, attrs: Partial<ReportControlAttrs>): boolean;
+    /** 返回编辑器实例 ID。 */
+    getEditorId(): string;
+    /** 返回当前文档中的结构化控件快照。 */
+    getControls(): ReportControlSnapshot[];
+    /** 按 controlId 返回结构化控件快照。 */
+    getControl(controlId: string): ReportControlSnapshot | undefined;
+    /** 按 controlId 更新单个控件的业务值。 */
+    updateControlValue(controlId: string, value: StructuredFieldValue): boolean;
+    /** 按 fieldName 批量更新所有同名控件的业务值。 */
+    updateControlValueByFieldName(fieldName: string, value: StructuredFieldValue): boolean;
+    /** 在当前有效编辑位置插入手动分页符。 */
+    insertPageBreak(): boolean;
+    /** 删除指定 ID 或当前选中的手动分页符。 */
+    deletePageBreak(id?: string): boolean;
+    /** 返回当前文档中的分页符 ID 和位置。 */
+    getPageBreaks(): ReportPageBreakSnapshot[];
+    /** 切换当前段落在预览和打印模式下的隐藏状态。 */
+    toggleHiddenParagraph(): boolean;
+    /** 明确设置当前段落隐藏状态。 */
+    setParagraphHidden(hidden: boolean): boolean;
+    /** 按编号块索引移动块并重新计算自动编号。 */
+    moveNumberedBlock(fromIndex: number, toIndex: number): boolean;
+    /** 切换编辑器可编辑状态。 */
+    setEditable(editable: boolean): void;
+    /** Tiptap transaction 后同步控件生命周期插件。 */
+    private readonly handleControlTransaction;
+    /** 创建插件上下文。 */
+    private createControlPluginContext;
+    /** 初始化插件并注册初始文档中的控件。 */
+    private initializeControlPlugins;
+    /** 销毁插件并反注册当前控件。 */
+    private destroyControlPlugins;
+    /** 对比当前文档和上次快照，派发控件生命周期变更。 */
+    private syncControlPlugins;
+    /** Updates snapshots for validated attrs-only transactions without rescanning the document. */
+    private syncChangedControlSnapshots;
+    /** Ensures public control snapshot reads observe the current document state. */
+    private ensureControlSnapshots;
+    /** Collects the structured control snapshots in the current document. */
+    private collectControlSnapshots;
+    /** 判断规则相关元数据是否发生变化。 */
+    private isSameControlMetadata;
+    /** 捕获插件异常，避免插件破坏编辑器事务。 */
+    private notifyControlPlugin;
+    /** 在一次编辑器操作内复用同一批次 ID。 */
+    private runWithOperationBatch;
+    /** Separates high-level content operations from adjacent local ProseMirror history events. */
+    private closeLocalHistoryEvent;
+    /** 从插件读取外层共享批次。 */
+    private getPluginBatchId;
+    /** 为当前操作创建批次号。 */
+    private createOperationBatchId;
+    /** 创建编辑器实例 ID。 */
+    private createEditorId;
+    /** 比较普通值或 JSON 兼容对象是否一致。 */
+    private isSameValue;
+    /** 解析初始化内容，优先使用显式 content，其次使用模板。 */
+    private resolveInitialContent;
+    /** 解析初始化内容，失败时降级为空文档。 */
+    private resolveInitialTiptapContent;
+    /** 将输入内容解析为严格校验后的 Tiptap JSON。 */
+    private resolveTiptapContent;
+    /** 归一化传入文档并修复控件实例 ID。 */
+    private normalizeContent;
+    /** 将 HTML 输入解析为报告文档，随后仍走统一文档校验。 */
+    private parseHTMLContent;
+    /** 将输入校验错误派发给业务方。 */
+    private reportContentError;
+    /** 初始化事务只更新最终文档，不得提前派发对外 change。 */
+    private handleEditorUpdate;
+    /** 向外派发同步后的 JSON、HTML 和 Tiptap 实例。 */
+    private emitChange;
+    /** 阻止只读状态下的变更命令。 */
+    private ensureEditable;
+    /** 调用节点描述符上的属性校验逻辑。 */
+    private validateControlAttrs;
+    /** 在文档树中按 controlId 查找控件并更新节点属性。 */
+    private updateNodeAttrsByControlId;
+    /** 在文档树中按 fieldName 查找控件并批量更新节点属性。 */
+    private updateNodeAttrsByFieldName;
+    /** Checks whether an attrs update preserves the identity invariants needed by the fast path. */
+    private isStableControlIdentity;
+}

package/dist/editor/createReportEditor.d.ts

@@ -0,0 +1,3 @@
+import type { ReportEditorInstance, ReportEditorOptions } from '../types/index.js';
+/** 根据配置创建一个报告编辑器 facade。 */
+export declare function createReportEditor(options?: ReportEditorOptions): ReportEditorInstance;

package/dist/extensions/DropdownFieldNode.d.ts

@@ -0,0 +1,15 @@
+import { Node } from '@tiptap/core';
+import type { DropdownFieldAttrs } from '../types/index.js';
+import { type ReportControlShortcutRuntime } from '../plugins/ControlShortcuts.js';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        dropdownField: {
+            insertDropdownField: (attrs: DropdownFieldAttrs) => ReturnType;
+        };
+    }
+}
+export type DropdownFieldNodeOptions = {
+    controlShortcutRuntime: ReportControlShortcutRuntime;
+};
+/** Tiptap 下拉控件节点定义。 */
+export declare const DropdownFieldNode: Node<DropdownFieldNodeOptions, any>;

package/dist/extensions/FontSizeExtension.d.ts

@@ -0,0 +1,11 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        fontSize: {
+            setFontSize: (fontSize: string) => ReturnType;
+            unsetFontSize: () => ReturnType;
+        };
+    }
+}
+/** Tiptap 字号扩展，将 fontSize 挂到 textStyle mark。 */
+export declare const FontSizeExtension: Extension<any, any>;

package/dist/extensions/HiddenParagraphExtension.d.ts

@@ -0,0 +1,11 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        hiddenParagraph: {
+            toggleHiddenParagraph: () => ReturnType;
+            setParagraphHidden: (hidden: boolean) => ReturnType;
+        };
+    }
+}
+/** Tiptap 隐藏段落扩展，支持预览和打印时过滤段落。 */
+export declare const HiddenParagraphExtension: Extension<any, any>;

package/dist/extensions/IndentationExtension.d.ts

@@ -0,0 +1,13 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        indentation: {
+            increaseIndent: () => ReturnType;
+            decreaseIndent: () => ReturnType;
+            setIndent: (value: number) => ReturnType;
+        };
+    }
+}
+/** 创建可配置目标节点的缩进扩展。 */
+export declare function createIndentationExtension(targets?: string[]): Extension<any, any>;
+export declare const IndentationExtension: Extension<any, any>;

package/dist/extensions/LineHeightExtension.d.ts

@@ -0,0 +1,12 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        lineHeight: {
+            setLineHeight: (value: string) => ReturnType;
+            unsetLineHeight: () => ReturnType;
+        };
+    }
+}
+/** 创建可配置目标节点的行高扩展。 */
+export declare function createLineHeightExtension(targets?: string[]): Extension<any, any>;
+export declare const LineHeightExtension: Extension<any, any>;

package/dist/extensions/PageBreakNode.d.ts

@@ -0,0 +1,11 @@
+import { Node } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        pageBreak: {
+            insertPageBreak: () => ReturnType;
+            deletePageBreak: (id?: string) => ReturnType;
+        };
+    }
+}
+/** Tiptap 手动分页符节点。 */
+export declare const PageBreakNode: Node<any, any>;

package/dist/extensions/ReportNumberedBlockNode.d.ts

@@ -0,0 +1,10 @@
+import { Node } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        reportNumberedBlock: {
+            insertNumberedBlock: (text?: string) => ReturnType;
+        };
+    }
+}
+/** Tiptap 报告编号块节点定义。 */
+export declare const ReportNumberedBlockNode: Node<any, any>;

package/dist/extensions/StructuredFieldNode.d.ts

@@ -0,0 +1,15 @@
+import { Node } from '@tiptap/core';
+import type { StructuredFieldAttrs } from '../types/index.js';
+import { type ReportControlShortcutRuntime } from '../plugins/ControlShortcuts.js';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        structuredField: {
+            insertStructuredField: (attrs: StructuredFieldAttrs) => ReturnType;
+        };
+    }
+}
+export type StructuredFieldNodeOptions = {
+    controlShortcutRuntime: ReportControlShortcutRuntime;
+};
+/** Tiptap 结构化输入控件节点定义。 */
+export declare const StructuredFieldNode: Node<StructuredFieldNodeOptions, any>;

package/dist/extensions/TextColorExtension.d.ts

@@ -0,0 +1,11 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        textColor: {
+            setTextColor: (color: string) => ReturnType;
+            unsetTextColor: () => ReturnType;
+        };
+    }
+}
+/** Tiptap 文字颜色扩展，将 color 挂到 textStyle mark。 */
+export declare const TextColorExtension: Extension<any, any>;

package/dist/extensions/VisibilityGroupMark.d.ts

@@ -0,0 +1,6 @@
+import { Mark } from '@tiptap/core';
+/**
+ * 运行时条件隐藏组使用 mark 表达，使段落仍保持平坦 inline 结构，
+ * 从而避免容器节点对光标、换行和输入法行为的干扰。
+ */
+export declare const VisibilityGroupMark: Mark<any, any>;

package/dist/extensions/index.d.ts

@@ -0,0 +1,29 @@
+import type { Extensions } from '@tiptap/core';
+import { DropdownFieldNode } from './DropdownFieldNode.js';
+import { FontSizeExtension } from './FontSizeExtension.js';
+import { HiddenParagraphExtension } from './HiddenParagraphExtension.js';
+import { IndentationExtension } from './IndentationExtension.js';
+import { LineHeightExtension } from './LineHeightExtension.js';
+import { PageBreakNode } from './PageBreakNode.js';
+import { ReportNumberedBlockNode } from './ReportNumberedBlockNode.js';
+import { StructuredFieldNode } from './StructuredFieldNode.js';
+import { VisibilityGroupMark } from './VisibilityGroupMark.js';
+import { type InvalidControlAttrsHandler, type InvalidVisibilityGroupHandler } from '../plugins/PasteSanitizer.js';
+import type { ReportEditorGroupManager } from '../group/ReportEditorGroupManager.js';
+import type { ReportControlShortcutOptions, ReportFeatureRegistry } from '../types/index.js';
+/** 根据 feature 注册表创建报告编辑器所需的 Tiptap 扩展集合。 */
+export declare class ReportExtensionFactory {
+    private readonly registry;
+    private readonly controlShortcuts?;
+    private readonly editorGroup?;
+    private readonly getCurrentBatchId?;
+    private readonly onInvalidControlAttrs?;
+    private readonly onInvalidVisibilityGroup?;
+    /** 绑定 feature 注册表、快捷键配置和编辑器分组。 */
+    constructor(registry?: ReportFeatureRegistry, controlShortcuts?: ReportControlShortcutOptions | undefined, editorGroup?: ReportEditorGroupManager | undefined, getCurrentBatchId?: (() => string | undefined) | undefined, onInvalidControlAttrs?: InvalidControlAttrsHandler | undefined, onInvalidVisibilityGroup?: InvalidVisibilityGroupHandler | undefined);
+    /** 创建包含内置、业务扩展和运行时插件的扩展数组。 */
+    create(): Extensions;
+    /** 创建默认配置下的扩展数组。 */
+    createDefault(): Extensions;
+}
+export { DropdownFieldNode, FontSizeExtension, HiddenParagraphExtension, IndentationExtension, LineHeightExtension, PageBreakNode, ReportNumberedBlockNode, StructuredFieldNode, VisibilityGroupMark };

package/dist/group/ReportEditorGroupManager.d.ts

@@ -0,0 +1,45 @@
+import type { ReportEditorInstance } from '../types/index.js';
+/** 编辑器分组中的单个注册项。 */
+export type ReportEditorGroupEntry = {
+    editorId: string;
+    editor: ReportEditorInstance;
+};
+/** 编辑器分组状态变更 payload。 */
+export type ReportEditorGroupChangePayload = {
+    editorIds: string[];
+    activeEditorId?: string;
+};
+/** 编辑器分组管理器配置。 */
+export type ReportEditorGroupManagerOptions = {
+    onChange?: (payload: ReportEditorGroupChangePayload) => void;
+};
+/** 管理多个编辑器实例及当前活跃编辑器。 */
+export declare class ReportEditorGroupManager {
+    private readonly options;
+    private readonly editors;
+    private activeEditorId;
+    /** 创建编辑器分组管理器。 */
+    constructor(options?: ReportEditorGroupManagerOptions);
+    /** 注册编辑器并将其设为活跃编辑器。 */
+    register(editorId: string, editor: ReportEditorInstance): void;
+    /** 注销编辑器并清理活跃状态。 */
+    unregister(editorId: string): void;
+    /** 判断指定编辑器是否已注册。 */
+    has(editorId: string): boolean;
+    /** 按 ID 获取编辑器实例。 */
+    get(editorId: string): ReportEditorInstance | undefined;
+    /** 返回所有注册编辑器条目。 */
+    entries(): ReportEditorGroupEntry[];
+    /** 返回所有注册编辑器 ID。 */
+    getEditorIds(): string[];
+    /** 返回所有编辑器根 DOM，用于限定快捷键导航范围。 */
+    getEditorElements(): HTMLElement[];
+    /** 设置当前活跃编辑器。 */
+    setActiveEditor(editorId: string): boolean;
+    /** 获取当前活跃编辑器 ID。 */
+    getActiveEditorId(): string | undefined;
+    /** 获取当前分组状态快照。 */
+    getState(): ReportEditorGroupChangePayload;
+    /** 派发分组状态变化。 */
+    private emitChange;
+}

package/dist/history/SharedHistoryManager.d.ts

@@ -0,0 +1,96 @@
+import type { ReportEditorInstance, SharedHistoryChangePayload, SharedHistoryEntry, SharedHistoryManagerOptions } from '../types/index.js';
+import { ReportEditorGroupManager } from '../group/ReportEditorGroupManager.js';
+type SharedHistoryEntryInput = Omit<SharedHistoryEntry, 'timestamp'> & {
+    timestamp?: number;
+};
+type SynchronousResult<T> = T extends PromiseLike<unknown> ? never : T;
+/** Maintains shared undo/redo history across multiple editors. */
+export declare class SharedHistoryManager {
+    private readonly options;
+    private static readonly DEFAULT_MAX_DEPTH;
+    private static readonly MAX_DEPTH_LIMIT;
+    private readonly editorGroup;
+    private readonly registeredEditors;
+    private readonly undoStack;
+    private readonly redoStack;
+    private readonly maxDepth;
+    private isCaptureSuppressed;
+    private readonly pendingCaptureEditorIds;
+    private pendingCaptureActiveEditorIdBefore?;
+    private pendingCaptureScheduled;
+    private pendingCaptureToken;
+    /** Creates a shared history manager and initializes its editor group. */
+    constructor(options?: SharedHistoryManagerOptions);
+    /** Registers an editor and stores its initial document snapshot. */
+    register(editorId: string, editor: ReportEditorInstance): void;
+    /** Unregisters an editor and removes its history entries. */
+    unregister(editorId: string): void;
+    /** Sets the active editor for shared history operations. */
+    setActiveEditor(editorId: string): boolean;
+    /** Returns the editor group used by shared history. */
+    getEditorGroup(): ReportEditorGroupManager;
+    /** Binds editor events so content changes are captured automatically. */
+    track(editorId: string, editor: ReportEditorInstance): () => void;
+    /** Captures the current content change for one registered editor. */
+    capture(editorId: string, label?: string): boolean;
+    /** Wraps one editor operation and records one shared history item. */
+    run<T>(editorId: string, operation: () => SynchronousResult<T>, label?: string): boolean;
+    /** Wraps a multi-editor operation and records it as one undo/redo item. */
+    runBatch<T>(editorIds: Iterable<string>, operation: () => SynchronousResult<T>, label?: string): boolean;
+    /** Manually records a single-editor shared history entry. */
+    record(entry: SharedHistoryEntryInput): boolean;
+    /** Undoes the latest shared history item. */
+    undo(): boolean;
+    /** Redoes the latest undone shared history item. */
+    redo(): boolean;
+    /** Clears all history or only the entries associated with one editor. */
+    clear(editorId?: string): void;
+    /** Returns whether undo is currently available. */
+    canUndo(): boolean;
+    /** Returns whether redo is currently available. */
+    canRedo(): boolean;
+    /** Returns the undo stack depth. */
+    getUndoDepth(): number;
+    /** Returns the redo stack depth. */
+    getRedoDepth(): number;
+    /** Returns the current active editor ID. */
+    getActiveEditorId(): string | undefined;
+    /** Returns a snapshot of shared history state. */
+    getState(): SharedHistoryChangePayload;
+    /** Coalesces synchronous tracked updates, including cross-editor plugin effects, into one history item. */
+    private queueCapture;
+    /** Flushes one event-loop turn of automatically tracked editor updates. */
+    private flushPendingCaptures;
+    /** Captures the current snapshot of every registered editor. */
+    private snapshotAllRegisteredEditors;
+    /** Builds changed entries and synchronizes every registered last snapshot after an operation. */
+    private collectChangedEntries;
+    /** Stores a single changed editor directly or promotes synchronous multi-editor effects to a batch. */
+    private pushOperationEntries;
+    private pushSingleEntry;
+    private pushBatchEntry;
+    private restore;
+    private restoreSingle;
+    private restoreBatch;
+    /** Notifies consumers only after documents and history stacks are fully committed. */
+    private notifyRestore;
+    private collectRegisteredTargets;
+    private setActiveEditorIfAvailable;
+    private removeEntriesForEditor;
+    private removeFromStack;
+    private trimStack;
+    private emitChange;
+    private createStatePayload;
+    /** Checks whether the latest automatically flushed item already contains a manual record. */
+    private latestEntryMatches;
+    /** Makes the next tracked update start from the editor's actual current document. */
+    private synchronizeRegisteredSnapshot;
+    /** Synchronizes snapshots for editors changed synchronously as a side effect of a restore. */
+    private synchronizeRegisteredSnapshots;
+    private snapshotFromEditor;
+    private createSnapshot;
+    private cloneSnapshotDocument;
+    private isSameSnapshot;
+    private toPublicEntry;
+}
+export {};

package/dist/identity/ControlIdentityService.d.ts

@@ -0,0 +1,48 @@
+import { Slice, type Node as ProseMirrorNode } from '@tiptap/pm/model';
+import type { ReportControlAttrs, ReportDocument, ReportFeatureRegistry } from '../types/index.js';
+/** 控件身份修复时需要写回的位置和新 ID。 */
+export type ControlIdentityUpdate = {
+    pos: number;
+    controlId: string;
+    batchId: string;
+};
+/** 控件身份服务，确保每个控件实例都有唯一 controlId。 */
+export declare class ControlIdentityService {
+    private readonly registry;
+    /** 绑定 feature 注册表以识别控件节点。 */
+    constructor(registry?: ReportFeatureRegistry);
+    /** 创建不与已有集合冲突的新 controlId。 */
+    createId(existing?: Set<string>): string;
+    /** 创建新的控件批次 ID。 */
+    createBatchId(): string;
+    /** 为控件 attrs 写入新的 controlId，并在缺失时补齐 batchId。 */
+    withFreshControlId<TAttrs extends ReportControlAttrs>(attrs: TAttrs, existing?: Set<string>, batchId?: string): TAttrs;
+    /** 归一化报告文档中的缺失或重复 controlId，并补齐 batchId。 */
+    normalizeDocument(document: ReportDocument, batchId?: string): ReportDocument;
+    /** 收集报告文档中已有的控件 ID。 */
+    collectIds(document: ReportDocument): Set<string>;
+    /** 收集 ProseMirror 文档中需要修复 controlId 或 batchId 的节点。 */
+    collectTransactionUpdates(doc: ProseMirrorNode, batchId?: string): ControlIdentityUpdate[];
+    /** 为粘贴 slice 中的控件重新分配 controlId 和批次 ID。 */
+    assignFreshControlIdsToSlice(slice: Slice, batchId?: string): Slice;
+    /** 递归处理 fragment 中的子节点。 */
+    private assignFreshControlIdsToFragment;
+    /** 为单个 ProseMirror 节点及其子树刷新控件 ID。 */
+    private assignFreshControlIdsToNode;
+    /** 递归归一化报告节点数组。 */
+    private normalizeReportNodes;
+    /** 归一化单个报告节点的 controlId 和 batchId。 */
+    private normalizeReportNode;
+    /** 深度优先遍历报告节点。 */
+    private visitReportNodes;
+    /** 判断节点类型是否为控件。 */
+    private isControlNode;
+    /** 从 attrs 中读取非空 controlId。 */
+    private getControlId;
+    /** 从 attrs 中读取非空 batchId。 */
+    private getBatchId;
+    /** 保留已有 batchId，缺失时使用传入批次或新批次。 */
+    private resolveBatchId;
+    /** 生成原始 controlId 字符串。 */
+    private createRawId;
+}

package/dist/identity/PageBreakIdentityService.d.ts

@@ -0,0 +1,29 @@
+import type { Editor } from '@tiptap/core';
+import { Slice, type Node as ProseMirrorNode } from '@tiptap/pm/model';
+import type { ReportDocument } from '../types/index.js';
+export declare const PAGE_BREAK_NODE_NAME = "pageBreak";
+export type PageBreakIdentityUpdate = {
+    pos: number;
+    id: string;
+};
+/** 创建分页符唯一 ID。 */
+export declare function createPageBreakId(existing?: Set<string>): string;
+/** 维护分页符 ID，确保加载、粘贴和直接事务后的文档仍可稳定定位。 */
+export declare class PageBreakIdentityService {
+    /** 归一化报告 JSON 中缺失或重复的分页符 ID。 */
+    normalizeDocument(document: ReportDocument): ReportDocument;
+    /** 收集 ProseMirror 文档中需要修复的分页符。 */
+    collectTransactionUpdates(doc: ProseMirrorNode): PageBreakIdentityUpdate[];
+    /** 为粘贴或复制式拖拽进入文档的分页符分配新 ID。 */
+    assignFreshIdsToSlice(slice: Slice): Slice;
+    /** 修复已创建编辑器中的分页符 ID，不写入撤销历史。 */
+    applyToEditor(editor: Editor): boolean;
+    /** 递归归一化报告节点。 */
+    private normalizeReportNodes;
+    /** 递归刷新 fragment 中的分页符 ID。 */
+    private assignFreshIdsToFragment;
+    /** 刷新单个节点及其子树中的分页符 ID。 */
+    private assignFreshIdsToNode;
+    /** 从 attrs 中读取可用 ID。 */
+    private getId;
+}

package/dist/identity/VisibilityGroupIdentityService.d.ts

@@ -0,0 +1,24 @@
+import { Slice, type Mark } from '@tiptap/pm/model';
+export declare const VISIBILITY_GROUP_MARK_NAME = "visibilityGroup";
+export declare const DEFAULT_VISIBILITY_GROUP_CONDITION = "all-controls-empty";
+/** 校验运行时 visibilityGroup mark 的必要身份和唯一受支持条件。 */
+export declare function assertVisibilityGroupMarkAttrs(attrs: Record<string, unknown>): void;
+/** 为一次模板展开、粘贴或复制式拖拽创建新的分组身份。 */
+export declare function createVisibilityGroupId(): string;
+/**
+ * 维护 visibilityGroup 的复制身份。
+ *
+ * 普通加载、移动和历史事务不经过本服务，因而保留原 ID；只有复制语义显式调用
+ * assignFreshIdsToSlice，并在同一个 slice 内按“旧 ID → 新 ID”映射。
+ */
+export declare class VisibilityGroupIdentityService {
+    /** 刷新 slice 中的所有分组 ID，同时保留副本内部原有的分组关系。 */
+    assignFreshIdsToSlice(slice: Slice): Slice;
+    /** 从 slice 中移除指定分组；省略 IDs 时移除全部 visibilityGroup mark。 */
+    removeMarksFromSlice(slice: Slice, groupIds?: ReadonlySet<string>): Slice;
+    /** 移除 mark 数组中的 visibilityGroup，同时保留 bold/textStyle 等格式 mark。 */
+    static withoutVisibilityGroupMarks(marks: readonly Mark[]): Mark[];
+    private refreshMarks;
+    private mapFragment;
+    private mapNode;
+}