@hmg-report-editor/core 1.0.0

package/dist/nodeViews/BaseControlNodeView.d.ts

@@ -0,0 +1,82 @@
+import type { NodeViewRendererProps } from '@tiptap/core';
+import { type Node as ProseMirrorNode } from '@tiptap/pm/model';
+import type { NodeView } from '@tiptap/pm/view';
+import type { StructuredFieldAttrs, StructuredFieldValue } from '../types/index.js';
+import { type ControlNavigationDirection, type ReportControlShortcutRuntime } from '../plugins/ControlShortcuts.js';
+export type FieldNodeName = 'structuredField' | 'dropdownField' | string;
+/** 控件 NodeView 基类，统一处理选择、拖拽、剪贴板和快捷键导航。 */
+export declare abstract class BaseControlNodeView<TAttrs extends StructuredFieldAttrs> implements NodeView {
+    protected readonly props: NodeViewRendererProps;
+    protected readonly nodeName: FieldNodeName;
+    protected readonly controlShortcutRuntime: ReportControlShortcutRuntime;
+    readonly dom: HTMLElement;
+    protected node: ProseMirrorNode;
+    private selected;
+    private editable;
+    /** 创建控件根 DOM 并绑定通用交互事件。 */
+    constructor(props: NodeViewRendererProps, nodeName: FieldNodeName, controlShortcutRuntime?: ReportControlShortcutRuntime);
+    /** 接收 ProseMirror 节点更新并重新同步 DOM。 */
+    update(node: ProseMirrorNode): boolean;
+    /** 标记整个控件节点被 ProseMirror 选中。 */
+    selectNode(): void;
+    /** 清除整个控件节点的选中态。 */
+    deselectNode(): void;
+    /** 决定事件由控件内部处理还是交给 ProseMirror。 */
+    stopEvent(event: Event): boolean;
+    /** 忽略控件内部 DOM 变化，状态以节点 attrs 为准。 */
+    ignoreMutation(): boolean;
+    /** 返回当前节点属性的强类型视图。 */
+    protected get attrs(): TAttrs;
+    /** 同步控件焦点样式和数据属性。 */
+    protected setFocused(focused: boolean): void;
+    /** 将控件输入值提交回 ProseMirror 节点 attrs。 */
+    protected commitValue(value: StructuredFieldValue): void;
+    /** 完成当前输入，并按配置跳转到下一个控件。 */
+    protected completeInputAndMaybeFocusNext(event: KeyboardEvent): boolean;
+    /** 从当前控件出发移动焦点到相邻控件。 */
+    protected focusAdjacentControlFromCurrent(direction: ControlNavigationDirection, selectText?: boolean): boolean;
+    /** 同步根元素上的控件身份、空值、只读和拖拽状态。 */
+    protected syncRootAttributes(): void;
+    /** 判断控件值是否应被视为空值。 */
+    protected isValueEmpty(value: StructuredFieldValue | undefined): boolean;
+    /** 处理控件内部输入元素上的快捷键导航。 */
+    private handleShortcutKeyDown;
+    /** 将单个控件写入剪贴板。 */
+    private copyControl;
+    /** 剪切单个控件并从文档中删除节点。 */
+    private cutControl;
+    /** 根据点击目标进入控件编辑或整节点选择。 */
+    private handleMouseDown;
+    /** 控件内部获得焦点时释放整节点选择。 */
+    private handleFocusIn;
+    /** 将当前控件设为 NodeSelection 以支持整节点拖拽。 */
+    private selectNodeForDrag;
+    /** 从整节点选择切回临近文本选区，允许编辑控件内部输入。 */
+    private releaseNodeSelectionForControlEditing;
+    /** 判断鼠标事件是否应该触发整节点选择。 */
+    private shouldSelectNodeFromEvent;
+    /** 判断方向键是否已经到达输入边界并可跳转控件。 */
+    private shouldNavigateFromInteractiveTarget;
+    /** 判断事件目标是否为控件内部可交互元素。 */
+    private isInteractiveTarget;
+    /** 判断事件是否属于拖拽流程。 */
+    private isDragEvent;
+    /** 生成控件 HTML 和纯文本并写入剪贴板。 */
+    private writeControlToClipboard;
+    /** Deletes an empty control and restores the editor caret at the removed node position. */
+    private deleteEmptyControlFromInput;
+    /** 允许子类追加节点特有的剪贴板属性。 */
+    protected decorateClipboardElement(_element: HTMLSpanElement): void;
+    /** 返回控件根元素 class。 */
+    protected abstract rootClassName(): string;
+    /** 返回控件聚焦态 class。 */
+    protected abstract focusedClassName(): string;
+    /** 返回控件选中态 class。 */
+    protected abstract selectedClassName(): string;
+    /** 返回 data-report-node 使用的节点名。 */
+    protected abstract reportNodeName(): string;
+    /** 返回复制到纯文本剪贴板的展示文本。 */
+    protected abstract clipboardText(): string;
+    /** 根据当前 attrs 重新渲染控件内部 DOM。 */
+    protected abstract renderControl(): void;
+}

package/dist/nodeViews/ControlClipboard.d.ts

@@ -0,0 +1,10 @@
+import type { StructuredFieldAttrs } from '../types/index.js';
+/** 控件剪贴板工具，负责生成可被编辑器重新识别的 HTML。 */
+export declare class ControlClipboard {
+    /** 判断输入框内部是否已有文本选区，避免覆盖原生复制。 */
+    static hasSelectedInputText(target: EventTarget | null): boolean;
+    /** 写入控件 HTML 和纯文本到剪贴板。 */
+    static write(event: ClipboardEvent, element: HTMLElement, text: string): boolean;
+    /** 根据控件属性创建剪贴板 HTML 元素。 */
+    static createElement(attrs: StructuredFieldAttrs, rootClassName: string, reportNodeName: string, text: string): HTMLSpanElement;
+}

package/dist/nodeViews/ControlInputAutosize.d.ts

@@ -0,0 +1,2 @@
+/** 根据输入框当前内容同步控件的自动显示宽度变量。 */
+export declare function syncControlInputAutoWidth(input: HTMLInputElement, host: HTMLElement): void;

package/dist/nodeViews/DropdownFieldNodeView.d.ts

@@ -0,0 +1,57 @@
+import type { NodeViewRendererProps } from '@tiptap/core';
+import type { DropdownFieldAttrs } from '../types/index.js';
+import { type ReportControlShortcutRuntime } from '../plugins/ControlShortcuts.js';
+import { BaseControlNodeView } from './BaseControlNodeView.js';
+/** 下拉控件的 NodeView，支持输入文本和选项菜单。 */
+export declare class DropdownFieldNodeView extends BaseControlNodeView<DropdownFieldAttrs> {
+    private readonly combo;
+    private readonly input;
+    private readonly menu;
+    private open;
+    private activeOptionIndex;
+    private menuPortaled;
+    /** 创建输入框和菜单 DOM。 */
+    constructor(props: NodeViewRendererProps, controlShortcutRuntime: ReportControlShortcutRuntime);
+    /** Removes a portaled menu and its page-level listeners with the NodeView. */
+    destroy(): void;
+    /** 返回根元素 class。 */
+    protected rootClassName(): string;
+    /** 返回聚焦态 class。 */
+    protected focusedClassName(): string;
+    /** 返回选中态 class。 */
+    protected selectedClassName(): string;
+    /** 返回序列化 HTML 中的报告节点名。 */
+    protected reportNodeName(): string;
+    /** 生成复制下拉控件时的纯文本展示值。 */
+    protected clipboardText(): string;
+    /** 将下拉选项和自定义输入开关写入剪贴板 HTML。 */
+    protected decorateClipboardElement(element: HTMLSpanElement): void;
+    /** 根据节点 attrs 同步输入框和菜单。 */
+    protected renderControl(): void;
+    /** 渲染下拉选项菜单并绑定选项提交。 */
+    private renderMenu;
+    /** 切换菜单展开状态。 */
+    private setOpen;
+    /** Ports the active menu to the document body so editor overflow cannot clip it. */
+    private mountMenu;
+    /** Returns a closed menu to the NodeView and releases global listeners. */
+    private unmountMenu;
+    /** Repositions the body-level menu after editor/page scrolling or viewport resizing. */
+    private readonly handleViewportChange;
+    /** Anchors the fixed menu to the combo, flipping above when the viewport requires it. */
+    private positionMenu;
+    /** 处理下拉选项切换、选中、展开和关闭快捷键。 */
+    private handleDropdownShortcut;
+    /** 使用方向键移动当前高亮选项。 */
+    private moveActiveOption;
+    /** 用键盘提交当前高亮选项。 */
+    private selectActiveOptionFromKeyboard;
+    /** 按当前值同步键盘高亮选项。 */
+    private syncActiveOptionFromValue;
+    /** 同步菜单选项的键盘高亮状态。 */
+    private syncActiveOptionState;
+    /** 根据当前输入文本同步自动显示长度。 */
+    private syncAutoWidth;
+    /** 将 attrs 中的选项归一化为数组。 */
+    private normalizeOptions;
+}

package/dist/nodeViews/FieldNodeViews.d.ts

@@ -0,0 +1,4 @@
+/** 控件 NodeView 统一出口。 */
+export { BaseControlNodeView } from './BaseControlNodeView.js';
+export { DropdownFieldNodeView } from './DropdownFieldNodeView.js';
+export { StructuredFieldNodeView } from './StructuredFieldNodeView.js';

package/dist/nodeViews/PageBreakNodeView.d.ts

@@ -0,0 +1,20 @@
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
+import type { NodeViewRendererProps } from '@tiptap/core';
+import type { NodeView } from '@tiptap/pm/view';
+/** 分页符编辑态 NodeView，仅提供视觉提示和整体选中反馈。 */
+export declare class PageBreakNodeView implements NodeView {
+    readonly dom: HTMLSpanElement;
+    private node;
+    private selected;
+    constructor(props: NodeViewRendererProps);
+    /** 同步分页符 ID。 */
+    update(node: ProseMirrorNode): boolean;
+    /** 显示整体选中样式。 */
+    selectNode(): void;
+    /** 清除整体选中样式。 */
+    deselectNode(): void;
+    /** 原子节点不接收 DOM 内容变更。 */
+    ignoreMutation(): boolean;
+    /** 渲染编辑态分隔线和提示文本。 */
+    private render;
+}

package/dist/nodeViews/StructuredFieldNodeView.d.ts

@@ -0,0 +1,24 @@
+import type { NodeViewRendererProps } from '@tiptap/core';
+import type { StructuredFieldAttrs } from '../types/index.js';
+import type { ReportControlShortcutRuntime } from '../plugins/ControlShortcuts.js';
+import { BaseControlNodeView } from './BaseControlNodeView.js';
+/** 结构化输入控件的 NodeView。 */
+export declare class StructuredFieldNodeView extends BaseControlNodeView<StructuredFieldAttrs> {
+    private readonly input;
+    /** 创建文本输入框并绑定值提交事件。 */
+    constructor(props: NodeViewRendererProps, controlShortcutRuntime: ReportControlShortcutRuntime);
+    /** 返回根元素 class。 */
+    protected rootClassName(): string;
+    /** 返回聚焦态 class。 */
+    protected focusedClassName(): string;
+    /** 返回选中态 class。 */
+    protected selectedClassName(): string;
+    /** 返回序列化 HTML 中的报告节点名。 */
+    protected reportNodeName(): string;
+    /** 生成复制结构化输入时的纯文本。 */
+    protected clipboardText(): string;
+    /** 根据节点 attrs 同步输入框内容和只读状态。 */
+    protected renderControl(): void;
+    /** 根据当前输入文本同步自动显示长度。 */
+    private syncAutoWidth;
+}

package/dist/plugins/ControlGapCursor.d.ts

@@ -0,0 +1,21 @@
+import { Extension } from '@tiptap/core';
+import type { EditorState, Transaction } from '@tiptap/pm/state';
+import { type EditorView } from '@tiptap/pm/view';
+/** 创建相邻行内控件间隙的鼠标光标映射扩展。 */
+export declare function createControlGapCursorExtension(controlNodeNames?: string[]): Extension;
+/** Marks a collapsed text selection that needs an explicit caret beside an atom control. */
+export declare function showControlBoundaryCaret(transaction: Transaction, pos: number): Transaction;
+/** Returns the document position of the temporary caret left by control deletion. */
+export declare function getControlBoundaryCaretPosition(state: EditorState): number | null;
+/** Clears a temporary boundary caret before keyboard focus moves into another control. */
+export declare function clearControlBoundaryCaret(transaction: Transaction): Transaction;
+/**
+ * 让 core 把间隙输入处理器作为 EditorView 直接 prop 安装。
+ * 直接 prop 先于 Tiptap 聚合的 input-rules 插件运行，防止规则按浏览器吸附位置提前消费输入。
+ */
+export declare function handleControlGapTextInput(view: EditorView, from: number, to: number, text: string, defaultTransaction: () => Transaction): boolean;
+/**
+ * 让 composition 生命周期先于 Tiptap input-rules 插件排队收尾，
+ * 确保规则是在文本回到规范边界后再检查最终输入。
+ */
+export declare function handleControlGapDOMEvent(view: EditorView, event: Event): boolean;

package/dist/plugins/ControlSelectionLifecycle.d.ts

@@ -0,0 +1,3 @@
+import { Extension } from '@tiptap/core';
+/** 创建控件整体选中态的焦点生命周期扩展。 */
+export declare function createControlSelectionLifecycleExtension(controlNodeNames: string[]): Extension;

package/dist/plugins/ControlShortcuts.d.ts

@@ -0,0 +1,40 @@
+import { Extension } from '@tiptap/core';
+import type { EditorView } from '@tiptap/pm/view';
+import type { ReportEditorGroupManager } from '../group/ReportEditorGroupManager.js';
+import type { ReportControlShortcutOptions } from '../types/index.js';
+/** 控件快捷键导航方向。 */
+export type ControlNavigationDirection = 'next' | 'previous';
+/** 归一化后的控件快捷键配置。 */
+export type ResolvedReportControlShortcuts = {
+    enabled: boolean;
+    nextControl: string;
+    previousControl: string;
+    openDropdown: string;
+    closeDropdown: string;
+    nextDropdownOption: string;
+    previousDropdownOption: string;
+    selectDropdownOption: string;
+    submitInput: string;
+    autoFocusNextOnEnter: boolean;
+};
+/** 控件快捷键运行时依赖。 */
+export type ReportControlShortcutRuntime = {
+    shortcuts: ResolvedReportControlShortcuts;
+    controlNodeNames: string[];
+    controlReportNodeNames: string[];
+    editorGroup?: ReportEditorGroupManager;
+};
+/** 创建控件快捷键运行时配置。 */
+export declare function createReportControlShortcutRuntime(options?: ReportControlShortcutOptions, controlNodeNames?: string[], controlReportNodeNames?: string[], editorGroup?: ReportEditorGroupManager): ReportControlShortcutRuntime;
+/** 合并业务配置和默认快捷键。 */
+export declare function resolveReportControlShortcuts(options?: ReportControlShortcutOptions): ResolvedReportControlShortcuts;
+/** 根据键盘事件解析控件导航方向。 */
+export declare function controlNavigationDirectionFromEvent(event: KeyboardEvent, shortcuts: ResolvedReportControlShortcuts): ControlNavigationDirection | undefined;
+/** 判断键盘事件是否匹配一个无修饰键快捷键。 */
+export declare function matchesControlShortcut(event: KeyboardEvent, shortcutKey: string): boolean;
+/** 判断键盘事件是否为左右方向键。 */
+export declare function isHorizontalArrowKey(event: KeyboardEvent): boolean;
+/** 在当前范围内移动焦点到上一个或下一个控件。 */
+export declare function focusAdjacentControl(view: EditorView, currentPos: number, runtime: ReportControlShortcutRuntime, direction: ControlNavigationDirection, selectText?: boolean): boolean;
+/** 创建处理整节点选中态快捷键的 ProseMirror 插件扩展。 */
+export declare function createControlShortcutExtension(runtime: ReportControlShortcutRuntime): Extension;

package/dist/plugins/ControlTransactionMeta.d.ts

@@ -0,0 +1,10 @@
+import type { Transaction } from '@tiptap/pm/state';
+export type ControlAttrsTransactionMeta = {
+    controlIds: string[];
+};
+/** Marks a validated transaction that only changes attrs on existing controls. */
+export declare function markControlAttrsTransaction(transaction: Transaction, controlIds: Iterable<string>): Transaction;
+/** Reads and validates the internal existing-control attrs transaction marker. */
+export declare function readControlAttrsTransaction(transaction: Transaction): ControlAttrsTransactionMeta | undefined;
+/** True when every document-changing transaction is a validated control attrs update. */
+export declare function onlyControlAttrsChanged(transactions: readonly Transaction[]): boolean;

package/dist/plugins/NumberingPlugin.d.ts

@@ -0,0 +1,15 @@
+import { Plugin } from '@tiptap/pm/state';
+import { Extension } from '@tiptap/core';
+import { NumberingService } from './NumberingService.js';
+/** 创建自动维护编号块的 ProseMirror 插件。 */
+export declare class NumberingPluginFactory {
+    private readonly nodeName;
+    private readonly service;
+    /** 绑定编号节点名和编号服务。 */
+    constructor(nodeName?: string, service?: NumberingService);
+    /** 创建 appendTransaction 编号修复插件。 */
+    create(): Plugin;
+}
+/** 创建 Tiptap 编号扩展。 */
+export declare function createNumberingExtension(nodeName?: string): Extension<any, any>;
+export declare const NumberingExtension: Extension<any, any>;

package/dist/plugins/NumberingService.d.ts

@@ -0,0 +1,29 @@
+import type { Editor } from '@tiptap/core';
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model';
+import type { Transaction } from '@tiptap/pm/state';
+/** 编号块需要写回的新编号。 */
+export type NumberingUpdate = {
+    pos: number;
+    number: string;
+};
+/** 编号块在 ProseMirror 文档中的位置。 */
+export type NumberedBlockPosition = {
+    pos: number;
+    node: ProseMirrorNode;
+};
+/** 编号块服务，负责收集、重排和写回自动编号。 */
+export declare class NumberingService {
+    private readonly nodeName;
+    /** 绑定需要维护编号的节点名。 */
+    constructor(nodeName?: string);
+    /** 收集文档中所有编号块。 */
+    collectBlocks(doc: ProseMirrorNode): NumberedBlockPosition[];
+    /** 计算所有自动编号块需要更新的编号。 */
+    collectUpdates(doc: ProseMirrorNode): NumberingUpdate[];
+    /** 将编号更新写入已有事务。 */
+    applyToTransaction(tr: Transaction): Transaction;
+    /** 直接将编号更新应用到编辑器。 */
+    applyToEditor(editor: Editor, addToHistory?: boolean): boolean;
+    /** 按索引移动编号块并重新计算编号。 */
+    moveBlock(editor: Editor, fromIndex: number, toIndex: number): boolean;
+}

package/dist/plugins/PasteSanitizer.d.ts

@@ -0,0 +1,32 @@
+import { Extension } from '@tiptap/core';
+import type { ReportEditorGroupManager } from '../group/ReportEditorGroupManager.js';
+import type { ReportFeatureRegistry } from '../types/index.js';
+export type InvalidControlAttrsHandler = (detail: {
+    nodeName: string;
+    attrs: Record<string, unknown>;
+    error: unknown;
+}) => void;
+export type InvalidVisibilityGroupDetail = {
+    nodeName: string;
+    attrs: Record<string, unknown>;
+    error: unknown;
+};
+export type InvalidVisibilityGroupHandler = (detail: InvalidVisibilityGroupDetail) => void;
+/** 粘贴 HTML 清洗器，保留安全标签、样式和报告 data 属性。 */
+export declare class PasteSanitizer {
+    /** 清洗粘贴 HTML，浏览器环境优先使用 DOMParser。 */
+    sanitize(html: string): string;
+    /** 拒绝会在 schema 解析时静默丢失条件隐藏语义的旧或非法报告 HTML。 */
+    private assertSupportedReportMarkup;
+    /** 递归清洗子元素并扁平化不支持标签。 */
+    private sanitizeChildren;
+    /** 移除事件属性和非白名单属性。 */
+    private sanitizeAttributes;
+    /** 只保留安全的内联样式声明。 */
+    private sanitizeStyle;
+    /** 在没有 DOMParser 的环境下做保守字符串清洗。 */
+    private regexFallback;
+}
+/** 创建粘贴清洗和控件 ID/批次修复扩展。 */
+export declare function createPasteSanitizerExtension(registry?: ReportFeatureRegistry, getCurrentBatchId?: () => string | undefined, onInvalidControlAttrs?: InvalidControlAttrsHandler, onInvalidVisibilityGroup?: InvalidVisibilityGroupHandler, editorGroup?: ReportEditorGroupManager): Extension<any, any>;
+export declare const PasteSanitizerExtension: Extension<any, any>;

package/dist/registry/ReportFeatureRegistry.d.ts

@@ -0,0 +1,16 @@
+import type { ReportFeatureDescriptor, ReportFeatureRegistry as ReportFeatureRegistryContract, ReportMarkDescriptor, ReportNodeDescriptor } from '../types/index.js';
+/** 定义普通报告节点描述符，保留传入对象的精确类型。 */
+export declare function defineReportNode<TDescriptor extends ReportNodeDescriptor>(descriptor: TDescriptor): TDescriptor;
+/** 定义结构化控件节点描述符，并自动标记为控件。 */
+export declare function defineReportControl<TDescriptor extends ReportNodeDescriptor>(descriptor: TDescriptor): TDescriptor & {
+    isControl: true;
+    isInline: TDescriptor extends {
+        isInline: infer TInline extends boolean;
+    } ? TInline : true;
+};
+/** 定义报告 mark 描述符，保留传入对象的精确类型。 */
+export declare function defineReportMark<TDescriptor extends ReportMarkDescriptor>(descriptor: TDescriptor): TDescriptor;
+/** 定义 feature 描述符，保留业务扩展的精确类型。 */
+export declare function defineReportFeature<TDescriptor extends ReportFeatureDescriptor>(descriptor: TDescriptor): TDescriptor;
+/** 创建包含内置 feature 和业务 feature 的注册表。 */
+export declare function createReportFeatureRegistry(features?: ReportFeatureDescriptor[]): ReportFeatureRegistryContract;

package/dist/registry/builtinReportNodes.d.ts

@@ -0,0 +1,19 @@
+import type { ReportFeatureDescriptor, ReportMarkDescriptor, ReportNodeDescriptor } from '../types/index.js';
+/** 内置富文本 mark 的 HTML 和纯文本序列化规则。 */
+export declare const builtinReportMarkDescriptors: ReportMarkDescriptor[];
+/** 结构化输入控件的模板转换、校验和序列化描述。 */
+export declare const structuredFieldDescriptor: ReportNodeDescriptor;
+/** 下拉控件的模板转换、校验和序列化描述。 */
+export declare const dropdownFieldDescriptor: ReportNodeDescriptor;
+/** 报告编号块的模板转换、编号展示和纯文本描述。 */
+export declare const reportNumberedBlockDescriptor: ReportNodeDescriptor;
+/** 手动分页符模板转换和外部 HTML 合约。 */
+export declare const pageBreakDescriptor: ReportNodeDescriptor;
+/** 内置报告节点描述符集合。 */
+export declare const builtinReportNodeDescriptors: ReportNodeDescriptor[];
+/** 基础 Tiptap 能力和内置 mark feature。 */
+export declare const builtinBaseFeature: ReportFeatureDescriptor;
+/** 报告业务节点 feature。 */
+export declare const builtinReportNodesFeature: ReportFeatureDescriptor;
+/** 默认随 core 启用的全部 feature。 */
+export declare const builtinReportFeatures: ReportFeatureDescriptor[];

package/dist/selection/SelectionManager.d.ts

@@ -0,0 +1,18 @@
+import type { Editor } from '@tiptap/core';
+import type { SavedSelection } from '../types/index.js';
+import { ReportErrorDispatcher } from '../utils/ReportErrorDispatcher.js';
+/** 选区管理器，负责保存和安全恢复编辑器选区。 */
+export declare class SelectionManager {
+    private readonly errors;
+    private savedSelection;
+    /** 创建选区管理器并绑定错误派发器。 */
+    constructor(errors?: ReportErrorDispatcher);
+    /** 保存当前编辑器选区。 */
+    save(editor: Editor): SavedSelection;
+    /** 尝试恢复指定选区，失败时回退到最近有效位置。 */
+    restore(editor: Editor, selection?: SavedSelection | null): boolean;
+    /** 将选区恢复到文档末尾附近。 */
+    restoreToDocumentEnd(editor: Editor): boolean;
+    /** 将位置限制在文档有效范围内。 */
+    private clamp;
+}

package/dist/serializer/ReportSerializer.d.ts

@@ -0,0 +1,57 @@
+import type { Editor } from '@tiptap/core';
+import type { HtmlOutputMode, ProseMirrorNode, ReportDocument, ReportFeatureRegistry, ReportPlainTextOptions } from '../types/index.js';
+import { ReportErrorDispatcher } from '../utils/ReportErrorDispatcher.js';
+/** 报告序列化器，负责 JSON、HTML 和纯文本输出。 */
+export declare class ReportSerializer {
+    private readonly documentVersion;
+    private readonly errors;
+    private readonly registry;
+    /** 创建序列化器并绑定版本、错误派发器和 feature 注册表。 */
+    constructor(documentVersion?: string, errors?: ReportErrorDispatcher, registry?: ReportFeatureRegistry);
+    /** 从 Tiptap editor 导出报告 JSON。 */
+    toJSON(editor: Editor): ReportDocument;
+    /** 按编辑、预览或打印模式导出完整 HTML 外层。 */
+    toHTML(editor: Editor, mode?: HtmlOutputMode): string;
+    /** 从已导出的报告 JSON 渲染完整 HTML 外层，避免重复读取编辑器文档。 */
+    toHTMLFromJSON(json: ReportDocument, mode?: HtmlOutputMode): string;
+    /** 导出报告纯文本，供搜索、复制或后端摘要使用。 */
+    toPlainText(editor: Editor, options?: ReportPlainTextOptions): string;
+    /** 渲染一组 ProseMirror 节点为 HTML。 */
+    private renderContent;
+    /** 将单个 ProseMirror 节点分派到内置或自定义渲染器。 */
+    private renderNode;
+    /** 渲染段落并在预览/打印模式中过滤整段隐藏和条件隐藏产生的空段。 */
+    private renderParagraph;
+    /** 使用注册表中的 mark 描述符渲染内联格式。 */
+    private applyMark;
+    /** 读取节点唯一允许携带的 visibilityGroup mark。 */
+    private getVisibilityGroupMark;
+    /** 判断相邻成员是否属于同一分组，从而输出单一连续 wrapper。 */
+    private isSameVisibilityGroup;
+    /** 渲染块级节点通用 class、缩进和行高属性。 */
+    renderBlockAttrs(node: ProseMirrorNode, className: string): string;
+    /** 渲染列表结构，并清理分页符归一化后留下的空容器。 */
+    private renderStructuralContainer;
+    /** 判断报告节点子树是否包含分页符。 */
+    private containsPageBreak;
+    /** 判断子树是否包含被条件组过滤的成员，用于清理随空段留下的列表容器。 */
+    private containsHiddenVisibilityMember;
+    /** 只渲染隐藏内容树中的分页符，不输出被隐藏的正文或容器。 */
+    private renderPageBreaksOnly;
+    /** 计算 preview/print 中位于两段有效可见内容之间的首个分页符。 */
+    private collectRetainedPageBreakIds;
+    /** 按输出可见性将文档压缩成有效内容和分页符 token。 */
+    private collectOutputTokens;
+    /** 使用控件 descriptor 的真实 preview/print 输出判断其是否形成分页有效内容。 */
+    private rendersVisibleControlContent;
+    /** 归一化纯文本导出选项。 */
+    private normalizePlainTextOptions;
+    /** 渲染一组 ProseMirror 节点为纯文本。 */
+    private renderTextContent;
+    /** 将单个节点分派到纯文本渲染规则。 */
+    private renderTextNode;
+    /** 让自定义 mark 有机会转换纯文本输出。 */
+    private renderTextMarks;
+    /** 对同一未知节点或 mark 只派发一次序列化警告。 */
+    private warnUnsupported;
+}

package/dist/serializer/VisibilityGroupResolver.d.ts

@@ -0,0 +1,20 @@
+import type { ProseMirrorNode, ReportFeatureRegistry } from '../types/index.js';
+/**
+ * 对整篇文档的条件隐藏组做一次预扫描。
+ *
+ * groupId 是全文身份，因此解析不依赖成员是否相邻、是否位于同一段落。
+ */
+export declare class VisibilityGroupResolver {
+    private readonly registry;
+    private readonly hiddenGroupIds;
+    constructor(content: ProseMirrorNode[] | undefined, registry: ReportFeatureRegistry);
+    /** 判断节点是否属于任一满足隐藏条件的分组。 */
+    isNodeHidden(node: ProseMirrorNode): boolean;
+    /** 判断节点是否携带 visibilityGroup 语义。 */
+    isGrouped(node: ProseMirrorNode): boolean;
+    /** 返回已判定隐藏的组 ID 快照，便于诊断和测试。 */
+    hiddenGroups(): ReadonlySet<string>;
+    private scan;
+    private groupMarks;
+    private isRawContent;
+}

package/dist/template/ReportTemplateEngine.d.ts

@@ -0,0 +1,41 @@
+import type { Editor } from '@tiptap/core';
+import type { ReportDocument, ReportFeatureRegistry, ReportTemplate } from '../types/index.js';
+import { ControlIdentityService } from '../identity/ControlIdentityService.js';
+import { ReportErrorDispatcher } from '../utils/ReportErrorDispatcher.js';
+/** 模板引擎，负责校验模板并转换为 ProseMirror 文档。 */
+export declare class ReportTemplateEngine {
+    private readonly errors;
+    private readonly identity;
+    private readonly registry;
+    /** 创建模板引擎并绑定错误派发、控件身份和 feature 注册表。 */
+    constructor(errors?: ReportErrorDispatcher, identity?: ControlIdentityService, registry?: ReportFeatureRegistry);
+    /** 校验模板根结构和所有子节点。 */
+    validate(template: ReportTemplate): void;
+    /** 将业务模板转换为报告 JSON 文档。 */
+    toDocument(template: ReportTemplate, batchId?: string): ReportDocument;
+    /** 用模板生成的文档替换当前编辑器内容。 */
+    applyTemplate(editor: Editor, template: ReportTemplate, batchId?: string): boolean;
+    /**
+     * 将模板内容追加到当前选区之后。
+     *
+     * 折叠选区使用光标位置，非折叠选区使用 selection.to，绝不替换选中内容；
+     * 选区不可用时回退到文档末尾。成功后由 insertContentAt 将选区放到新增内容末端。
+     */
+    appendTemplate(editor: Editor, template: ReportTemplate, batchId?: string): boolean;
+    /** 返回当前选区之后的插入位置；缺失、越界或不可解析时使用文档末尾。 */
+    private resolveAppendPosition;
+    /** 递归校验模板节点和自定义节点约束。 */
+    private validateNode;
+    /** 校验模板期条件隐藏组的位置、条件和 inline-only 内容约束。 */
+    private validateVisibilityGroup;
+    /** 根据内置文本或节点 descriptor 的能力声明判断模板节点是否为 inline。 */
+    private isInlineTemplateNode;
+    /** 将模板节点转换为 ProseMirror 节点 JSON。 */
+    private toProseMirrorNode;
+    /** 模板只能通过 visibilityGroup 容器创建运行时分组 mark。 */
+    private validateTemplateMarks;
+    /** 防止自定义 descriptor 绕过模板容器直接制造运行时 visibilityGroup mark。 */
+    private assertNoRuntimeVisibilityMarks;
+    /** 转换一组模板子节点。 */
+    private toContent;
+}