@agile-team/mach-report 2.4.1 → 2.6.1

package/dist/vue/index.d.ts

@@ -48,6 +48,31 @@ 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;
+};
 /** 页间距（px）；不传走配置中心 */
 gapPx: {
 type: NumberConstructor;
@@ -91,26 +116,49 @@ type: PropType<PlanFetcher | null>;
 default: null;
 };
 }>, {
-reload: typeof reload;
-print: typeof print_2;
-exportAs: typeof exportAs;
-openPdfWindow: typeof openPdfWindow;
-gotoPage: typeof gotoPage;
-setParams: typeof setParams;
-checkPdfFont: typeof checkPdfFont;
-importExcel: typeof importExcel;
-getPlan: typeof getPlan;
-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
+/**
+* ReportPreview：接收报表 ID 和 PlanFetcher，预览与导出 RenderPlan。
+*
+* 职责编排（实现在 composables，本文件保持薄壳）：
+* - usePageWindow：视口虚拟化（自然坐标系 + gap）
+* - useZoom：transform: scale 缩放（零重排；Ctrl+滚轮/键盘 ±/持久化记忆）
+* - usePrintExport：打印/导出/PDF 窗口（流式打印 + named pages）
+* - useReportSearch/useThumbs/useDebugPanel：搜索（防抖+高亮）/缩略图/调试面板
+* - 配置优先级：props > provideMachReportConfig 叠加 > preset > 插件 config.defaults > 内置缺省
+*/
+?: boolean;
+}): Promise<void> | void;
+importExcel?(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions): Promise<ExcelImportResult | null>;
+getPlan?(): RenderPlan | null;
+getChanges?(): ReportCellEdit_2[];
+getDifferences?(): ReportCellEdit_2[];
+undo?(): Promise<boolean>;
+redo?(): Promise<boolean>;
+restoreChanges?(): Promise<boolean>;
+getSelection?(): ReportCellSelection | null;
+focusCell?(address: ReportCellAddress_2, 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;
 "template-import": (result: ExcelImportResult) => any;
+"preferences-change": (preferences: Readonly<ReportPreviewPreferences>) => any;
 }, string, PublicProps, Readonly<ExtractPropTypes<    {
 reportId: {
 type: PropType<string | string[] | null>;
@@ -141,6 +189,31 @@ 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;
+};
 /** 页间距（px）；不传走配置中心 */
 gapPx: {
 type: NumberConstructor;
@@ -184,14 +257,15 @@ 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;
 "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
+"onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
 }>, {
 editable: boolean | ReportEditingOptions;
 height: string;
@@ -202,14 +276,181 @@ 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;
 autoLoad: boolean;
+emptyState: boolean | ReportEmptyState;
 preset: string;
 paramDefs: ReportParamDef[] | undefined;
 fetcher: PlanFetcher | null;
 }, {}, {}, {}, string, ComponentProvideOptions, true, {
+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
+/**
+* ReportPreview：接收报表 ID 和 PlanFetcher，预览与导出 RenderPlan。
+*
+* 职责编排（实现在 composables，本文件保持薄壳）：
+* - usePageWindow：视口虚拟化（自然坐标系 + gap）
+* - useZoom：transform: scale 缩放（零重排；Ctrl+滚轮/键盘 ±/持久化记忆）
+* - usePrintExport：打印/导出/PDF 窗口（流式打印 + named pages）
+* - useReportSearch/useThumbs/useDebugPanel：搜索（防抖+高亮）/缩略图/调试面板
+* - 配置优先级：props > provideMachReportConfig 叠加 > preset > 插件 config.defaults > 内置缺省
+*/
+?: 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
+/**
+* ReportPreview：接收报表 ID 和 PlanFetcher，预览与导出 RenderPlan。
+*
+* 职责编排（实现在 composables，本文件保持薄壳）：
+* - usePageWindow：视口虚拟化（自然坐标系 + gap）
+* - useZoom：transform: scale 缩放（零重排；Ctrl+滚轮/键盘 ±/持久化记忆）
+* - usePrintExport：打印/导出/PDF 窗口（流式打印 + named pages）
+* - useReportSearch/useThumbs/useDebugPanel：搜索（防抖+高亮）/缩略图/调试面板
+* - 配置优先级：props > provideMachReportConfig 叠加 > preset > 插件 config.defaults > 内置缺省
+*/
+?: 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;
@@ -234,6 +475,12 @@ declare type __VLS_Props = {
     };
     thumbsVisible: boolean;
     showImport?: boolean;
+    showSearch?: boolean;
+    showThumbnails?: boolean;
+    showZoom?: boolean;
+    exportFormats?: readonly ReportExportFormat[];
+    showSettings?: boolean;
+    settingsOpen?: boolean;
     busy?: boolean;
 };
 
@@ -243,14 +490,177 @@ declare type __VLS_Props_2 = {
     messages: MachReportMessages;
     /** 触发过查询后才开始必填提示（避免首屏一片红） */
     attempted: boolean;
+    issues?: readonly ReportParamIssue[];
 };
 
 declare function __VLS_template(): {
     attrs: Partial<{}>;
     slots: {
+        settings?(_: {}): any;
         default?(_: {}): any;
     };
     refs: {
+        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
+        /**
+        * ReportPreview：接收报表 ID 和 PlanFetcher，预览与导出 RenderPlan。
+        *
+        * 职责编排（实现在 composables，本文件保持薄壳）：
+        * - usePageWindow：视口虚拟化（自然坐标系 + gap）
+        * - useZoom：transform: scale 缩放（零重排；Ctrl+滚轮/键盘 ±/持久化记忆）
+        * - usePrintExport：打印/导出/PDF 窗口（流式打印 + named pages）
+        * - useReportSearch/useThumbs/useDebugPanel：搜索（防抖+高亮）/缩略图/调试面板
+        * - 配置优先级：props > provideMachReportConfig 叠加 > preset > 插件 config.defaults > 内置缺省
+        */
+        ?: 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
+        /**
+        * ReportPreview：接收报表 ID 和 PlanFetcher，预览与导出 RenderPlan。
+        *
+        * 职责编排（实现在 composables，本文件保持薄壳）：
+        * - usePageWindow：视口虚拟化（自然坐标系 + gap）
+        * - useZoom：transform: scale 缩放（零重排；Ctrl+滚轮/键盘 ±/持久化记忆）
+        * - usePrintExport：打印/导出/PDF 窗口（流式打印 + named pages）
+        * - useReportSearch/useThumbs/useDebugPanel：搜索（防抖+高亮）/缩略图/调试面板
+        * - 配置优先级：props > provideMachReportConfig 叠加 > preset > 插件 config.defaults > 内置缺省
+        */
+        ?: 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;
@@ -267,6 +677,25 @@ declare type __VLS_WithTemplateSlots<T, S> = T & {
     };
 };
 
+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;
+}
+
 /** 供 HTML/Word 导出的完整文档；打印路径逐页渲染，避免预先生成所有页。 */
 export declare function buildPrintDocument(p: RenderPlan): PrintHtmlResult;
 
@@ -280,9 +709,6 @@ export declare function buildWordHtml(p: RenderPlan): {
     filename: string;
 };
 
-/** 检查失败只影响 PDF 诊断，不阻塞预览或其它输出。 */
-declare function checkPdfFont(): Promise<PdfFontCheckResult>;
-
 /**
  * 列值格式化（声明式、JSON 可序列化）。
  * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
@@ -346,9 +772,17 @@ declare type ColumnFormat_3 = {
     pattern?: string;
 };
 
-declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+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_2 =
+declare type ComponentKind =
 | "text"
 | "image"
 | "barcode"
@@ -358,6 +792,8 @@ declare type ComponentKind_2 =
 | "rect"
 | "ellipse";
 
+declare type ComponentKind_2 = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
 declare type ComponentKind_3 = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 
 declare interface ComponentStyle {
@@ -454,8 +890,20 @@ export declare function createFetchRequest(options?: FetchRequestOptions): HostR
  */
 export declare function createLocalFetcher(entries: Record<string, LocalTemplateEntry> | ReportRegistry): PlanFetcher;
 
+/** Explicit persistence bridge. Merely registering ReportProvider never enables editing or saving. */
+export declare function createProviderEditing(provider: ReportProvider, options: ProviderEditingOptions): ReportEditingOptions;
+
+/** Optional browser convenience adapter. Access errors are handled by the preview. */
+export declare function createReportStoragePreferences(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">): ReportPreferencesAdapter;
+
+declare type Current<T> = T | (() => T);
+
+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 }
+
 export declare const DEFAULT_MESSAGES: MachReportMessages;
 
 export declare const DEFAULT_THEME: MachReportTheme;
@@ -569,8 +1017,6 @@ declare interface ExcelImportResult_2 {
     sheets: ExcelImportedSheet_2[];
 }
 
-declare function exportAs(format: string): Promise<void>;
-
 export declare interface FetchRequestOptions {
     /** 网关前缀（默认空 = 同源） */
     baseUrl?: string;
@@ -581,9 +1027,7 @@ export declare interface FetchRequestOptions {
     timeoutMs?: number;
 }
 
-declare function getPlan(): RenderPlan | null;
-
-declare function gotoPage(n: number): void;
+declare function focusInvalid(): void;
 
 declare interface GridCell {
     text?: string;
@@ -596,6 +1040,7 @@ declare interface GridCell {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -615,6 +1060,7 @@ declare interface GridCell_2 {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource_2;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent_2[];
@@ -634,6 +1080,7 @@ declare interface GridCell_3 {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource_3;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent_3[];
@@ -651,16 +1098,15 @@ export declare type HostRequest = (config: {
     signal?: AbortSignal;
 }) => Promise<unknown>;
 
-/** Import is an explicit local replacement; business mapping/storage remains in the host. */
-declare function importExcel(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions): Promise<ExcelImportResult | null>;
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
 
 export declare function joinReportIds(reportId: ReportIdInput): string;
 
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
-declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
+declare type ListAlignment = NonNullable<ComponentStyle_2["align"]> | "auto";
 
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
-declare type ListAlignment_2 = NonNullable<ComponentStyle_2["align"]> | "auto";
+declare type ListAlignment_2 = NonNullable<ComponentStyle["align"]> | "auto";
 
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
 declare type ListAlignment_3 = NonNullable<ComponentStyle_3["align"]> | "auto";
@@ -669,13 +1115,13 @@ declare interface ListColumn {
     header: string;
     field: string;
     widthMm: number;
-    style?: ComponentStyle;
+    style?: ComponentStyle_2;
     /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
     align?: ListAlignment;
     /** 独立的表头对齐，不改变内容对齐。 */
-    headerAlign?: ComponentStyle["align"];
+    headerAlign?: ComponentStyle_2["align"];
     /** 独立的表头样式，优先于列表级表头样式。 */
-    headerStyle?: ComponentStyle;
+    headerStyle?: ComponentStyle_2;
     /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
@@ -683,20 +1129,22 @@ declare interface ListColumn {
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
-    valueType?: GridCell["valueType"];
+    valueType?: GridCell_2["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 declare interface ListColumn_2 {
     header: string;
     field: string;
     widthMm: number;
-    style?: ComponentStyle_2;
+    style?: ComponentStyle;
     /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
     align?: ListAlignment_2;
     /** 独立的表头对齐，不改变内容对齐。 */
-    headerAlign?: ComponentStyle_2["align"];
+    headerAlign?: ComponentStyle["align"];
     /** 独立的表头样式，优先于列表级表头样式。 */
-    headerStyle?: ComponentStyle_2;
+    headerStyle?: ComponentStyle;
     /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
     format?: ColumnFormat_2;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
@@ -704,7 +1152,9 @@ declare interface ListColumn_2 {
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
-    valueType?: GridCell_2["valueType"];
+    valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 declare interface ListColumn_3 {
@@ -726,6 +1176,8 @@ declare interface ListColumn_3 {
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
     valueType?: GridCell_3["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 declare interface ListComponent {
@@ -739,6 +1191,10 @@ declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -749,8 +1205,10 @@ declare interface ListComponent {
     /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
     align?: ListAlignment;
     /** 表头默认对齐，列配置可覆盖。 */
-    headerAlign?: ComponentStyle["align"];
-    headerStyle?: ComponentStyle;
+    headerAlign?: ComponentStyle_2["align"];
+    headerStyle?: ComponentStyle_2;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid_2;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -769,6 +1227,10 @@ declare interface ListComponent_2 {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn_2[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -779,8 +1241,10 @@ declare interface ListComponent_2 {
     /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
     align?: ListAlignment_2;
     /** 表头默认对齐，列配置可覆盖。 */
-    headerAlign?: ComponentStyle_2["align"];
-    headerStyle?: ComponentStyle_2;
+    headerAlign?: ComponentStyle["align"];
+    headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy_2;
@@ -799,6 +1263,10 @@ declare interface ListComponent_3 {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn_3[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -811,6 +1279,8 @@ declare interface ListComponent_3 {
     /** 表头默认对齐，列配置可覆盖。 */
     headerAlign?: ComponentStyle_3["align"];
     headerStyle?: ComponentStyle_3;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid_3;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy_3;
@@ -820,7 +1290,7 @@ declare interface ListComponent_3 {
 
 declare type ListGrandTotal = boolean | {
     label?: string;
-    style?: ComponentStyle;
+    style?: ComponentStyle_2;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
 };
@@ -829,7 +1299,7 @@ declare type ListGrandTotal_2 =
 | boolean
 | {
     label?: string;
-    style?: ComponentStyle_2;
+    style?: ComponentStyle;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
 };
@@ -847,10 +1317,10 @@ declare interface ListGroupBy {
     field: string;
     /** 组头文案模板，{value} 占位（默认 "{value}"） */
     headerTemplate?: string;
-    headerStyle?: ComponentStyle;
+    headerStyle?: ComponentStyle_2;
     /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
     subtotal?: string[];
-    subtotalStyle?: ComponentStyle;
+    subtotalStyle?: ComponentStyle_2;
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
@@ -862,10 +1332,10 @@ declare interface ListGroupBy_2 {
     field: string;
     /** 组头文案模板，{value} 占位（默认 "{value}"） */
     headerTemplate?: string;
-    headerStyle?: ComponentStyle_2;
+    headerStyle?: ComponentStyle;
     /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
     subtotal?: string[];
-    subtotalStyle?: ComponentStyle_2;
+    subtotalStyle?: ComponentStyle;
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
@@ -937,6 +1407,15 @@ export declare interface MachReportController {
     /** Copies prevent consumers from mutating the preview's current snapshot. */
     getPlan?(): RenderPlan | null;
     getChanges?(): ReportCellEdit_2[];
+    getDifferences?(): ReportCellEdit_2[];
+    undo?(): Promise<boolean>;
+    redo?(): Promise<boolean>;
+    restoreChanges?(): Promise<boolean>;
+    getSelection?(): ReportCellSelection | null;
+    focusCell?(address: ReportCellAddress_2, extend?: boolean): Promise<boolean>;
+    focusField?(target: ReportFieldTarget): Promise<boolean>;
+    copySelection?(): string;
+    pasteSelection?(text: string): Promise<boolean>;
 }
 
 /** defaults 层可配置项（全部可选，均有内置缺省） */
@@ -944,6 +1423,13 @@ export 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 */
@@ -994,6 +1480,15 @@ export declare interface MachReportHandle extends MachReportController {
     importExcel(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions): Promise<ExcelImportResult | null>;
     getPlan(): RenderPlan | null;
     getChanges(): ReportCellEdit_2[];
+    getDifferences(): ReportCellEdit_2[];
+    undo(): Promise<boolean>;
+    redo(): Promise<boolean>;
+    restoreChanges(): Promise<boolean>;
+    getSelection(): ReportCellSelection | null;
+    focusCell(address: ReportCellAddress_2, extend?: boolean): Promise<boolean>;
+    focusField(target: ReportFieldTarget): Promise<boolean>;
+    copySelection(): string;
+    pasteSelection(text: string): Promise<boolean>;
 }
 
 /** 日志通道（默认 console；可注入 noop 静默或上报 collector） */
@@ -1044,6 +1539,11 @@ export declare interface MachReportMessages {
     reset: string;
     /** 必填缺失提示（{label} 占位） */
     paramRequired: string;
+    paramInvalid?: string;
+    paramPrompt?: string;
+    paramPromptDescription?: string;
+    paramSelectPlaceholder?: string;
+    paramTextPlaceholder?: string;
     /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
     searching?: string;
     importExcel?: string;
@@ -1054,6 +1554,51 @@ export 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;
 }
 
 /**
@@ -1121,6 +1666,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;
@@ -1158,37 +1727,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;
     "onTemplate-import"?: ((result: ExcelImportResult_2) => 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_2 | 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_2 | null>;
+    getPlan?(): RenderPlan | null;
+    getChanges?(): ReportCellEdit_2[];
+    getDifferences?(): ReportCellEdit_2[];
+    undo?(): Promise<boolean>;
+    redo?(): Promise<boolean>;
+    restoreChanges?(): Promise<boolean>;
+    getSelection?(): ReportCellSelection | null;
+    focusCell?(address: ReportCellAddress_2, 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;
     "template-import": (result: ExcelImportResult_2) => any;
+    "preferences-change": (preferences: Readonly<ReportPreviewPreferences>) => any;
     }, PublicProps, {
     editable: boolean | ReportEditingOptions;
     height: string;
@@ -1199,14 +1779,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;
@@ -1247,6 +1972,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;
@@ -1284,28 +2033,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;
     "onTemplate-import"?: ((result: ExcelImportResult_2) => 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_2 | 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_2 | null>;
+    getPlan?(): RenderPlan | null;
+    getChanges?(): ReportCellEdit_2[];
+    getDifferences?(): ReportCellEdit_2[];
+    undo?(): Promise<boolean>;
+    redo?(): Promise<boolean>;
+    restoreChanges?(): Promise<boolean>;
+    getSelection?(): ReportCellSelection | null;
+    focusCell?(address: ReportCellAddress_2, extend?: boolean): Promise<boolean>;
+    focusField?(target: ReportFieldTarget): Promise<boolean>;
+    copySelection?(): string;
+    pasteSelection?(text: string): Promise<boolean>;
     }, {}, {}, {}, {
     editable: boolean | ReportEditingOptions;
     height: string;
@@ -1316,10 +2075,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;
@@ -1356,6 +2121,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;
@@ -1393,37 +2182,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;
 "onTemplate-import"?: ((result: ExcelImportResult_2) => 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_2 | 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_2 | null>;
+getPlan?(): RenderPlan | null;
+getChanges?(): ReportCellEdit_2[];
+getDifferences?(): ReportCellEdit_2[];
+undo?(): Promise<boolean>;
+redo?(): Promise<boolean>;
+restoreChanges?(): Promise<boolean>;
+getSelection?(): ReportCellSelection | null;
+focusCell?(address: ReportCellAddress_2, 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;
 "template-import": (result: ExcelImportResult_2) => any;
+"preferences-change": (preferences: Readonly<ReportPreviewPreferences>) => any;
 }, string, {
 editable: boolean | ReportEditingOptions;
 height: string;
@@ -1434,15 +2234,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;
     };
 });
@@ -1472,6 +2279,10 @@ export 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;
 }
 
 export declare interface MachReportStateError {
@@ -1494,9 +2305,62 @@ export declare interface MachReportTheme {
     btnActiveBg: string;
 }
 
+export declare interface MachReportToolbarOptions {
+    search?: boolean;
+    thumbnails?: boolean;
+    zoom?: boolean;
+    /** 编辑能力由 editable 授权；此项仅设置初始交互偏好，默认 true（兼容旧行为）。 */
+    editing?: boolean;
+    /** 导入能力由 excelImport 授权；此项仅设置初始交互偏好，默认 true。 */
+    excelImport?: boolean;
+    /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
+    exportFormats?: ReportExportFormat[];
+}
+
 export declare function normalizeReportIds(reportId: ReportIdInput): string[];
 
-declare function openPdfWindow(): void;
+/** Workers preserve stable error codes, not JavaScript class identity. Only known codes cross the UI boundary. */
+export declare function normalizeReportLoadError(error: unknown): MachReportError;
+
+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 PageWindow {
     start: number;
@@ -1510,6 +2374,8 @@ declare interface PaginateOptions {
     mmPerRow?: number;
     /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
     measurer?: TextMeasurer;
+    /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
+    maxPages?: number;
 }
 
 /** PDF 导出器：RenderPlan → PDF 字节；第二参数可上报非致命保真告警。 */
@@ -1542,6 +2408,8 @@ declare interface PlanComponent {
     lines?: string[];
     richParagraphs?: RichParagraph[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid;
     table?: PlanTableFragment;
     style?: ComponentStyle;
@@ -1563,6 +2431,8 @@ declare interface PlanComponent_2 {
     lines?: string[];
     richParagraphs?: RichParagraph_2[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid_2;
     table?: PlanTableFragment_2;
     style?: ComponentStyle_2;
@@ -1584,6 +2454,8 @@ declare interface PlanComponent_3 {
     lines?: string[];
     richParagraphs?: RichParagraph_3[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid_3;
     table?: PlanTableFragment_3;
     style?: ComponentStyle_3;
@@ -1640,7 +2512,7 @@ declare interface PlanPage {
     marginBottomMm?: number;
     marginLeftMm?: number;
     marginRightMm?: number;
-    components: PlanComponent_2[];
+    components: PlanComponent[];
 }
 
 /** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
@@ -1654,6 +2526,8 @@ declare interface PlanTableFragment {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & { rowKey?: string | number };
 }
 
 /** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
@@ -1667,6 +2541,10 @@ declare interface PlanTableFragment_2 {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource_2, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 /** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
@@ -1680,10 +2558,12 @@ declare interface PlanTableFragment_3 {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource_3, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
-declare function print_2(): Promise<void>;
-
 declare interface PrintHtmlResult {
     head: string;
     pageChunks: string[];
@@ -1705,13 +2585,24 @@ export declare function printPlans(plans: RenderPlan[], options?: {
  */
 export declare function provideMachReportConfig(overlay: MachReportConfigInput | MachReportDefaults): void;
 
-declare function reload(): Promise<void>;
+export declare interface ProviderEditingOptions extends Pick<ReportEditingOptions, "canEdit" | "validate" | "requireSource"> {
+    reportId: Current<string>;
+    params?: Current<Record<string, string>>;
+    /** Getters are useful when query metadata is held by the host. Otherwise stable cell sources are used. */
+    expectedRevision?: Current<string | undefined>;
+    sourceToken?: Current<string | undefined>;
+    onDiagnostic?(diagnostic: ReportDiagnostic): void;
+}
 
 declare interface RenderPlan {
     schemaVersion: string;
     pages: PlanPage[];
 }
 
+export declare const REPORT_EXPORT_FORMATS: readonly ReportExportFormat[];
+
+export declare const REPORT_PREVIEW_TOOLS: readonly ["search", "thumbnails", "zoom", ...ReportExportFormat[], "print", "pdfWindow", "editing", "import"];
+
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 declare interface ReportCellAddress {
     pageIndex: number;
@@ -1730,11 +2621,13 @@ declare interface ReportCellAddress_2 {
 
 declare interface ReportCellContext {
     address: ReportCellAddress;
-    cell: Readonly<GridCell>;
-    component: Readonly<PlanComponent>;
+    cell: Readonly<GridCell_2>;
+    component: Readonly<PlanComponent_2>;
     value: ReportCellValue;
     valueType: ReportCellValueType;
     table?: ReportCellTableIdentity;
+    /** Stable business identity. Physical row indices must never be used as database keys. */
+    source?: Readonly<ReportCellSource_2>;
     editable: boolean;
     readOnlyReason?: ReportCellReadOnlyReason;
 }
@@ -1742,6 +2635,7 @@ declare interface ReportCellContext {
 declare interface ReportCellEdit {
     address: ReportCellAddress;
     table?: ReportCellTableIdentity;
+    source?: Readonly<ReportCellSource_2>;
     previousValue: ReportCellValue;
     previousText: string;
     value: ReportCellValue;
@@ -1751,6 +2645,7 @@ declare interface ReportCellEdit {
 declare interface ReportCellEdit_2 {
     address: ReportCellAddress_2;
     table?: ReportCellTableIdentity_2;
+    source?: Readonly<ReportCellSource>;
     previousValue: ReportCellValue_2;
     previousText: string;
     value: ReportCellValue_2;
@@ -1759,11 +2654,43 @@ declare interface ReportCellEdit_2 {
 
 declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
 
+export declare interface ReportCellSelection {
+    anchor: ReportCellAddress_2;
+    focus: ReportCellAddress_2;
+}
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+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["role"];
+    role: PlanTableFragment_2["role"];
     columnKey?: string;
 }
 
@@ -1771,7 +2698,7 @@ declare interface ReportCellTableIdentity_2 {
     id: string;
     /** 逻辑表行索引；跨分页的同一行保持不变。 */
     rowIndex: number;
-    role: PlanTableFragment_2["role"];
+    role: PlanTableFragment["role"];
     columnKey?: string;
 }
 
@@ -1779,7 +2706,7 @@ declare type ReportCellValue = string | number | boolean | null;
 
 declare type ReportCellValue_2 = string | number | boolean | null;
 
-declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
+declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
 
 declare interface ReportDefinition {
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
@@ -1787,25 +2714,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[];
+}
+
+declare interface ReportEditConflict {
+    source?: Readonly<ReportCellSource_2>;
+    address?: ReportCellAddress;
+    message: string;
+    currentValue?: ReportCellValue;
+    revision?: string | number;
+}
+
 /** Opt in with true for local drafts, or provide host validation and persistence. */
 export 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>;
     /** 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>, 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;
 }
 
 export 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[];
+}
+
+/** 报表含表头但业务行为空时，由接入方明确声明；组件不推测业务数据。 */
+export declare interface ReportEmptyState {
+    title?: string;
+    description?: string;
 }
 
+/** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
+export declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -1818,10 +2789,39 @@ 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;
+}
+
+export declare interface ReportFieldTarget {
+    field: string;
+    datasetId?: string;
+    rowKey?: string | number;
 }
 
 export declare type ReportIdInput = string | string[] | null | undefined;
 
+export 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;
+}
+
 /** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
 declare interface ReportLoadContext {
     reportId: string;
@@ -1841,6 +2841,11 @@ declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
 }
 
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
@@ -1858,6 +2863,11 @@ declare interface ReportParamDef_2 {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
 }
 
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
@@ -1875,9 +2885,20 @@ declare interface ReportParamDef_3 {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
 }
 
-export declare const ReportParamPanel: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+declare interface ReportParamIssue { code: ReportParamIssueCode; path: string; field: string; message: string }
+
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+
+export declare const ReportParamPanel: DefineComponent<__VLS_Props_2, {
+focusInvalid: typeof focusInvalid;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 reset: () => any;
 query: () => any;
 "update:modelValue": (value: Record<string, string>) => any;
@@ -1885,12 +2906,69 @@ query: () => any;
 onReset?: (() => any) | undefined;
 onQuery?: (() => any) | undefined;
 "onUpdate:modelValue"?: ((value: Record<string, string>) => any) | undefined;
-}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
+root: HTMLDivElement;
+}, HTMLDivElement>;
+
+export 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>;
+}
+
+export declare interface ReportPreferencesOptions {
+    /** Host-scoped key; do not share one key between unrelated users/tenants. */
+    key: string;
+    adapter: ReportPreferencesAdapter;
+}
 
 export declare const ReportPreview: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 
+export declare type ReportPreviewPreferences = Record<ReportPreviewTool, boolean>;
+
+export 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_2[];
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+
+declare interface ReportSaveResult {
+    revision: string;
+    sourceToken?: string;
+    conflicts?: Array<{ editIndex: number; code: string; message: string }>;
+    diagnostics?: ReportDiagnostic[];
+}
+
+export declare interface ReportSection {
+    label: string;
+    pageIndex: number;
+}
+
 declare interface ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
@@ -1912,11 +2990,31 @@ declare interface ReportTemplate_3 {
     pages: TemplatePage_3[];
 }
 
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+declare interface ReportTemplateDocument {
+    schemaVersion: "1.0";
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate_2;
+}
+
 declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate_2 | Promise<ReportTemplate_2>;
 
-export declare const ReportToolbar: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+declare interface ReportTemplateProvider {
+    list(context: { signal?: AbortSignal }): Promise<ReportTemplateSummary[]>;
+    get(id: string, context: { signal?: AbortSignal }): Promise<ReportTemplateDocument | undefined>;
+}
+
+declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+
+export declare const ReportToolbar: DefineComponent<__VLS_Props, {
+focusSearch: () => void;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+export: (format: "pdf" | "xlsx" | "html" | "png" | "word") => any;
 print: () => any;
-export: (format: "html" | "png" | "pdf" | "xlsx" | "word") => any;
 zoom: (mode: number | "fit") => any;
 goto: (page: number) => any;
 "pdf-window": () => any;
@@ -1925,9 +3023,10 @@ goto: (page: number) => any;
 "search-toggle": () => any;
 "thumbs-toggle": () => any;
 "import-excel": () => any;
+"settings-toggle": () => any;
 }, string, PublicProps, Readonly<__VLS_Props> & Readonly<{
+onExport?: ((format: "pdf" | "xlsx" | "html" | "png" | "word") => any) | undefined;
 onPrint?: (() => any) | undefined;
-onExport?: ((format: "html" | "png" | "pdf" | "xlsx" | "word") => any) | undefined;
 onZoom?: ((mode: number | "fit") => any) | undefined;
 onGoto?: ((page: number) => any) | undefined;
 "onPdf-window"?: (() => any) | undefined;
@@ -1936,13 +3035,15 @@ onGoto?: ((page: number) => any) | undefined;
 "onSearch-toggle"?: (() => any) | undefined;
 "onThumbs-toggle"?: (() => any) | undefined;
 "onImport-excel"?: (() => any) | undefined;
+"onSettings-toggle"?: (() => any) | undefined;
 }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 searchInputRef: HTMLInputElement;
+searchToggleRef: HTMLButtonElement;
 }, HTMLDivElement>;
 
 export declare function resolveConfig(config: MachReportConfig | null | undefined, presetName?: string): ResolvedConfig;
 
-export declare type ResolvedConfig = Required<Pick<MachReportDefaults, "showExport" | "showPrint" | "showPdfWindow" | "showParams" | "gapPx">> & {
+export declare type ResolvedConfig = Required<Pick<MachReportDefaults, "showExport" | "showPrint" | "showPdfWindow" | "showSettings" | "showParams" | "gapPx">> & {
     pdfFontUrl: string;
     theme: MachReportTheme;
     messages: MachReportMessages;
@@ -1951,6 +3052,10 @@ export declare type ResolvedConfig = Required<Pick<MachReportDefaults, "showExpo
     xlsx: XlsxRenderOptions;
     editable: boolean | ReportEditingOptions;
     excelImport: boolean | ExcelImportOptions;
+    toolbar: MachReportToolbarOptions;
+    interaction: ReportInteractionOptions;
+    preferences?: ReportPreferencesOptions;
+    assets?: AssetRenderOptions;
 };
 
 declare interface RichParagraph {
@@ -2001,12 +3106,6 @@ declare interface RichSegment_3 {
     style?: ComponentStyle_3;
 }
 
-/** 控制器注入：后代组件 useReportPreview() 免模板 ref 编程式访问（与 expose 同面） */
-/** 编程式设参查询：合并进面板值（面板本地字典经 v-model 同步），可选立即重载 */
-declare function setParams(values: Record<string, string>, opts?: {
-    reload?: boolean;
-}): Promise<void>;
-
 export declare const SILENT_LOGGER: MachReportLogger;
 
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
@@ -2042,9 +3141,9 @@ declare interface StyleRule_3 {
     style: Record<string, unknown>;
 }
 
-declare type TemplateComponent = PlanComponent | ListComponent;
+declare type TemplateComponent = PlanComponent_2 | ListComponent;
 
-declare type TemplateComponent_2 = PlanComponent_2 | ListComponent_2;
+declare type TemplateComponent_2 = PlanComponent | ListComponent_2;
 
 declare type TemplateComponent_3 = PlanComponent_3 | ListComponent_3;
 
@@ -2094,7 +3193,9 @@ declare interface TemplatePage_3 {
 
 declare interface TextMeasureOptions {
     fontSizePt: number;
+    fontFamily?: string;
     bold?: boolean;
+    italic?: boolean;
     letterSpacingPt?: number;
 }
 
@@ -2196,7 +3297,7 @@ export declare function useZoom(getFitInputs: () => {
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
  */
-declare interface XlsxRenderOptions {
+declare interface XlsxRenderOptions extends OutputDiagnosticOptions_2 {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */