@agile-team/mach-report 2.12.0 → 2.14.0

package/dist/vue/async.d.cts

@@ -681,6 +681,7 @@ declare interface MachReportConfig {
 }
 /** defaults 层可配置项（全部可选，均有内置缺省） */
 declare interface MachReportDefaults {
+    printOptions?: ReportPrintOptions;
     showExport?: boolean;
     showPrint?: boolean;
     showPdfWindow?: boolean;
@@ -727,7 +728,7 @@ declare type MachReportLogger = Pick<Console, "warn" | "info">;
  * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-declare interface MachReportMessages extends Partial<ReportCalculationMessages> {
+declare interface MachReportMessages extends Partial<ReportCalculationMessages>, ReportPrintMessages {
     exportMenu?: string;
     exportMenuDescription?: string;
     clearSearch?: string;
@@ -737,6 +738,17 @@ declare interface MachReportMessages extends Partial<ReportCalculationMessages>
     pageJumpInvalid?: string;
     pageJumpHint?: string;
     pagination?: string;
+    recordNavigation?: string;
+    dataExplanation?: string;
+    dataExplanationHint?: string;
+    dataExplanationSearch?: string;
+    dataExplanationEmpty?: string;
+    dataMissingSource?: string;
+    dataNotApplicable?: string;
+    dataNotCalculable?: string;
+    recordInfo?: string;
+    prevRecord?: string;
+    nextRecord?: string;
     columnSearchHint?: string;
     columnSearchShortcut?: string;
     closeColumnDirectory?: string;
@@ -1426,6 +1438,20 @@ declare interface ReportCellTableIdentity_2 {
 declare type ReportCellValue = string | number | boolean | null;
 declare type ReportCellValue_2 = string | number | boolean | null;
 declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
+declare interface ReportDataTarget {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
+declare interface ReportDataTarget_2 {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
 declare interface ReportDefinition {
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate | ReportTemplateLoader;
@@ -1446,6 +1472,9 @@ declare interface ReportDiagnostic {
     message: string;
     path?: string;
     severity: "warning" | "error" | "info";
+    /** Optional explanation supplied by the business source, not inferred from blank cells. */
+    valueState?: ReportValueState;
+    target?: ReportDataTarget;
 }
 declare type ReportDiscardReason = "reload" | "import" | "replace" | "leave";
 declare interface ReportEditBatch {
@@ -1529,7 +1558,8 @@ declare interface ReportFetchInput extends ReportTaskMonitoring {
     signal?: AbortSignal;
     /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
     onWarning?: (message: string) => void;
-    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
+    /** Index scopes diagnostics when reports share datasets or a report ID is repeated. */
+    onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 declare interface ReportFieldContract {
     field: string;
@@ -1550,6 +1580,7 @@ declare interface ReportFieldTarget {
     datasetId?: string;
     rowKey?: string | number;
     tableId?: string;
+    reportScope?: string;
 }
 declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
@@ -1650,7 +1681,13 @@ declare interface ReportPreferencesOptions {
     key: string;
     adapter: ReportPreferencesAdapter;
 }
+declare interface ReportPreviewDataTarget extends ReportDataTarget_2 {
+    /** Added by the query adapter; isolates identical dataset/row/field identities across reports. */
+    reportScope?: string;
+}
 declare interface ReportPreviewDiagnostic {
+    valueState?: ReportValueState_2;
+    target?: ReportPreviewDataTarget;
     code: string;
     severity: "warning" | "error" | "info";
     message: string;
@@ -1673,6 +1710,35 @@ declare interface ReportPreviewTask {
 }
 declare type ReportPreviewTaskStage = "query" | "validate" | "layout" | "assets" | "import" | "encode" | "download" | "print";
 declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
+declare interface ReportPrintCalibration {
+    offsetXmm?: number;
+    offsetYmm?: number;
+}
+declare interface ReportPrintFont {
+    /** Same family name used by the template. Sources are trusted application assets. */
+    family: string;
+    source: string;
+    weight?: string;
+    style?: "normal" | "italic" | "oblique";
+}
+declare interface ReportPrintMessages {
+    printPrepareTimeout?: string;
+    printImageFailed?: string;
+    printFontFailed?: string;
+    printPrepareFailed?: string;
+    printCalibration?: string;
+    printOffsetX?: string;
+    printOffsetY?: string;
+    printCalibrationTest?: string;
+    printCalibrationHint?: string;
+}
+declare interface ReportPrintOptions {
+    /** Defaults to 15 seconds for the entire font/image preparation stage. */
+    resourceTimeoutMs?: number;
+    fonts?: readonly ReportPrintFont[];
+    /** Physical translation only; no scaling or mutation of the report data/plan. */
+    calibration?: ReportPrintCalibration;
+}
 /** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
 declare interface ReportProvider {
     query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
@@ -1783,6 +1849,10 @@ declare interface ReportTemplateRepeat_2 {
     };
 }
 declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState_2 = "missing-source" | "not-applicable" | "not-calculable";
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];

package/dist/vue/async.d.ts

@@ -681,6 +681,7 @@ declare interface MachReportConfig {
 }
 /** defaults 层可配置项（全部可选，均有内置缺省） */
 declare interface MachReportDefaults {
+    printOptions?: ReportPrintOptions;
     showExport?: boolean;
     showPrint?: boolean;
     showPdfWindow?: boolean;
@@ -727,7 +728,7 @@ declare type MachReportLogger = Pick<Console, "warn" | "info">;
  * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-declare interface MachReportMessages extends Partial<ReportCalculationMessages> {
+declare interface MachReportMessages extends Partial<ReportCalculationMessages>, ReportPrintMessages {
     exportMenu?: string;
     exportMenuDescription?: string;
     clearSearch?: string;
@@ -737,6 +738,17 @@ declare interface MachReportMessages extends Partial<ReportCalculationMessages>
     pageJumpInvalid?: string;
     pageJumpHint?: string;
     pagination?: string;
+    recordNavigation?: string;
+    dataExplanation?: string;
+    dataExplanationHint?: string;
+    dataExplanationSearch?: string;
+    dataExplanationEmpty?: string;
+    dataMissingSource?: string;
+    dataNotApplicable?: string;
+    dataNotCalculable?: string;
+    recordInfo?: string;
+    prevRecord?: string;
+    nextRecord?: string;
     columnSearchHint?: string;
     columnSearchShortcut?: string;
     closeColumnDirectory?: string;
@@ -1426,6 +1438,20 @@ declare interface ReportCellTableIdentity_2 {
 declare type ReportCellValue = string | number | boolean | null;
 declare type ReportCellValue_2 = string | number | boolean | null;
 declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
+declare interface ReportDataTarget {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
+declare interface ReportDataTarget_2 {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
 declare interface ReportDefinition {
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate | ReportTemplateLoader;
@@ -1446,6 +1472,9 @@ declare interface ReportDiagnostic {
     message: string;
     path?: string;
     severity: "warning" | "error" | "info";
+    /** Optional explanation supplied by the business source, not inferred from blank cells. */
+    valueState?: ReportValueState;
+    target?: ReportDataTarget;
 }
 declare type ReportDiscardReason = "reload" | "import" | "replace" | "leave";
 declare interface ReportEditBatch {
@@ -1529,7 +1558,8 @@ declare interface ReportFetchInput extends ReportTaskMonitoring {
     signal?: AbortSignal;
     /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
     onWarning?: (message: string) => void;
-    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
+    /** Index scopes diagnostics when reports share datasets or a report ID is repeated. */
+    onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 declare interface ReportFieldContract {
     field: string;
@@ -1550,6 +1580,7 @@ declare interface ReportFieldTarget {
     datasetId?: string;
     rowKey?: string | number;
     tableId?: string;
+    reportScope?: string;
 }
 declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
@@ -1650,7 +1681,13 @@ declare interface ReportPreferencesOptions {
     key: string;
     adapter: ReportPreferencesAdapter;
 }
+declare interface ReportPreviewDataTarget extends ReportDataTarget_2 {
+    /** Added by the query adapter; isolates identical dataset/row/field identities across reports. */
+    reportScope?: string;
+}
 declare interface ReportPreviewDiagnostic {
+    valueState?: ReportValueState_2;
+    target?: ReportPreviewDataTarget;
     code: string;
     severity: "warning" | "error" | "info";
     message: string;
@@ -1673,6 +1710,35 @@ declare interface ReportPreviewTask {
 }
 declare type ReportPreviewTaskStage = "query" | "validate" | "layout" | "assets" | "import" | "encode" | "download" | "print";
 declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
+declare interface ReportPrintCalibration {
+    offsetXmm?: number;
+    offsetYmm?: number;
+}
+declare interface ReportPrintFont {
+    /** Same family name used by the template. Sources are trusted application assets. */
+    family: string;
+    source: string;
+    weight?: string;
+    style?: "normal" | "italic" | "oblique";
+}
+declare interface ReportPrintMessages {
+    printPrepareTimeout?: string;
+    printImageFailed?: string;
+    printFontFailed?: string;
+    printPrepareFailed?: string;
+    printCalibration?: string;
+    printOffsetX?: string;
+    printOffsetY?: string;
+    printCalibrationTest?: string;
+    printCalibrationHint?: string;
+}
+declare interface ReportPrintOptions {
+    /** Defaults to 15 seconds for the entire font/image preparation stage. */
+    resourceTimeoutMs?: number;
+    fonts?: readonly ReportPrintFont[];
+    /** Physical translation only; no scaling or mutation of the report data/plan. */
+    calibration?: ReportPrintCalibration;
+}
 /** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
 declare interface ReportProvider {
     query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
@@ -1783,6 +1849,10 @@ declare interface ReportTemplateRepeat_2 {
     };
 }
 declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState_2 = "missing-source" | "not-applicable" | "not-calculable";
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];

package/dist/vue/index.d.cts

@@ -70,6 +70,10 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
         type: PropType<AssetRenderOptions>;
         default: undefined;
     };
+    printOptions: {
+        type: PropType<ReportPrintOptions>;
+        default: undefined;
+    };
     /** 保留表头的零行业务结果；不改变计划和导出内容。 */
     emptyState: {
         type: PropType<boolean | ReportEmptyState>;
@@ -228,6 +232,10 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
         type: PropType<AssetRenderOptions>;
         default: undefined;
     };
+    printOptions: {
+        type: PropType<ReportPrintOptions>;
+        default: undefined;
+    };
     /** 保留表头的零行业务结果；不改变计划和导出内容。 */
     emptyState: {
         type: PropType<boolean | ReportEmptyState>;
@@ -301,6 +309,7 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
     showPdfWindow: boolean;
     showSettings: boolean;
     showParams: boolean;
+    printOptions: ReportPrintOptions;
     toolbar: MachReportToolbarOptions;
     interaction: ReportInteractionOptions;
     preferences: ReportPreferencesOptions;
@@ -318,8 +327,8 @@ declare const __VLS_component_2: DefineComponent<__VLS_Props, {
     focusSearch: () => void;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
     export: (format: ReportExportFormat) => any;
-    print: () => any;
     zoom: (mode: number | "fit") => any;
+    print: () => any;
     goto: (page: number) => any;
     "pdf-window": () => any;
     "search-input": (query: string) => any;
@@ -330,8 +339,8 @@ declare const __VLS_component_2: DefineComponent<__VLS_Props, {
     "settings-toggle": () => any;
 }, string, MachReportVuePublicProps, Readonly<__VLS_Props> & Readonly<{
     onExport?: ((format: ReportExportFormat) => any) | undefined;
-    onPrint?: (() => any) | undefined;
     onZoom?: ((mode: number | "fit") => any) | undefined;
+    onPrint?: (() => any) | undefined;
     onGoto?: ((page: number) => any) | undefined;
     "onPdf-window"?: (() => any) | undefined;
     "onSearch-input"?: ((query: string) => any) | undefined;
@@ -469,7 +478,7 @@ declare interface AssetRenderOptions extends OutputDiagnosticOptions {
     signal?: AbortSignal;
 }
 /** 供 HTML/Word 导出的完整文档；打印路径逐页渲染，避免预先生成所有页。 */
-export declare function buildPrintDocument(p: RenderPlan): PrintHtmlResult;
+export declare function buildPrintDocument(p: RenderPlan, options?: ReportPrintOptions): PrintHtmlResult;
 export declare function buildWordHtml(p: RenderPlan): {
     html: string;
     filename: string;
@@ -722,6 +731,8 @@ export declare function createFetchRequest(options?: FetchRequestOptions): HostR
  * 用于本地预览、离线场景和单测。
  */
 export declare function createLocalFetcher(entries: Record<string, LocalTemplateEntry> | ReportRegistry): PlanFetcher;
+/** Independent physical test page. Its ruler is measured in millimetres, never CSS pixels. */
+export declare function createPrintCalibrationPlan(widthMm: number, heightMm: number): RenderPlan_2;
 /** 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. */
@@ -740,6 +751,7 @@ declare interface DatasetValidationOptions {
 }
 export declare const DEFAULT_CALCULATION_MESSAGES: ReportCalculationMessages;
 export declare const DEFAULT_MESSAGES: MachReportMessages;
+export declare const DEFAULT_PRINT_MESSAGES: Required<ReportPrintMessages>;
 export declare const DEFAULT_THEME: MachReportTheme;
 export declare interface DefaultPdfExporterOptions {
     /** 中文字体 URL（浏览器 fetch）；空串跳过字体加载（西文报表） */
@@ -1367,6 +1379,7 @@ export declare interface MachReportController {
 }
 /** defaults 层可配置项（全部可选，均有内置缺省） */
 export declare interface MachReportDefaults {
+    printOptions?: ReportPrintOptions;
     showExport?: boolean;
     showPrint?: boolean;
     showPdfWindow?: boolean;
@@ -1449,7 +1462,7 @@ export declare type MachReportLogger = Pick<Console, "warn" | "info">;
  * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-export declare interface MachReportMessages extends Partial<ReportCalculationMessages> {
+export declare interface MachReportMessages extends Partial<ReportCalculationMessages>, ReportPrintMessages {
     exportMenu?: string;
     exportMenuDescription?: string;
     clearSearch?: string;
@@ -1459,6 +1472,17 @@ export declare interface MachReportMessages extends Partial<ReportCalculationMes
     pageJumpInvalid?: string;
     pageJumpHint?: string;
     pagination?: string;
+    recordNavigation?: string;
+    dataExplanation?: string;
+    dataExplanationHint?: string;
+    dataExplanationSearch?: string;
+    dataExplanationEmpty?: string;
+    dataMissingSource?: string;
+    dataNotApplicable?: string;
+    dataNotCalculable?: string;
+    recordInfo?: string;
+    prevRecord?: string;
+    nextRecord?: string;
     columnSearchHint?: string;
     columnSearchShortcut?: string;
     closeColumnDirectory?: string;
@@ -1974,6 +1998,18 @@ declare interface PlanPage {
     marginRightMm?: number;
     components: PlanComponent[];
 }
+declare interface PlanPage_2 {
+    meta?: Record<string, unknown>;
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
+    pageWidthMm: number;
+    pageHeightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: PlanComponent_2[];
+}
 /** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
 declare interface PlanTableFragment {
     /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
@@ -2022,6 +2058,12 @@ declare interface PlanTableFragment_3 {
         rowKey?: string | number;
     };
 }
+/** Bounded concurrency, one stage timeout, and cancellation even for a hanging decoder. */
+export declare function preparePrintResources(doc: Document, options?: ReportPrintOptions, signal?: AbortSignal, base?: string): Promise<void>;
+export declare function printCalibration(options?: ReportPrintOptions): {
+    x: number;
+    y: number;
+};
 declare interface PrintHtmlResult {
     head: string;
     pageChunks: string[];
@@ -2034,6 +2076,8 @@ export declare function printPlans(plans: RenderPlan[], options?: {
     onProgress?: (done: number, total: number) => void;
     onError?: (message: string) => void;
     signal?: AbortSignal;
+    printOptions?: ReportPrintOptions;
+    messages?: ReportPrintMessages;
 }): Promise<void>;
 /**
  * 路由/布局级响应式叠加：就近提供配置层（如某路由关闭导出按钮）。
@@ -2055,6 +2099,12 @@ declare interface RenderPlan {
     requiresRecalculation?: boolean;
     pages: PlanPage[];
 }
+declare interface RenderPlan_2 {
+    schemaVersion: string;
+    /** 编辑需要模板重算上下文；跨 Worker/JSON 保留要求，但不声明本地会话可用。 */
+    requiresRecalculation?: boolean;
+    pages: PlanPage_2[];
+}
 export declare const REPORT_EXPORT_FORMATS: readonly ReportExportFormat[];
 export declare const REPORT_PREVIEW_TOOLS: readonly [
     "search",
@@ -2224,6 +2274,20 @@ declare interface ReportCellTableIdentity_2 {
 declare type ReportCellValue = string | number | boolean | null;
 declare type ReportCellValue_2 = string | number | boolean | null;
 declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
+declare interface ReportDataTarget {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
+declare interface ReportDataTarget_2 {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
 declare interface ReportDefinition {
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate_2 | ReportTemplateLoader;
@@ -2244,6 +2308,9 @@ declare interface ReportDiagnostic {
     message: string;
     path?: string;
     severity: "warning" | "error" | "info";
+    /** Optional explanation supplied by the business source, not inferred from blank cells. */
+    valueState?: ReportValueState;
+    target?: ReportDataTarget;
 }
 export declare type ReportDiscardReason = "reload" | "import" | "replace" | "leave";
 declare interface ReportEditBatch {
@@ -2339,7 +2406,8 @@ declare interface ReportFetchInput extends ReportTaskMonitoring {
     signal?: AbortSignal;
     /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
     onWarning?: (message: string) => void;
-    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
+    /** Index scopes diagnostics when reports share datasets or a report ID is repeated. */
+    onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 declare interface ReportFieldContract {
     field: string;
@@ -2360,6 +2428,7 @@ export declare interface ReportFieldTarget {
     datasetId?: string;
     rowKey?: string | number;
     tableId?: string;
+    reportScope?: string;
 }
 declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
@@ -2514,7 +2583,13 @@ export declare interface ReportPreferencesOptions {
     adapter: ReportPreferencesAdapter;
 }
 export declare const ReportPreview: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export declare interface ReportPreviewDataTarget extends ReportDataTarget_2 {
+    /** Added by the query adapter; isolates identical dataset/row/field identities across reports. */
+    reportScope?: string;
+}
 export declare interface ReportPreviewDiagnostic {
+    valueState?: ReportValueState_2;
+    target?: ReportPreviewDataTarget;
     code: string;
     severity: "warning" | "error" | "info";
     message: string;
@@ -2537,6 +2612,41 @@ export declare interface ReportPreviewTask {
 }
 export declare type ReportPreviewTaskStage = "query" | "validate" | "layout" | "assets" | "import" | "encode" | "download" | "print";
 export declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
+export declare interface ReportPrintCalibration {
+    offsetXmm?: number;
+    offsetYmm?: number;
+}
+export declare interface ReportPrintFont {
+    /** Same family name used by the template. Sources are trusted application assets. */
+    family: string;
+    source: string;
+    weight?: string;
+    style?: "normal" | "italic" | "oblique";
+}
+export declare interface ReportPrintMessages {
+    printPrepareTimeout?: string;
+    printImageFailed?: string;
+    printFontFailed?: string;
+    printPrepareFailed?: string;
+    printCalibration?: string;
+    printOffsetX?: string;
+    printOffsetY?: string;
+    printCalibrationTest?: string;
+    printCalibrationHint?: string;
+}
+export declare interface ReportPrintOptions {
+    /** Defaults to 15 seconds for the entire font/image preparation stage. */
+    resourceTimeoutMs?: number;
+    fonts?: readonly ReportPrintFont[];
+    /** Physical translation only; no scaling or mutation of the report data/plan. */
+    calibration?: ReportPrintCalibration;
+}
+export declare class ReportPrintResourceError extends Error {
+    readonly kind: "image" | "font" | "timeout" | "config";
+    readonly resource: string | number;
+    readonly code = "print-resource";
+    constructor(kind: "image" | "font" | "timeout" | "config", resource?: string | number);
+}
 /** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
 declare interface ReportProvider {
     query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
@@ -2669,6 +2779,10 @@ declare interface ReportTemplateRepeat_3 {
 }
 declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
 export declare const ReportToolbar: __VLS_WithTemplateSlots_2<typeof __VLS_component_2, __VLS_TemplateResult_2["slots"]>;
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
+/** Optional business explanations never replace raw data or schema validation. */
+declare type ReportValueState_2 = "missing-source" | "not-applicable" | "not-calculable";
 /** 新消息保持可选，旧的完整文案对象也能获得新增能力的默认文案。 */
 export declare function resolveCalculationMessages(messages: Partial<ReportCalculationMessages>): ReportCalculationMessages;
 export declare function resolveConfig(config: MachReportConfig | null | undefined, presetName?: string): ResolvedConfig;
@@ -2688,6 +2802,7 @@ export declare type ResolvedConfig = Required<Pick<MachReportDefaults, "showExpo
     guardChanges: boolean;
     beforeDiscard?: ReportBeforeDiscard;
     output: ReportOutputOptions;
+    printOptions?: ReportPrintOptions;
 };
 declare interface RichParagraph {
     segments: RichSegment[];
@@ -2732,6 +2847,7 @@ declare interface RichSegment_3 {
     style?: ComponentStyle_3;
 }
 export declare const SILENT_LOGGER: MachReportLogger;
+export declare function snapshotPrintOptions(options?: ReportPrintOptions): ReportPrintOptions;
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
     when: {
@@ -2916,12 +3032,15 @@ export declare function usePageWindow(plan: Ref<RenderPlan | null>, zoom: Ref<nu
     }[]>;
     makeScrollHandler: (currentPage: Ref<number>, pageCount: Ref<number>) => (vp: HTMLElement) => void;
     refreshViewport: (vp: HTMLElement | null) => void;
+    scrollToPage: (vp: HTMLElement, index: number) => void;
     pageOffsetPx: (index: number) => number;
     destroy: () => void;
 };
 export declare function usePrintExport(plan: Ref<RenderPlan | null>, hooks: {
     /** 按导出开始时的配置快照处理，避免输出过程中跟随路由配置变化。 */
     getXlsxOptions?: () => XlsxRenderOptions;
+    getPrintOptions?: () => ReportPrintOptions;
+    getPrintMessages?: () => ReportPrintMessages;
     /** Flush the active editor and await source-backed calculation/persistence before capturing the output plan. */
     beforeOutput?: () => boolean | Promise<boolean>;
     getPdfExporter: () => PdfExporter;