@agile-team/mach-report 2.4.1 → 2.6.1

package/dist/vue/async.d.ts

@@ -13,6 +13,25 @@ import { PropType } from 'vue';
 import { PublicProps } from 'vue';
 import { VNodeProps } from 'vue';
 
+declare interface AssetRenderBudget {
+    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
+    maxAssets?: number;
+    /** Maximum image payload bytes per new asset, default 32 MiB. */
+    maxImageBytes?: number;
+    /** Maximum total image payload bytes for new assets, default 128 MiB. */
+    maxTotalImageBytes?: number;
+    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
+    maxDurationMs?: number;
+}
+
+declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    assetBudget?: AssetRenderBudget;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+
 /**
  * 列值格式化（声明式、JSON 可序列化）。
  * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
@@ -53,6 +72,16 @@ declare type ColumnFormat_2 = {
     pattern?: string;
 };
 
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
 declare type ComponentKind =
 | "text"
 | "image"
@@ -139,8 +168,12 @@ declare interface ComponentStyle_3 {
     rotateDeg?: number;
 }
 
+declare interface DatasetContract { fields: readonly ReportFieldContract[]; rowKey?: string }
+
 declare type DatasetRows = Record<string, Record<string, unknown>[]>;
 
+declare interface DatasetValidationOptions { path?: string; maxRows?: number; maxCells?: number; maxIssues?: number }
+
 declare interface ExcelImportedSheet {
     name: string;
     /** Original, one-based workbook position. */
@@ -232,6 +265,7 @@ declare interface GridCell {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -251,6 +285,7 @@ declare interface GridCell_2 {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource_2;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent_2[];
@@ -270,6 +305,7 @@ declare interface GridCell_3 {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource_3;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent_3[];
@@ -278,6 +314,8 @@ declare interface GridCell_3 {
     style?: ComponentStyle_3;
 }
 
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
 declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
 
@@ -303,6 +341,8 @@ declare interface ListColumn {
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
     valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 declare interface ListColumn_2 {
@@ -324,6 +364,8 @@ declare interface ListColumn_2 {
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
     valueType?: GridCell_3["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 declare interface ListComponent {
@@ -337,6 +379,10 @@ declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -349,6 +395,8 @@ declare interface ListComponent {
     /** 表头默认对齐，列配置可覆盖。 */
     headerAlign?: ComponentStyle["align"];
     headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -367,6 +415,10 @@ declare interface ListComponent_2 {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn_2[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -379,6 +431,8 @@ declare interface ListComponent_2 {
     /** 表头默认对齐，列配置可覆盖。 */
     headerAlign?: ComponentStyle_3["align"];
     headerStyle?: ComponentStyle_3;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid_3;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy_2;
@@ -450,6 +504,13 @@ declare interface MachReportDefaults {
     showExport?: boolean;
     showPrint?: boolean;
     showPdfWindow?: boolean;
+    /** 设置入口默认显示；可在其中按需启用阅读及输出工具。 */
+    showSettings?: boolean;
+    toolbar?: MachReportToolbarOptions;
+    interaction?: ReportInteractionOptions;
+    preferences?: ReportPreferencesOptions;
+    /** Prepare optional image/chart/QR/barcode adapters once for preview and all outputs. */
+    assets?: AssetRenderOptions;
     /** 参数面板显隐（有参数定义且未显式关闭时显示；缺省 true） */
     showParams?: boolean;
     /** 页间距 px */
@@ -523,6 +584,11 @@ declare interface MachReportMessages {
     reset: string;
     /** 必填缺失提示（{label} 占位） */
     paramRequired: string;
+    paramInvalid?: string;
+    paramPrompt?: string;
+    paramPromptDescription?: string;
+    paramSelectPlaceholder?: string;
+    paramTextPlaceholder?: string;
     /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
     searching?: string;
     importExcel?: string;
@@ -533,6 +599,51 @@ declare interface MachReportMessages {
     editInvalidNumber?: string;
     editInvalidBoolean?: string;
     editConflict?: string;
+    settings?: string;
+    settingsDisplay?: string;
+    settingsExport?: string;
+    settingsData?: string;
+    settingsUnavailable?: string;
+    settingsReset?: string;
+    settingsClose?: string;
+    search?: string;
+    closeSearch?: string;
+    prevSearchMatch?: string;
+    nextSearchMatch?: string;
+    zoom?: string;
+    settingsLocal?: string;
+    editingLocal?: string;
+    editingSaved?: string;
+    importLocal?: string;
+    emptyDescription?: string;
+    undo?: string;
+    redo?: string;
+    restoreChanges?: string;
+    changes?: string;
+    changesCount?: string;
+    changesEmpty?: string;
+    changesBefore?: string;
+    changesAfter?: string;
+    editAtomicRequired?: string;
+    clipboardLimit?: string;
+    preferencesError?: string;
+    freezeHeaders?: string;
+    frozenColumns?: string;
+    sections?: string;
+    locateField?: string;
+    locateFieldPlaceholder?: string;
+    locateFieldMissing?: string;
+    importSummary?: string;
+    importPreserved?: string;
+    importWarnings?: string;
+    importReadOnly?: string;
+    conflicts?: string;
+    editReadOnly?: string;
+    editMissing?: string;
+    editDuplicate?: string;
+    clipboardInvalid?: string;
+    editSaved?: string;
+    settingsPanes?: string;
 }
 
 declare interface MachReportPluginOptions {
@@ -586,6 +697,30 @@ export declare const MachReportPreview: {
     type: BooleanConstructor;
     default: undefined;
     };
+    showSettings: {
+    type: BooleanConstructor;
+    default: undefined;
+    };
+    toolbar: {
+    type: PropType<MachReportToolbarOptions>;
+    default: undefined;
+    };
+    interaction: {
+    type: PropType<ReportInteractionOptions>;
+    default: undefined;
+    };
+    preferences: {
+    type: PropType<ReportPreferencesOptions>;
+    default: undefined;
+    };
+    assets: {
+    type: PropType<AssetRenderOptions>;
+    default: undefined;
+    };
+    emptyState: {
+    type: PropType<boolean | ReportEmptyState>;
+    default: boolean;
+    };
     gapPx: {
     type: NumberConstructor;
     default: undefined;
@@ -623,37 +758,48 @@ export declare const MachReportPreview: {
     default: null;
     };
     }>> & Readonly<{
+    onWarning?: ((message: string) => any) | undefined;
     onError?: ((message: string, detail?: {
     code: string;
     cause?: unknown;
     } | undefined) => any) | undefined;
     onLoaded?: ((pageCount: number) => any) | undefined;
-    onWarning?: ((message: string) => any) | undefined;
-    "onCell-edit"?: ((edit: ReportCellEdit_2) => any) | undefined;
+    "onCell-edit"?: ((edit: ReportCellEdit) => any) | undefined;
     "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
+    "onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
     }>, {
-    reload: () => Promise<void>;
-    print: () => Promise<void>;
-    exportAs: (format: string) => Promise<void>;
-    openPdfWindow: () => void;
-    gotoPage: (n: number) => void;
-    setParams: (values: Record<string, string>, opts?: {
-    reload?: boolean;
-    }) => Promise<void>;
-    checkPdfFont: () => Promise<PdfFontCheckResult>;
-    importExcel: (input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2) => Promise<ExcelImportResult | null>;
-    getPlan: () => RenderPlan | null;
-    getChanges: () => ReportCellEdit_2[];
     state: ComputedRef<MachReportState>;
+    checkPdfFont?(): Promise<PdfFontCheckResult>;
+    reload(): Promise<void>;
+    print(): Promise<void>;
+    exportAs(format: string): Promise<void> | void;
+    openPdfWindow(): void;
+    gotoPage(page: number): void;
+    setParams(values: Record<string, string>, opts?: {
+    reload?: boolean;
+    }): Promise<void> | void;
+    importExcel?(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2): Promise<ExcelImportResult | null>;
+    getPlan?(): RenderPlan | null;
+    getChanges?(): ReportCellEdit[];
+    getDifferences?(): ReportCellEdit[];
+    undo?(): Promise<boolean>;
+    redo?(): Promise<boolean>;
+    restoreChanges?(): Promise<boolean>;
+    getSelection?(): ReportCellSelection | null;
+    focusCell?(address: ReportCellAddress, extend?: boolean): Promise<boolean>;
+    focusField?(target: ReportFieldTarget): Promise<boolean>;
+    copySelection?(): string;
+    pasteSelection?(text: string): Promise<boolean>;
     }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+    warning: (message: string) => any;
     error: (message: string, detail?: {
     code: string;
     cause?: unknown;
     } | undefined) => any;
     loaded: (pageCount: number) => any;
-    warning: (message: string) => any;
-    "cell-edit": (edit: ReportCellEdit_2) => any;
+    "cell-edit": (edit: ReportCellEdit) => any;
     "template-import": (result: ExcelImportResult) => any;
+    "preferences-change": (preferences: Readonly<ReportPreviewPreferences>) => any;
     }, PublicProps, {
     editable: boolean | ReportEditingOptions;
     height: string;
@@ -664,14 +810,159 @@ export declare const MachReportPreview: {
     showExport: boolean;
     showPrint: boolean;
     showPdfWindow: boolean;
+    showSettings: boolean;
     showParams: boolean;
+    toolbar: MachReportToolbarOptions;
+    interaction: ReportInteractionOptions;
+    preferences: ReportPreferencesOptions;
+    assets: AssetRenderOptions;
     messages: Partial<MachReportMessages>;
     excelImport: boolean | ExcelImportOptions_2;
     autoLoad: boolean;
+    emptyState: boolean | ReportEmptyState;
     preset: string;
     paramDefs: ReportParamDef[] | undefined;
     fetcher: PlanFetcher | null;
     }, true, {}, {}, { [K in keyof GlobalComponents]: GlobalComponents[K] }, { [K in keyof GlobalDirectives]: GlobalDirectives[K] }, string, {
+    paramPanelRef: CreateComponentPublicInstanceWithMixins<Readonly<{
+    defs: ReportParamDef[];
+    modelValue: Record<string, string>;
+    messages: MachReportMessages;
+    attempted: boolean;
+    issues?: readonly ReportParamIssue[];
+    }> & Readonly<{
+    onReset?: (() => any) | undefined;
+    onQuery?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: Record<string, string>) => any) | undefined;
+    }>, {
+    focusInvalid: () => void;
+    }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+    reset: () => any;
+    query: () => any;
+    "update:modelValue": (value: Record<string, string>) => any;
+    }, PublicProps, {}, false, {}, {}, { [K in keyof GlobalComponents]: GlobalComponents[K] }, { [K in keyof GlobalDirectives]: GlobalDirectives[K] }, string, {
+    root: HTMLDivElement;
+    }, HTMLDivElement, ComponentProvideOptions, {
+    P: {};
+    B: {};
+    D: {};
+    C: {};
+    M: {};
+    Defaults: {};
+    }, Readonly<{
+    defs: ReportParamDef[];
+    modelValue: Record<string, string>;
+    messages: MachReportMessages;
+    attempted: boolean;
+    issues?: readonly ReportParamIssue[];
+    }> & Readonly<{
+    onReset?: (() => any) | undefined;
+    onQuery?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: Record<string, string>) => any) | undefined;
+    }>, {
+    focusInvalid: () => void;
+    }, {}, {}, {}, {}> | null;
+    toolbarRef: CreateComponentPublicInstanceWithMixins<Readonly<{
+    pageCount: number;
+    currentPage: number;
+    zoomMode: "fit" | "raw";
+    zoom: number;
+    showExport: boolean;
+    showPrint: boolean;
+    showPdfWindow: boolean;
+    messages: MachReportMessages;
+    search: {
+    visible: boolean;
+    query: string;
+    matchIndex: number;
+    matchCount: number;
+    searching?: boolean;
+    };
+    thumbsVisible: boolean;
+    showImport?: boolean;
+    showSearch?: boolean;
+    showThumbnails?: boolean;
+    showZoom?: boolean;
+    exportFormats?: readonly ReportExportFormat[];
+    showSettings?: boolean;
+    settingsOpen?: boolean;
+    busy?: boolean;
+    }> & Readonly<{
+    onExport?: ((format: "pdf" | "xlsx" | "html" | "png" | "word") => any) | undefined;
+    onPrint?: (() => any) | undefined;
+    onZoom?: ((mode: number | "fit") => any) | undefined;
+    onGoto?: ((page: number) => any) | undefined;
+    "onPdf-window"?: (() => any) | undefined;
+    "onSearch-input"?: ((query: string) => any) | undefined;
+    "onSearch-nav"?: ((dir: 1 | -1) => any) | undefined;
+    "onSearch-toggle"?: (() => any) | undefined;
+    "onThumbs-toggle"?: (() => any) | undefined;
+    "onImport-excel"?: (() => any) | undefined;
+    "onSettings-toggle"?: (() => any) | undefined;
+    }>, {
+    focusSearch: () => void;
+    }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+    export: (format: "pdf" | "xlsx" | "html" | "png" | "word") => any;
+    print: () => any;
+    zoom: (mode: number | "fit") => any;
+    goto: (page: number) => any;
+    "pdf-window": () => any;
+    "search-input": (query: string) => any;
+    "search-nav": (dir: 1 | -1) => any;
+    "search-toggle": () => any;
+    "thumbs-toggle": () => any;
+    "import-excel": () => any;
+    "settings-toggle": () => any;
+    }, PublicProps, {}, false, {}, {}, { [K in keyof GlobalComponents]: GlobalComponents[K] }, { [K in keyof GlobalDirectives]: GlobalDirectives[K] }, string, {
+    searchInputRef: HTMLInputElement;
+    searchToggleRef: HTMLButtonElement;
+    }, HTMLDivElement, ComponentProvideOptions, {
+    P: {};
+    B: {};
+    D: {};
+    C: {};
+    M: {};
+    Defaults: {};
+    }, Readonly<{
+    pageCount: number;
+    currentPage: number;
+    zoomMode: "fit" | "raw";
+    zoom: number;
+    showExport: boolean;
+    showPrint: boolean;
+    showPdfWindow: boolean;
+    messages: MachReportMessages;
+    search: {
+    visible: boolean;
+    query: string;
+    matchIndex: number;
+    matchCount: number;
+    searching?: boolean;
+    };
+    thumbsVisible: boolean;
+    showImport?: boolean;
+    showSearch?: boolean;
+    showThumbnails?: boolean;
+    showZoom?: boolean;
+    exportFormats?: readonly ReportExportFormat[];
+    showSettings?: boolean;
+    settingsOpen?: boolean;
+    busy?: boolean;
+    }> & Readonly<{
+    onExport?: ((format: "pdf" | "xlsx" | "html" | "png" | "word") => any) | undefined;
+    onPrint?: (() => any) | undefined;
+    onZoom?: ((mode: number | "fit") => any) | undefined;
+    onGoto?: ((page: number) => any) | undefined;
+    "onPdf-window"?: (() => any) | undefined;
+    "onSearch-input"?: ((query: string) => any) | undefined;
+    "onSearch-nav"?: ((dir: 1 | -1) => any) | undefined;
+    "onSearch-toggle"?: (() => any) | undefined;
+    "onThumbs-toggle"?: (() => any) | undefined;
+    "onImport-excel"?: (() => any) | undefined;
+    "onSettings-toggle"?: (() => any) | undefined;
+    }>, {
+    focusSearch: () => void;
+    }, {}, {}, {}, {}> | null;
     importInputRef: HTMLInputElement;
     viewportRef: HTMLDivElement;
     containerRef: HTMLDivElement;
@@ -712,6 +1003,30 @@ export declare const MachReportPreview: {
     type: BooleanConstructor;
     default: undefined;
     };
+    showSettings: {
+    type: BooleanConstructor;
+    default: undefined;
+    };
+    toolbar: {
+    type: PropType<MachReportToolbarOptions>;
+    default: undefined;
+    };
+    interaction: {
+    type: PropType<ReportInteractionOptions>;
+    default: undefined;
+    };
+    preferences: {
+    type: PropType<ReportPreferencesOptions>;
+    default: undefined;
+    };
+    assets: {
+    type: PropType<AssetRenderOptions>;
+    default: undefined;
+    };
+    emptyState: {
+    type: PropType<boolean | ReportEmptyState>;
+    default: boolean;
+    };
     gapPx: {
     type: NumberConstructor;
     default: undefined;
@@ -749,28 +1064,38 @@ export declare const MachReportPreview: {
     default: null;
     };
     }>> & Readonly<{
+    onWarning?: ((message: string) => any) | undefined;
     onError?: ((message: string, detail?: {
     code: string;
     cause?: unknown;
     } | undefined) => any) | undefined;
     onLoaded?: ((pageCount: number) => any) | undefined;
-    onWarning?: ((message: string) => any) | undefined;
-    "onCell-edit"?: ((edit: ReportCellEdit_2) => any) | undefined;
+    "onCell-edit"?: ((edit: ReportCellEdit) => any) | undefined;
     "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
+    "onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
     }>, {
-    reload: () => Promise<void>;
-    print: () => Promise<void>;
-    exportAs: (format: string) => Promise<void>;
-    openPdfWindow: () => void;
-    gotoPage: (n: number) => void;
-    setParams: (values: Record<string, string>, opts?: {
-    reload?: boolean;
-    }) => Promise<void>;
-    checkPdfFont: () => Promise<PdfFontCheckResult>;
-    importExcel: (input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2) => Promise<ExcelImportResult | null>;
-    getPlan: () => RenderPlan | null;
-    getChanges: () => ReportCellEdit_2[];
     state: ComputedRef<MachReportState>;
+    checkPdfFont?(): Promise<PdfFontCheckResult>;
+    reload(): Promise<void>;
+    print(): Promise<void>;
+    exportAs(format: string): Promise<void> | void;
+    openPdfWindow(): void;
+    gotoPage(page: number): void;
+    setParams(values: Record<string, string>, opts?: {
+    reload?: boolean;
+    }): Promise<void> | void;
+    importExcel?(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2): Promise<ExcelImportResult | null>;
+    getPlan?(): RenderPlan | null;
+    getChanges?(): ReportCellEdit[];
+    getDifferences?(): ReportCellEdit[];
+    undo?(): Promise<boolean>;
+    redo?(): Promise<boolean>;
+    restoreChanges?(): Promise<boolean>;
+    getSelection?(): ReportCellSelection | null;
+    focusCell?(address: ReportCellAddress, extend?: boolean): Promise<boolean>;
+    focusField?(target: ReportFieldTarget): Promise<boolean>;
+    copySelection?(): string;
+    pasteSelection?(text: string): Promise<boolean>;
     }, {}, {}, {}, {
     editable: boolean | ReportEditingOptions;
     height: string;
@@ -781,10 +1106,16 @@ export declare const MachReportPreview: {
     showExport: boolean;
     showPrint: boolean;
     showPdfWindow: boolean;
+    showSettings: boolean;
     showParams: boolean;
+    toolbar: MachReportToolbarOptions;
+    interaction: ReportInteractionOptions;
+    preferences: ReportPreferencesOptions;
+    assets: AssetRenderOptions;
     messages: Partial<MachReportMessages>;
     excelImport: boolean | ExcelImportOptions_2;
     autoLoad: boolean;
+    emptyState: boolean | ReportEmptyState;
     preset: string;
     paramDefs: ReportParamDef[] | undefined;
     fetcher: PlanFetcher | null;
@@ -821,6 +1152,30 @@ showPdfWindow: {
 type: BooleanConstructor;
 default: undefined;
 };
+showSettings: {
+type: BooleanConstructor;
+default: undefined;
+};
+toolbar: {
+type: PropType<MachReportToolbarOptions>;
+default: undefined;
+};
+interaction: {
+type: PropType<ReportInteractionOptions>;
+default: undefined;
+};
+preferences: {
+type: PropType<ReportPreferencesOptions>;
+default: undefined;
+};
+assets: {
+type: PropType<AssetRenderOptions>;
+default: undefined;
+};
+emptyState: {
+type: PropType<boolean | ReportEmptyState>;
+default: boolean;
+};
 gapPx: {
 type: NumberConstructor;
 default: undefined;
@@ -858,37 +1213,48 @@ type: PropType<PlanFetcher | null>;
 default: null;
 };
 }>> & Readonly<{
+onWarning?: ((message: string) => any) | undefined;
 onError?: ((message: string, detail?: {
 code: string;
 cause?: unknown;
 } | undefined) => any) | undefined;
 onLoaded?: ((pageCount: number) => any) | undefined;
-onWarning?: ((message: string) => any) | undefined;
-"onCell-edit"?: ((edit: ReportCellEdit_2) => any) | undefined;
+"onCell-edit"?: ((edit: ReportCellEdit) => any) | undefined;
 "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
+"onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
 }>, {
-reload: () => Promise<void>;
-print: () => Promise<void>;
-exportAs: (format: string) => Promise<void>;
-openPdfWindow: () => void;
-gotoPage: (n: number) => void;
-setParams: (values: Record<string, string>, opts?: {
-reload?: boolean;
-}) => Promise<void>;
-checkPdfFont: () => Promise<PdfFontCheckResult>;
-importExcel: (input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2) => Promise<ExcelImportResult | null>;
-getPlan: () => RenderPlan | null;
-getChanges: () => ReportCellEdit_2[];
 state: ComputedRef<MachReportState>;
+checkPdfFont?(): Promise<PdfFontCheckResult>;
+reload(): Promise<void>;
+print(): Promise<void>;
+exportAs(format: string): Promise<void> | void;
+openPdfWindow(): void;
+gotoPage(page: number): void;
+setParams(values: Record<string, string>, opts?: {
+reload?: boolean;
+}): Promise<void> | void;
+importExcel?(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2): Promise<ExcelImportResult | null>;
+getPlan?(): RenderPlan | null;
+getChanges?(): ReportCellEdit[];
+getDifferences?(): ReportCellEdit[];
+undo?(): Promise<boolean>;
+redo?(): Promise<boolean>;
+restoreChanges?(): Promise<boolean>;
+getSelection?(): ReportCellSelection | null;
+focusCell?(address: ReportCellAddress, extend?: boolean): Promise<boolean>;
+focusField?(target: ReportFieldTarget): Promise<boolean>;
+copySelection?(): string;
+pasteSelection?(text: string): Promise<boolean>;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+warning: (message: string) => any;
 error: (message: string, detail?: {
 code: string;
 cause?: unknown;
 } | undefined) => any;
 loaded: (pageCount: number) => any;
-warning: (message: string) => any;
-"cell-edit": (edit: ReportCellEdit_2) => any;
+"cell-edit": (edit: ReportCellEdit) => any;
 "template-import": (result: ExcelImportResult) => any;
+"preferences-change": (preferences: Readonly<ReportPreviewPreferences>) => any;
 }, string, {
 editable: boolean | ReportEditingOptions;
 height: string;
@@ -899,15 +1265,22 @@ debug: boolean;
 showExport: boolean;
 showPrint: boolean;
 showPdfWindow: boolean;
+showSettings: boolean;
 showParams: boolean;
+toolbar: MachReportToolbarOptions;
+interaction: ReportInteractionOptions;
+preferences: ReportPreferencesOptions;
+assets: AssetRenderOptions;
 messages: Partial<MachReportMessages>;
 excelImport: boolean | ExcelImportOptions_2;
 autoLoad: boolean;
+emptyState: boolean | ReportEmptyState;
 preset: string;
 paramDefs: ReportParamDef[] | undefined;
 fetcher: PlanFetcher | null;
 }, {}, string, {}, { [K in keyof GlobalComponents]: GlobalComponents[K] }, { [K in keyof GlobalDirectives]: GlobalDirectives[K] }, string, ComponentProvideOptions> & VNodeProps & AllowedComponentProps & ComponentCustomProps & (new () => {
     $slots: {
+        settings?(_: {}): any;
         default?(_: {}): any;
     };
 });
@@ -937,6 +1310,10 @@ declare interface MachReportState {
     readonly saving?: boolean;
     readonly importing?: boolean;
     readonly dirty?: boolean;
+    readonly canUndo?: boolean;
+    readonly canRedo?: boolean;
+    readonly changeCount?: number;
+    readonly selection?: Readonly<ReportCellSelection> | null;
 }
 
 declare interface MachReportStateError {
@@ -959,11 +1336,65 @@ declare interface MachReportTheme {
     btnActiveBg: string;
 }
 
+declare interface MachReportToolbarOptions {
+    search?: boolean;
+    thumbnails?: boolean;
+    zoom?: boolean;
+    /** 编辑能力由 editable 授权；此项仅设置初始交互偏好，默认 true（兼容旧行为）。 */
+    editing?: boolean;
+    /** 导入能力由 excelImport 授权；此项仅设置初始交互偏好，默认 true。 */
+    excelImport?: boolean;
+    /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
+    exportFormats?: ReportExportFormat[];
+}
+
+declare interface OutputDiagnostic {
+    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
+    severity: "warning";
+    format: OutputFormat;
+    pageIndex: number;
+    componentIndex: number;
+    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
+    componentPath?: readonly number[];
+    kind: string;
+    nid?: string;
+    message: string;
+}
+
+declare interface OutputDiagnostic_2 {
+    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
+    severity: "warning";
+    format: OutputFormat_2;
+    pageIndex: number;
+    componentIndex: number;
+    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
+    componentPath?: readonly number[];
+    kind: string;
+    nid?: string;
+    message: string;
+}
+
+declare interface OutputDiagnosticOptions {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+}
+
+declare interface OutputDiagnosticOptions_2 {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic_2) => void;
+}
+
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+
+declare type OutputFormat_2 = "dom" | "canvas" | "pdf" | "xlsx";
+
 declare interface PaginateOptions {
     /** 每行额外占高（mm），压测专用钩子 */
     mmPerRow?: number;
     /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
     measurer?: TextMeasurer;
+    /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
+    maxPages?: number;
 }
 
 /** PDF 导出器：RenderPlan → PDF 字节；第二参数可上报非致命保真告警。 */
@@ -996,6 +1427,8 @@ declare interface PlanComponent {
     lines?: string[];
     richParagraphs?: RichParagraph[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid;
     table?: PlanTableFragment;
     style?: ComponentStyle;
@@ -1017,6 +1450,8 @@ declare interface PlanComponent_2 {
     lines?: string[];
     richParagraphs?: RichParagraph_2[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid_2;
     table?: PlanTableFragment_2;
     style?: ComponentStyle_2;
@@ -1038,6 +1473,8 @@ declare interface PlanComponent_3 {
     lines?: string[];
     richParagraphs?: RichParagraph_3[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid_3;
     table?: PlanTableFragment_3;
     style?: ComponentStyle_3;
@@ -1104,6 +1541,8 @@ declare interface PlanTableFragment {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & { rowKey?: string | number };
 }
 
 /** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
@@ -1117,6 +1556,10 @@ declare interface PlanTableFragment_2 {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource_2, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 /** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
@@ -1130,6 +1573,10 @@ declare interface PlanTableFragment_3 {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource_3, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 /** 预取组件分片（路由 hover / 空闲时调用，正式渲染零等待） */
@@ -1157,12 +1604,14 @@ declare interface ReportCellAddress_2 {
 }
 
 declare interface ReportCellContext {
-    address: ReportCellAddress;
+    address: ReportCellAddress_2;
     cell: Readonly<GridCell_2>;
     component: Readonly<PlanComponent_2>;
-    value: ReportCellValue;
+    value: ReportCellValue_2;
     valueType: ReportCellValueType;
-    table?: ReportCellTableIdentity;
+    table?: ReportCellTableIdentity_2;
+    /** Stable business identity. Physical row indices must never be used as database keys. */
+    source?: Readonly<ReportCellSource_2>;
     editable: boolean;
     readOnlyReason?: ReportCellReadOnlyReason;
 }
@@ -1170,6 +1619,7 @@ declare interface ReportCellContext {
 declare interface ReportCellEdit {
     address: ReportCellAddress;
     table?: ReportCellTableIdentity;
+    source?: Readonly<ReportCellSource>;
     previousValue: ReportCellValue;
     previousText: string;
     value: ReportCellValue;
@@ -1179,6 +1629,7 @@ declare interface ReportCellEdit {
 declare interface ReportCellEdit_2 {
     address: ReportCellAddress_2;
     table?: ReportCellTableIdentity_2;
+    source?: Readonly<ReportCellSource_2>;
     previousValue: ReportCellValue_2;
     previousText: string;
     value: ReportCellValue_2;
@@ -1187,11 +1638,43 @@ declare interface ReportCellEdit_2 {
 
 declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
 
+declare interface ReportCellSelection {
+    anchor: ReportCellAddress;
+    focus: ReportCellAddress;
+}
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource_2 {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource_3 {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
 declare interface ReportCellTableIdentity {
     id: string;
     /** 逻辑表行索引；跨分页的同一行保持不变。 */
     rowIndex: number;
-    role: PlanTableFragment_2["role"];
+    role: PlanTableFragment["role"];
     columnKey?: string;
 }
 
@@ -1199,7 +1682,7 @@ declare interface ReportCellTableIdentity_2 {
     id: string;
     /** 逻辑表行索引；跨分页的同一行保持不变。 */
     rowIndex: number;
-    role: PlanTableFragment["role"];
+    role: PlanTableFragment_2["role"];
     columnKey?: string;
 }
 
@@ -1215,25 +1698,69 @@ declare interface ReportDefinition {
     /** 静态数据；load 存在时优先使用 load 的结果。 */
     datasets?: DatasetRows;
     load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
+    /** 可选统一适配器；load 存在时仍优先 load，兼容已有定义。 */
+    provider?: ReportProvider;
+    /** 可选业务数据契约；声明的数据集缺失或字段不合法时，在分页前给出结构化错误。 */
+    dataSchema?: Record<string, DatasetContract>;
+    dataValidation?: Pick<DatasetValidationOptions, "maxRows" | "maxCells" | "maxIssues">;
     /** 覆盖模板参数定义；动态模板应在此声明查询面板元数据，避免查询前先请求模板。 */
     params?: ReportParamDef[];
     pagination?: PaginateOptions;
 }
 
+declare interface ReportDiagnostic { code: string; message: string; path?: string; severity: "warning" | "error" | "info" }
+
+declare interface ReportEditBatch {
+    /** Idempotency identity; the server should bind it to the exact payload. */
+    requestId: string;
+    edits: ReportCellEdit_2[];
+}
+
+declare interface ReportEditConflict {
+    source?: Readonly<ReportCellSource_2>;
+    address?: ReportCellAddress_2;
+    message: string;
+    currentValue?: ReportCellValue_2;
+    revision?: string | number;
+}
+
 /** Opt in with true for local drafts, or provide host validation and persistence. */
 declare interface ReportEditingOptions {
     canEdit?(context: ReportCellContext): boolean;
     /** Return an error message or throw to reject the edit. */
-    validate?(edit: Readonly<ReportCellEdit>, operation: ReportEditOperation): void | string | Promise<void | string>;
+    validate?(edit: Readonly<ReportCellEdit_2>, operation: ReportEditOperation): void | string | Promise<void | string>;
     /** Called before applying the change. A rejection leaves the current report untouched. */
-    save?(edit: Readonly<ReportCellEdit>, operation: ReportEditOperation): void | Promise<void>;
+    save?(edit: Readonly<ReportCellEdit_2>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
+    /** Must commit all edits in one server transaction. Required for multi-cell persisted edits. */
+    saveBatch?(batch: Readonly<ReportEditBatch>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
+    /** Restrict persistence to plans that supply stable datasetId/rowKey/field metadata. */
+    requireSource?: boolean;
 }
 
 declare interface ReportEditOperation {
     /** Reload, another import or unmount aborts the operation. Save adapters should forward this signal. */
     signal: AbortSignal;
+    requestId?: string;
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+
+declare interface ReportEditResult {
+    /** A successful result may advance concurrency tokens for the affected dataset. */
+    revision?: string | number;
+    sourceToken?: string;
+    /** Any conflict rejects the entire client batch. A server must also transact atomically. */
+    conflicts?: readonly ReportEditConflict[];
 }
 
+/** 报表含表头但业务行为空时，由接入方明确声明；组件不推测业务数据。 */
+declare interface ReportEmptyState {
+    title?: string;
+    description?: string;
+}
+
+/** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
+declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -1246,6 +1773,35 @@ declare interface ReportFetchInput {
     signal?: AbortSignal;
     /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
     onWarning?: (message: string) => void;
+    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
+}
+
+declare interface ReportFieldContract {
+    field: string;
+    label?: string;
+    type: "text" | "number" | "boolean" | "date" | "decimal";
+    required?: boolean;
+    nullable?: boolean;
+    enum?: readonly (string | number | boolean)[];
+    min?: number; max?: number;
+    minLength?: number; maxLength?: number;
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    unit?: string;
+}
+
+declare interface ReportFieldTarget {
+    field: string;
+    datasetId?: string;
+    rowKey?: string | number;
+}
+
+declare interface ReportInteractionOptions {
+    /** Screen-only frozen panes; exported geometry is unchanged. */
+    freezeHeaders?: boolean;
+    /** Leading identity columns, from 0 to 20. */
+    frozenColumns?: number;
+    /** Show workbook sheets / report sections when available. Default true. */
+    navigation?: boolean;
 }
 
 /** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
@@ -1267,6 +1823,11 @@ declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
 }
 
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
@@ -1284,10 +1845,69 @@ declare interface ReportParamDef_2 {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
+}
+
+declare interface ReportParamIssue { code: ReportParamIssueCode; path: string; field: string; message: string }
+
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+
+declare interface ReportPreferencesAdapter {
+    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
+    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
+    remove?(key: string): void | Promise<void>;
+}
+
+declare interface ReportPreferencesOptions {
+    /** Host-scoped key; do not share one key between unrelated users/tenants. */
+    key: string;
+    adapter: ReportPreferencesAdapter;
+}
+
+declare type ReportPreviewPreferences = Record<ReportPreviewTool, boolean>;
+
+declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
+
+/** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
+declare interface ReportProvider {
+    query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
+    save?(input: ReportSaveInput): ReportSaveResult | Promise<ReportSaveResult>;
+    export?(input: ReportProviderExportInput): ReportProviderExportResult | Promise<ReportProviderExportResult>;
+    templates?: ReportTemplateProvider;
+}
+
+declare interface ReportProviderExportInput extends ReportLoadContext { format: "pdf" | "xlsx" }
+
+declare interface ReportProviderExportResult { bytes: Uint8Array; contentType: string; fileName?: string; diagnostics?: ReportDiagnostic[] }
+
+declare interface ReportQueryResult {
+    datasets: DatasetRows;
+    revision?: string;
+    sourceToken?: string;
+    diagnostics?: ReportDiagnostic[];
 }
 
 declare type ReportRegistry = Record<string, ReportDefinition>;
 
+declare interface ReportSaveInput extends ReportLoadContext {
+    requestId: string;
+    expectedRevision?: string;
+    sourceToken?: string;
+    edits: readonly ReportCellEdit[];
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+
+declare interface ReportSaveResult {
+    revision: string;
+    sourceToken?: string;
+    conflicts?: Array<{ editIndex: number; code: string; message: string }>;
+    diagnostics?: ReportDiagnostic[];
+}
+
 declare interface ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
@@ -1302,8 +1922,26 @@ declare interface ReportTemplate_2 {
     pages: TemplatePage_2[];
 }
 
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+declare interface ReportTemplateDocument {
+    schemaVersion: "1.0";
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate;
+}
+
 declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
 
+declare interface ReportTemplateProvider {
+    list(context: { signal?: AbortSignal }): Promise<ReportTemplateSummary[]>;
+    get(id: string, context: { signal?: AbortSignal }): Promise<ReportTemplateDocument | undefined>;
+}
+
+declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -1412,7 +2050,9 @@ declare interface TemplatePage_2 {
 
 declare interface TextMeasureOptions {
     fontSizePt: number;
+    fontFamily?: string;
     bold?: boolean;
+    italic?: boolean;
     letterSpacingPt?: number;
 }
 
@@ -1429,7 +2069,7 @@ declare interface TextMeasurer {
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
  */
-declare interface XlsxRenderOptions {
+declare interface XlsxRenderOptions extends OutputDiagnosticOptions_2 {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */