@agile-team/mach-report 2.6.1 → 2.7.0

package/dist/vue/async.d.cts

@@ -1,2083 +1,1507 @@
-import { AllowedComponentProps } from 'vue';
-import { App } from 'vue';
-import { ComponentCustomProps } from 'vue';
-import { ComponentOptionsBase } from 'vue';
-import { ComponentOptionsMixin } from 'vue';
-import { ComponentProvideOptions } from 'vue';
-import { ComputedRef } from 'vue';
-import { CreateComponentPublicInstanceWithMixins } from 'vue';
-import { ExtractPropTypes } from 'vue';
-import { GlobalComponents } from 'vue';
-import { GlobalDirectives } from 'vue';
-import { PropType } from 'vue';
-import { PublicProps } from 'vue';
-import { VNodeProps } from 'vue';
-
-declare interface AssetRenderBudget {
-    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
-    maxAssets?: number;
-    /** Maximum image payload bytes per new asset, default 32 MiB. */
-    maxImageBytes?: number;
-    /** Maximum total image payload bytes for new assets, default 128 MiB. */
-    maxTotalImageBytes?: number;
-    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
-    maxDurationMs?: number;
-}
-
-declare interface AssetRenderOptions extends OutputDiagnosticOptions {
-    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
-    assetBudget?: AssetRenderBudget;
-    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
-    assetFailure?: "throw" | "placeholder";
-    signal?: AbortSignal;
-}
-
-/**
- * 列值格式化（声明式、JSON 可序列化）。
- * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
- * 三后端（DOM/Canvas/PDF）零改动。
- *
- * 语义约定（v0.9 固化）：
- * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
- * - number.thousands 默认 false（千分位显式开启）
- * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
- *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
- */
-
-declare type ColumnFormat =
-| { kind: "number"; thousands?: boolean; digits?: number }
-| { kind: "percent"; digits?: number }
-| { kind: "date"; pattern?: string };
-
-/**
- * 列值格式化（声明式、JSON 可序列化）。
- * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
- * 三后端（DOM/Canvas/PDF）零改动。
- *
- * 语义约定（v0.9 固化）：
- * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
- * - number.thousands 默认 false（千分位显式开启）
- * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
- *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
- */
-declare type ColumnFormat_2 = {
-    kind: "number";
-    thousands?: boolean;
-    digits?: number;
-} | {
-    kind: "percent";
-    digits?: number;
-} | {
-    kind: "date";
-    pattern?: string;
-};
-
-declare interface ComponentImageContext {
-    readonly component: Readonly<PlanComponent>;
-    readonly pageIndex: number;
-    readonly componentIndex: number;
-    readonly componentPath: readonly number[];
-    readonly signal: AbortSignal;
-}
-
-declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
-
-declare type ComponentKind =
-| "text"
-| "image"
-| "barcode"
-| "qrcode"
-| "chart"
-| "line"
-| "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 {
-    fontSizePx?: number;
-    fontSize?: number;
-    fontFamily?: string;
-    bold?: boolean;
-    italic?: boolean;
-    underline?: boolean;
-    color?: string;
-    backgroundColor?: string;
-    align?: "left" | "center" | "right" | "justify";
-    verticalAlign?: "top" | "middle" | "bottom";
-    lineColor?: string;
-    borderColor?: string;
-    lineWidthPt?: number;
-    borderTop?: boolean;
-    borderRight?: boolean;
-    borderBottom?: boolean;
-    borderLeft?: boolean;
-    lineHeight?: number;
-    letterSpacing?: number;
-    opacity?: number;
-    rotateDeg?: number;
-}
-
-declare interface ComponentStyle_2 {
-    fontSizePx?: number;
-    fontSize?: number;
-    fontFamily?: string;
-    bold?: boolean;
-    italic?: boolean;
-    underline?: boolean;
-    color?: string;
-    backgroundColor?: string;
-    align?: "left" | "center" | "right" | "justify";
-    verticalAlign?: "top" | "middle" | "bottom";
-    lineColor?: string;
-    borderColor?: string;
-    lineWidthPt?: number;
-    borderTop?: boolean;
-    borderRight?: boolean;
-    borderBottom?: boolean;
-    borderLeft?: boolean;
-    lineHeight?: number;
-    letterSpacing?: number;
-    opacity?: number;
-    rotateDeg?: number;
-}
-
-declare interface ComponentStyle_3 {
-    fontSizePx?: number;
-    fontSize?: number;
-    fontFamily?: string;
-    bold?: boolean;
-    italic?: boolean;
-    underline?: boolean;
-    color?: string;
-    backgroundColor?: string;
-    align?: "left" | "center" | "right" | "justify";
-    verticalAlign?: "top" | "middle" | "bottom";
-    lineColor?: string;
-    borderColor?: string;
-    lineWidthPt?: number;
-    borderTop?: boolean;
-    borderRight?: boolean;
-    borderBottom?: boolean;
-    borderLeft?: boolean;
-    lineHeight?: number;
-    letterSpacing?: number;
-    opacity?: number;
-    rotateDeg?: number;
-}
-
-declare interface DatasetContract { fields: readonly ReportFieldContract[]; rowKey?: string }
-
-declare type DatasetRows = Record<string, Record<string, unknown>[]>;
-
-declare interface DatasetValidationOptions { path?: string; maxRows?: number; maxCells?: number; maxIssues?: number }
-
-declare interface ExcelImportedSheet {
-    name: string;
-    /** Original, one-based workbook position. */
-    index: number;
-    range: string;
-    rowCount: number;
-    columnCount: number;
-    /** Zero-based index into template.pages. */
-    pageStart: number;
-    pageCount: number;
-}
-
-/** Limits apply to the selected rectangular ranges, including their empty cells. */
-declare interface ExcelImportLimits {
-    /** Compressed input, default 20 MiB. */
-    maxFileBytes?: number;
-    /** Declared ZIP uncompressed total, default 64 MiB. */
-    maxUncompressedBytes?: number;
-    /** Total selected cells across sheets, default 250,000; hard ceiling 1,000,000. */
-    maxCells?: number;
-    /** Rows per selected sheet, default 100,000; hard ceiling 1,048,576. */
-    maxRows?: number;
-    /** Columns per selected sheet, default 2,048; hard ceiling 16,384. */
-    maxColumns?: number;
-    /** Workbook sheets, default 32. */
-    maxSheets?: number;
-}
-
-/** Limits apply to the selected rectangular ranges, including their empty cells. */
-declare interface ExcelImportLimits_2 {
-    /** Compressed input, default 20 MiB. */
-    maxFileBytes?: number;
-    /** Declared ZIP uncompressed total, default 64 MiB. */
-    maxUncompressedBytes?: number;
-    /** Total selected cells across sheets, default 250,000; hard ceiling 1,000,000. */
-    maxCells?: number;
-    /** Rows per selected sheet, default 100,000; hard ceiling 1,048,576. */
-    maxRows?: number;
-    /** Columns per selected sheet, default 2,048; hard ceiling 16,384. */
-    maxColumns?: number;
-    /** Workbook sheets, default 32. */
-    maxSheets?: number;
-}
-
-declare interface ExcelImportOptions {
-    /** Sheet names or one-based workbook positions. Default: all visible sheets. */
-    sheets?: Array<string | number>;
-    /** A1 range for every sheet, or ranges keyed by exact sheet name. */
-    range?: string | Record<string, string>;
-    /** Wide preserves natural column widths. A3/A4 scale the complete width to paper. */
-    layout?: "wide" | "a3" | "a4";
-    /** Only applies to A3/A4; default landscape. */
-    landscape?: boolean;
-    /** Vertical preview segment limit, default 80, maximum 200. Merges remain intact. */
-    maxRowsPerPage?: number;
-    /** Optional resource limits; hard ceilings prevent unbounded allocations. */
-    limits?: ExcelImportLimits;
-}
-
-declare interface ExcelImportOptions_2 {
-    /** Sheet names or one-based workbook positions. Default: all visible sheets. */
-    sheets?: Array<string | number>;
-    /** A1 range for every sheet, or ranges keyed by exact sheet name. */
-    range?: string | Record<string, string>;
-    /** Wide preserves natural column widths. A3/A4 scale the complete width to paper. */
-    layout?: "wide" | "a3" | "a4";
-    /** Only applies to A3/A4; default landscape. */
-    landscape?: boolean;
-    /** Vertical preview segment limit, default 80, maximum 200. Merges remain intact. */
-    maxRowsPerPage?: number;
-    /** Optional resource limits; hard ceilings prevent unbounded allocations. */
-    limits?: ExcelImportLimits_2;
-}
-
-declare interface ExcelImportResult {
-    template: ReportTemplate_2;
-    warnings: string[];
-    sheets: ExcelImportedSheet[];
-}
-
-declare interface GridCell {
-    text?: string;
-    rawText?: string;
-    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
-    value?: string | number | boolean | null;
-    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
-    numberFormat?: string;
-    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
-    valueType?: "text" | "number" | "boolean";
-    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
-    editable?: boolean;
-    source?: ReportCellSource;
-    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
-    formula?: string;
-    children?: PlanComponent[];
-    colSpan?: number;
-    rowSpan?: number;
-    style?: ComponentStyle;
-}
-
-declare interface GridCell_2 {
-    text?: string;
-    rawText?: string;
-    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
-    value?: string | number | boolean | null;
-    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
-    numberFormat?: string;
-    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
-    valueType?: "text" | "number" | "boolean";
-    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
-    editable?: boolean;
-    source?: ReportCellSource_2;
-    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
-    formula?: string;
-    children?: PlanComponent_2[];
-    colSpan?: number;
-    rowSpan?: number;
-    style?: ComponentStyle_2;
-}
-
-declare interface GridCell_3 {
-    text?: string;
-    rawText?: string;
-    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
-    value?: string | number | boolean | null;
-    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
-    numberFormat?: string;
-    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
-    valueType?: "text" | "number" | "boolean";
-    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
-    editable?: boolean;
-    source?: ReportCellSource_3;
-    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
-    formula?: string;
-    children?: PlanComponent_3[];
-    colSpan?: number;
-    rowSpan?: number;
-    style?: ComponentStyle_3;
-}
-
-declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
-
-/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
-declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
-
-/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
-declare type ListAlignment_2 = NonNullable<ComponentStyle_3["align"]> | "auto";
-
-declare interface ListColumn {
-    header: string;
-    field: string;
-    widthMm: number;
-    style?: ComponentStyle;
-    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
-    align?: ListAlignment;
-    /** 独立的表头对齐，不改变内容对齐。 */
-    headerAlign?: ComponentStyle["align"];
-    /** 独立的表头样式，优先于列表级表头样式。 */
-    headerStyle?: ComponentStyle;
-    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
-    format?: ColumnFormat;
-    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
-    rules?: StyleRule[];
-    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
-    editable?: boolean;
-    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
-    valueType?: GridCell["valueType"];
-    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
-    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
-}
-
-declare interface ListColumn_2 {
-    header: string;
-    field: string;
-    widthMm: number;
-    style?: ComponentStyle_3;
-    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
-    align?: ListAlignment_2;
-    /** 独立的表头对齐，不改变内容对齐。 */
-    headerAlign?: ComponentStyle_3["align"];
-    /** 独立的表头样式，优先于列表级表头样式。 */
-    headerStyle?: ComponentStyle_3;
-    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
-    format?: ColumnFormat_2;
-    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
-    rules?: StyleRule_2[];
-    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
-    editable?: boolean;
-    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
-    valueType?: GridCell_3["valueType"];
-    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
-    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
-}
-
-declare interface ListComponent {
-    kind: "list";
-    id?: string;
-    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
-    layout?: "page" | "wide";
-    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
-    title?: string;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    dataset: string;
-    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
-    rowKey?: string;
-    revisionField?: string;
-    sourceTokenField?: string;
-    columns: ListColumn[];
-    fontSizePt?: number;
-    headerBold?: boolean;
-    rowHeightMm?: number;
-    paddingMm?: number;
-    headerEveryPage?: boolean;
-    headerBackgroundColor?: string;
-    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
-    align?: ListAlignment;
-    /** 表头默认对齐，列配置可覆盖。 */
-    headerAlign?: ComponentStyle["align"];
-    headerStyle?: ComponentStyle;
-    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
-    headerGrid?: PlanGrid;
-    border?: boolean;
-    /** 分组小计（组头/组尾小计/组头防孤行） */
-    groupBy?: ListGroupBy;
-    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
-    grandTotal?: ListGrandTotal;
-}
-
-declare interface ListComponent_2 {
-    kind: "list";
-    id?: string;
-    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
-    layout?: "page" | "wide";
-    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
-    title?: string;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    dataset: string;
-    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
-    rowKey?: string;
-    revisionField?: string;
-    sourceTokenField?: string;
-    columns: ListColumn_2[];
-    fontSizePt?: number;
-    headerBold?: boolean;
-    rowHeightMm?: number;
-    paddingMm?: number;
-    headerEveryPage?: boolean;
-    headerBackgroundColor?: string;
-    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
-    align?: ListAlignment_2;
-    /** 表头默认对齐，列配置可覆盖。 */
-    headerAlign?: ComponentStyle_3["align"];
-    headerStyle?: ComponentStyle_3;
-    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
-    headerGrid?: PlanGrid_3;
-    border?: boolean;
-    /** 分组小计（组头/组尾小计/组头防孤行） */
-    groupBy?: ListGroupBy_2;
-    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
-    grandTotal?: ListGrandTotal_2;
-}
-
-declare type ListGrandTotal =
-| boolean
-| {
-    label?: string;
-    style?: ComponentStyle;
-    /** 合计列（缺省沿用 groupBy.subtotal） */
-    fields?: string[];
-};
-
-declare type ListGrandTotal_2 = boolean | {
-    label?: string;
-    style?: ComponentStyle_3;
-    /** 合计列（缺省沿用 groupBy.subtotal） */
-    fields?: string[];
-};
-
-/** 分组小计配置（声明式，见 ListComponent.groupBy） */
-declare interface ListGroupBy {
-    /** 分组字段（值变化即切组） */
-    field: string;
-    /** 组头文案模板，{value} 占位（默认 "{value}"） */
-    headerTemplate?: string;
-    headerStyle?: ComponentStyle;
-    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
-    subtotal?: string[];
-    subtotalStyle?: ComponentStyle;
-    subtotalLabel?: string;
-    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
-    keepWithNext?: boolean;
-}
-
-/** 分组小计配置（声明式，见 ListComponent.groupBy） */
-declare interface ListGroupBy_2 {
-    /** 分组字段（值变化即切组） */
-    field: string;
-    /** 组头文案模板，{value} 占位（默认 "{value}"） */
-    headerTemplate?: string;
-    headerStyle?: ComponentStyle_3;
-    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
-    subtotal?: string[];
-    subtotalStyle?: ComponentStyle_3;
-    subtotalLabel?: string;
-    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
-    keepWithNext?: boolean;
-}
-
-declare const machReportAsyncPlugin: {
-    install(app: App, options?: MachReportPluginOptions): void;
-};
-export default machReportAsyncPlugin;
-export { machReportAsyncPlugin }
-
-declare interface MachReportConfig {
-    defaults: MachReportDefaults;
-    presets: Record<string, MachReportPreset>;
-    /** 默认启用的 preset 名 */
-    defaultPreset?: string;
-}
-
-/** defaults 层可配置项（全部可选，均有内置缺省） */
-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 */
-    gapPx?: number;
-    /** PDF 导出中文字体 URL */
-    pdfFontUrl?: string;
-    theme?: Partial<MachReportTheme>;
-    messages?: Partial<MachReportMessages>;
-    /** 校验告警等内部日志通道（默认 console；静默传 { warn: () => {}, info: () => {} }） */
-    logger?: MachReportLogger;
-    preview?: MachReportPreviewOptions;
-    /** Excel 出口配置，按字段继承；不配置使用导出器默认值。 */
-    xlsx?: XlsxRenderOptions;
-    /** 默认关闭；true 为本地草稿，对象可提供权限、校验和保存回调。 */
-    editable?: boolean | ReportEditingOptions;
-    /** 默认关闭；启用后提供导入按钮。ExcelJS 仅在导入时加载。 */
-    excelImport?: boolean | ExcelImportOptions;
-}
-
-/**
- * 结构化错误（code 分类，宿主可按码决定 UX：重试 / 提示 / 降级）。
- * error 事件契约保持 `(message: string)` 不变，新增第二参数 detail（可选）。
- */
-declare type MachReportErrorCode = "param" | "fetch" | "validate" | "render" | "pdf" | "print" | "export" | "edit" | "import" | "config";
-
-/** 日志通道（默认 console；可注入 noop 静默或上报 collector） */
-declare type MachReportLogger = Pick<Console, "warn" | "info">;
-
-/**
- * 配置中心（对齐 mach-table 的 defineMachTableConfig 体验）：
- * - 应用级：app.use(machReportPlugin, { config: defineMachReportConfig({...}) })
- * - 路由级叠加：provideMachReportConfig(overlay)（响应式，就近覆盖）
- * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
- */
-/** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-declare interface MachReportMessages {
-    title: string;
-    prevPage: string;
-    nextPage: string;
-    /** 页码显示模板，{cur}/{total} 占位 */
-    pageInfo: string;
-    fitWidth: string;
-    exportHtml: string;
-    exportPdf: string;
-    exportExcel: string;
-    exportImage: string;
-    exportWord: string;
-    /** 导出进行中提示，{format} 占位 */
-    exporting: string;
-    print: string;
-    pdfWindow: string;
-    loading: string;
-    empty: string;
-    /** @deprecated 未被组件消费，将在下个大版本移除（保留仅为类型兼容） */
-    errorPrefix: string;
-    retry: string;
-    /** 可选新增文案，保留旧完整文案对象兼容。 */
-    pdfFontUnavailable?: string;
-    /** 搜索框占位文案 */
-    searchPlaceholder: string;
-    /** 搜索命中计数，{cur}/{total} 占位 */
-    matchInfo: string;
-    /** 上/下一个命中 */
-    prevMatch: string;
-    nextMatch: string;
-    /** 缩略图侧栏开关 */
-    thumbnails: string;
-    /** 参数面板 */
-    paramsTitle: string;
-    query: string;
-    reset: string;
-    /** 必填缺失提示（{label} 占位） */
-    paramRequired: string;
-    paramInvalid?: string;
-    paramPrompt?: string;
-    paramPromptDescription?: string;
-    paramSelectPlaceholder?: string;
-    paramTextPlaceholder?: string;
-    /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
-    searching?: string;
-    importExcel?: string;
-    importing?: string;
-    editCell?: string;
-    editingHint?: string;
-    saving?: string;
-    editInvalidNumber?: string;
-    editInvalidBoolean?: string;
-    editConflict?: string;
-    settings?: string;
-    settingsDisplay?: string;
-    settingsExport?: string;
-    settingsData?: string;
-    settingsUnavailable?: string;
-    settingsReset?: string;
-    settingsClose?: string;
-    search?: string;
-    closeSearch?: string;
-    prevSearchMatch?: string;
-    nextSearchMatch?: string;
-    zoom?: string;
-    settingsLocal?: string;
-    editingLocal?: string;
-    editingSaved?: string;
-    importLocal?: string;
-    emptyDescription?: string;
-    undo?: string;
-    redo?: string;
-    restoreChanges?: string;
-    changes?: string;
-    changesCount?: string;
-    changesEmpty?: string;
-    changesBefore?: string;
-    changesAfter?: string;
-    editAtomicRequired?: string;
-    clipboardLimit?: string;
-    preferencesError?: string;
-    freezeHeaders?: string;
-    frozenColumns?: string;
-    sections?: string;
-    locateField?: string;
-    locateFieldPlaceholder?: string;
-    locateFieldMissing?: string;
-    importSummary?: string;
-    importPreserved?: string;
-    importWarnings?: string;
-    importReadOnly?: string;
-    conflicts?: string;
-    editReadOnly?: string;
-    editMissing?: string;
-    editDuplicate?: string;
-    clipboardInvalid?: string;
-    editSaved?: string;
-    settingsPanes?: string;
-}
-
-declare interface MachReportPluginOptions {
-    /** 报表数据源；也可直接传给 ReportPreview 的 fetcher prop */
-    fetcher?: PlanFetcher;
-    /** 常规业务接入：注册模板与取数，包内完成分页与参数面板；显式 fetcher 优先。 */
-    reports?: ReportRegistry;
-    /** 应用级配置中心（defaults/presets/文案/主题），见 defineMachReportConfig */
-    config?: MachReportConfig;
-    /** PDF 导出字体 URL（默认 /simhei.ttf；'' 跳过字体） */
-    pdfFontUrl?: string;
-    /** 自定义 PDF 导出器（缺省用懒加载引擎 /pdf 子路径的默认实现） */
-    pdfExporter?: PdfExporter;
-    /** 注册全局组件 <MachReportPreview>（默认 true；懒加载分片不影响首屏） */
-    globalComponent?: boolean;
-}
-
-declare type MachReportPreset = MachReportDefaults;
-
-/**
- * 全局组件（懒加载分片：首次渲染才拉取组件与引擎依赖，
- * 与局部 import 等价——首屏敏感页面零额外成本）
- */
-export declare const MachReportPreview: {
-    new (...args: any[]): CreateComponentPublicInstanceWithMixins<Readonly<ExtractPropTypes<    {
-    reportId: {
-    type: PropType<string | string[] | null>;
-    default: null;
-    };
-    params: {
-    type: PropType<Record<string, string>>;
-    default: () => {};
-    };
-    height: {
-    type: StringConstructor;
-    default: string;
-    };
-    autoLoad: {
-    type: BooleanConstructor;
-    default: boolean;
-    };
-    showExport: {
-    type: BooleanConstructor;
-    default: undefined;
-    };
-    showPrint: {
-    type: BooleanConstructor;
-    default: undefined;
-    };
-    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;
-    };
-    messages: {
-    type: PropType<Partial<MachReportMessages>>;
-    default: undefined;
-    };
-    preset: {
-    type: StringConstructor;
-    default: undefined;
-    };
-    debug: {
-    type: BooleanConstructor;
-    default: boolean;
-    };
-    paramDefs: {
-    type: PropType<ReportParamDef[] | undefined>;
-    default: undefined;
-    };
-    showParams: {
-    type: BooleanConstructor;
-    default: undefined;
-    };
-    editable: {
-    type: PropType<boolean | ReportEditingOptions>;
-    default: undefined;
-    };
-    excelImport: {
-    type: PropType<boolean | ExcelImportOptions_2>;
-    default: undefined;
-    };
-    fetcher: {
-    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;
-    "onCell-edit"?: ((edit: ReportCellEdit) => any) | undefined;
-    "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
-    "onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
-    }>, {
-    state: ComputedRef<MachReportState>;
-    checkPdfFont?(): Promise<PdfFontCheckResult>;
-    reload(): Promise<void>;
-    print(): Promise<void>;
-    exportAs(format: string): Promise<void> | void;
-    openPdfWindow(): void;
-    gotoPage(page: number): void;
-    setParams(values: Record<string, string>, opts?: {
-    reload?: boolean;
-    }): Promise<void> | void;
-    importExcel?(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2): Promise<ExcelImportResult | null>;
-    getPlan?(): RenderPlan | null;
-    getChanges?(): ReportCellEdit[];
-    getDifferences?(): ReportCellEdit[];
-    undo?(): Promise<boolean>;
-    redo?(): Promise<boolean>;
-    restoreChanges?(): Promise<boolean>;
-    getSelection?(): ReportCellSelection | null;
-    focusCell?(address: ReportCellAddress, extend?: boolean): Promise<boolean>;
-    focusField?(target: ReportFieldTarget): Promise<boolean>;
-    copySelection?(): string;
-    pasteSelection?(text: string): Promise<boolean>;
-    }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
-    warning: (message: string) => any;
-    error: (message: string, detail?: {
-    code: string;
-    cause?: unknown;
-    } | undefined) => any;
-    loaded: (pageCount: number) => any;
-    "cell-edit": (edit: ReportCellEdit) => any;
-    "template-import": (result: ExcelImportResult) => any;
-    "preferences-change": (preferences: Readonly<ReportPreviewPreferences>) => any;
-    }, PublicProps, {
-    editable: boolean | ReportEditingOptions;
-    height: string;
-    gapPx: number;
-    params: Record<string, string>;
-    reportId: string | string[] | null;
-    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;
-    }, 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;
-    thumbsRef: HTMLElement;
-    }, HTMLDivElement, ComponentProvideOptions, {
-    P: {};
-    B: {};
-    D: {};
-    C: {};
-    M: {};
-    Defaults: {};
-    }, Readonly<ExtractPropTypes<    {
-    reportId: {
-    type: PropType<string | string[] | null>;
-    default: null;
-    };
-    params: {
-    type: PropType<Record<string, string>>;
-    default: () => {};
-    };
-    height: {
-    type: StringConstructor;
-    default: string;
-    };
-    autoLoad: {
-    type: BooleanConstructor;
-    default: boolean;
-    };
-    showExport: {
-    type: BooleanConstructor;
-    default: undefined;
-    };
-    showPrint: {
-    type: BooleanConstructor;
-    default: undefined;
-    };
-    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;
-    };
-    messages: {
-    type: PropType<Partial<MachReportMessages>>;
-    default: undefined;
-    };
-    preset: {
-    type: StringConstructor;
-    default: undefined;
-    };
-    debug: {
-    type: BooleanConstructor;
-    default: boolean;
-    };
-    paramDefs: {
-    type: PropType<ReportParamDef[] | undefined>;
-    default: undefined;
-    };
-    showParams: {
-    type: BooleanConstructor;
-    default: undefined;
-    };
-    editable: {
-    type: PropType<boolean | ReportEditingOptions>;
-    default: undefined;
-    };
-    excelImport: {
-    type: PropType<boolean | ExcelImportOptions_2>;
-    default: undefined;
-    };
-    fetcher: {
-    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;
-    "onCell-edit"?: ((edit: ReportCellEdit) => any) | undefined;
-    "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
-    "onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
-    }>, {
-    state: ComputedRef<MachReportState>;
-    checkPdfFont?(): Promise<PdfFontCheckResult>;
-    reload(): Promise<void>;
-    print(): Promise<void>;
-    exportAs(format: string): Promise<void> | void;
-    openPdfWindow(): void;
-    gotoPage(page: number): void;
-    setParams(values: Record<string, string>, opts?: {
-    reload?: boolean;
-    }): Promise<void> | void;
-    importExcel?(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2): Promise<ExcelImportResult | null>;
-    getPlan?(): RenderPlan | null;
-    getChanges?(): ReportCellEdit[];
-    getDifferences?(): ReportCellEdit[];
-    undo?(): Promise<boolean>;
-    redo?(): Promise<boolean>;
-    restoreChanges?(): Promise<boolean>;
-    getSelection?(): ReportCellSelection | null;
-    focusCell?(address: ReportCellAddress, extend?: boolean): Promise<boolean>;
-    focusField?(target: ReportFieldTarget): Promise<boolean>;
-    copySelection?(): string;
-    pasteSelection?(text: string): Promise<boolean>;
-    }, {}, {}, {}, {
-    editable: boolean | ReportEditingOptions;
-    height: string;
-    gapPx: number;
-    params: Record<string, string>;
-    reportId: string | string[] | null;
-    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;
-    }>;
-    __isFragment?: never;
-    __isTeleport?: never;
-    __isSuspense?: never;
-} & ComponentOptionsBase<Readonly<ExtractPropTypes<    {
-reportId: {
-type: PropType<string | string[] | null>;
-default: null;
-};
-params: {
-type: PropType<Record<string, string>>;
-default: () => {};
-};
-height: {
-type: StringConstructor;
-default: string;
-};
-autoLoad: {
-type: BooleanConstructor;
-default: boolean;
-};
-showExport: {
-type: BooleanConstructor;
-default: undefined;
-};
-showPrint: {
-type: BooleanConstructor;
-default: undefined;
-};
-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;
-};
-messages: {
-type: PropType<Partial<MachReportMessages>>;
-default: undefined;
-};
-preset: {
-type: StringConstructor;
-default: undefined;
-};
-debug: {
-type: BooleanConstructor;
-default: boolean;
-};
-paramDefs: {
-type: PropType<ReportParamDef[] | undefined>;
-default: undefined;
-};
-showParams: {
-type: BooleanConstructor;
-default: undefined;
-};
-editable: {
-type: PropType<boolean | ReportEditingOptions>;
-default: undefined;
-};
-excelImport: {
-type: PropType<boolean | ExcelImportOptions_2>;
-default: undefined;
-};
-fetcher: {
-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;
-"onCell-edit"?: ((edit: ReportCellEdit) => any) | undefined;
-"onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
-"onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
-}>, {
-state: ComputedRef<MachReportState>;
-checkPdfFont?(): Promise<PdfFontCheckResult>;
-reload(): Promise<void>;
-print(): Promise<void>;
-exportAs(format: string): Promise<void> | void;
-openPdfWindow(): void;
-gotoPage(page: number): void;
-setParams(values: Record<string, string>, opts?: {
-reload?: boolean;
-}): Promise<void> | void;
-importExcel?(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2): Promise<ExcelImportResult | null>;
-getPlan?(): RenderPlan | null;
-getChanges?(): ReportCellEdit[];
-getDifferences?(): ReportCellEdit[];
-undo?(): Promise<boolean>;
-redo?(): Promise<boolean>;
-restoreChanges?(): Promise<boolean>;
-getSelection?(): ReportCellSelection | null;
-focusCell?(address: ReportCellAddress, extend?: boolean): Promise<boolean>;
-focusField?(target: ReportFieldTarget): Promise<boolean>;
-copySelection?(): string;
-pasteSelection?(text: string): Promise<boolean>;
-}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
-warning: (message: string) => any;
-error: (message: string, detail?: {
-code: string;
-cause?: unknown;
-} | undefined) => any;
-loaded: (pageCount: number) => any;
-"cell-edit": (edit: ReportCellEdit) => any;
-"template-import": (result: ExcelImportResult) => any;
-"preferences-change": (preferences: Readonly<ReportPreviewPreferences>) => any;
-}, string, {
-editable: boolean | ReportEditingOptions;
-height: string;
-gapPx: number;
-params: Record<string, string>;
-reportId: string | string[] | null;
-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;
-    };
-});
-
-/** 预览按需调优；默认已经启用正文/缩略图虚拟化及可取消的分片搜索。 */
-declare interface MachReportPreviewOptions {
-    /** 视口前后额外保留的正文页数，默认 1，归一化到 0~10 的整数。 */
-    overscanPages?: number;
-    /** 搜索输入防抖毫秒，默认 200，归一化到 0~2000。 */
-    searchDebounceMs?: number;
-}
-
-/** 只读快照，由组件的同一套状态驱动；无需通过事件另建状态。 */
-declare interface MachReportState {
-    readonly loading: boolean;
-    readonly hasPlan: boolean;
-    readonly pageCount: number;
-    readonly currentPage: number;
-    /** 当前导出显示名称，空闲时为 null。 */
-    readonly exporting: string | null;
-    readonly printing: boolean;
-    readonly canExport: boolean;
-    readonly canPrint: boolean;
-    readonly error: Readonly<MachReportStateError> | null;
-    readonly pdfFont: Readonly<PdfFontCheckResult>;
-    readonly editing?: boolean;
-    readonly saving?: boolean;
-    readonly importing?: boolean;
-    readonly dirty?: boolean;
-    readonly canUndo?: boolean;
-    readonly canRedo?: boolean;
-    readonly changeCount?: number;
-    readonly selection?: Readonly<ReportCellSelection> | null;
-}
-
-declare interface MachReportStateError {
-    message: string;
-    code: MachReportErrorCode;
-    cause?: unknown;
-}
-
-/** 主题变量（组件外壳注入的 --mrp-* CSS 自定义属性） */
-declare interface MachReportTheme {
-    shellBg: string;
-    shellFg: string;
-    toolbarBg: string;
-    toolbarBorder: string;
-    toolbarFg: string;
-    btnFg: string;
-    btnBorder: string;
-    btnHoverBg: string;
-    btnHoverFg: string;
-    btnActiveBg: string;
-}
-
-declare interface MachReportToolbarOptions {
-    search?: boolean;
-    thumbnails?: boolean;
-    zoom?: boolean;
-    /** 编辑能力由 editable 授权；此项仅设置初始交互偏好，默认 true（兼容旧行为）。 */
-    editing?: boolean;
-    /** 导入能力由 excelImport 授权；此项仅设置初始交互偏好，默认 true。 */
-    excelImport?: boolean;
-    /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
-    exportFormats?: ReportExportFormat[];
-}
-
-declare interface OutputDiagnostic {
-    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
-    severity: "warning";
-    format: OutputFormat;
-    pageIndex: number;
-    componentIndex: number;
-    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
-    componentPath?: readonly number[];
-    kind: string;
-    nid?: string;
-    message: string;
-}
-
-declare interface OutputDiagnostic_2 {
-    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
-    severity: "warning";
-    format: OutputFormat_2;
-    pageIndex: number;
-    componentIndex: number;
-    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
-    componentPath?: readonly number[];
-    kind: string;
-    nid?: string;
-    message: string;
-}
-
-declare interface OutputDiagnosticOptions {
-    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
-    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
-}
-
-declare interface OutputDiagnosticOptions_2 {
-    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
-    onDiagnostic?: (diagnostic: OutputDiagnostic_2) => void;
-}
-
-declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
-
-declare type OutputFormat_2 = "dom" | "canvas" | "pdf" | "xlsx";
-
-declare interface PaginateOptions {
-    /** 每行额外占高（mm），压测专用钩子 */
-    mmPerRow?: number;
-    /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
-    measurer?: TextMeasurer;
-    /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
-    maxPages?: number;
-}
-
-/** PDF 导出器：RenderPlan → PDF 字节；第二参数可上报非致命保真告警。 */
-declare interface PdfExporter {
-    (plan: RenderPlan, onWarning?: (message: string) => void): Promise<Uint8Array>;
-    /** 可选轻量字体检查；旧版自定义导出函数无需实现。取消时拒绝 AbortError。 */
-    checkFont?: (signal?: AbortSignal) => Promise<PdfFontCheckResult>;
-}
-
-declare interface PdfFontCheckResult {
-    status: PdfFontStatus;
-    fontUrl: string;
-    message?: string;
-    cause?: unknown;
-}
-
-/** available 仅表示字体资源可达；实际导出仍会校验文字能否编码。 */
-declare type PdfFontStatus = "unchecked" | "checking" | "available" | "disabled" | "unverified" | "error";
-
-declare interface PlanComponent {
-    kind: ComponentKind;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    heightMm: number;
-    nid?: string;
-    rkey?: string;
-    text?: string;
-    rawText?: string;
-    lines?: string[];
-    richParagraphs?: RichParagraph[];
-    imageData?: string;
-    /** 明确指定线段方向；省略保持历史水平线行为。 */
-    lineDirection?: "down" | "up";
-    grid?: PlanGrid;
-    table?: PlanTableFragment;
-    style?: ComponentStyle;
-    meta?: Record<string, unknown>;
-    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
-    fallbackText?: string;
-}
-
-declare interface PlanComponent_2 {
-    kind: ComponentKind_2;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    heightMm: number;
-    nid?: string;
-    rkey?: string;
-    text?: string;
-    rawText?: string;
-    lines?: string[];
-    richParagraphs?: RichParagraph_2[];
-    imageData?: string;
-    /** 明确指定线段方向；省略保持历史水平线行为。 */
-    lineDirection?: "down" | "up";
-    grid?: PlanGrid_2;
-    table?: PlanTableFragment_2;
-    style?: ComponentStyle_2;
-    meta?: Record<string, unknown>;
-    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
-    fallbackText?: string;
-}
-
-declare interface PlanComponent_3 {
-    kind: ComponentKind_3;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    heightMm: number;
-    nid?: string;
-    rkey?: string;
-    text?: string;
-    rawText?: string;
-    lines?: string[];
-    richParagraphs?: RichParagraph_3[];
-    imageData?: string;
-    /** 明确指定线段方向；省略保持历史水平线行为。 */
-    lineDirection?: "down" | "up";
-    grid?: PlanGrid_3;
-    table?: PlanTableFragment_3;
-    style?: ComponentStyle_3;
-    meta?: Record<string, unknown>;
-    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
-    fallbackText?: string;
-}
-
-declare interface PlanFetcher {
-    (input: ReportFetchInput): Promise<RenderPlan>;
-    getParamDefs?: ReportFetcher["getParamDefs"];
-}
-
-declare interface PlanGrid {
-    /** 行内允许 null 空位；渲染器按空单元格处理 */
-    cells: (GridCell | null)[][];
-    colWidthsMm?: number[];
-    rowHeightsMm?: number[];
-    gapMm?: number;
-    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
-    paddingMm?: number;
-}
-
-declare interface PlanGrid_2 {
-    /** 行内允许 null 空位；渲染器按空单元格处理 */
-    cells: (GridCell_2 | null)[][];
-    colWidthsMm?: number[];
-    rowHeightsMm?: number[];
-    gapMm?: number;
-    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
-    paddingMm?: number;
-}
-
-declare interface PlanGrid_3 {
-    /** 行内允许 null 空位；渲染器按空单元格处理 */
-    cells: (GridCell_3 | null)[][];
-    colWidthsMm?: number[];
-    rowHeightsMm?: number[];
-    gapMm?: number;
-    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
-    paddingMm?: number;
-}
-
-declare interface PlanPage {
-    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
-    layout?: "page" | "wide";
-    pageWidthMm: number;
-    pageHeightMm: number;
-    marginTopMm?: number;
-    marginBottomMm?: number;
-    marginLeftMm?: number;
-    marginRightMm?: number;
-    components: PlanComponent[];
-}
-
-/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
-declare interface PlanTableFragment {
-    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
-    id: string;
-    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
-    rowIndex: number;
-    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
-    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
-    columnKeys: string[];
-    layout?: "page" | "wide";
-    title?: string;
-    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
-    source?: Omit<ReportCellSource, "field" | "rowKey"> & { rowKey?: string | number };
-}
-
-/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
-declare interface PlanTableFragment_2 {
-    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
-    id: string;
-    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
-    rowIndex: number;
-    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
-    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
-    columnKeys: string[];
-    layout?: "page" | "wide";
-    title?: string;
-    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
-    source?: Omit<ReportCellSource_2, "field" | "rowKey"> & {
-        rowKey?: string | number;
-    };
-}
-
-/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
-declare interface PlanTableFragment_3 {
-    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
-    id: string;
-    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
-    rowIndex: number;
-    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
-    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
-    columnKeys: string[];
-    layout?: "page" | "wide";
-    title?: string;
-    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
-    source?: Omit<ReportCellSource_3, "field" | "rowKey"> & {
-        rowKey?: string | number;
-    };
-}
-
-/** 预取组件分片（路由 hover / 空闲时调用，正式渲染零等待） */
-export declare function preloadMachReport(): Promise<unknown>;
-
-declare interface RenderPlan {
-    schemaVersion: string;
-    pages: PlanPage[];
-}
-
-/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
-declare interface ReportCellAddress {
-    pageIndex: number;
-    componentIndex: number;
-    rowIndex: number;
-    columnIndex: number;
-}
-
-/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
-declare interface ReportCellAddress_2 {
-    pageIndex: number;
-    componentIndex: number;
-    rowIndex: number;
-    columnIndex: number;
-}
-
-declare interface ReportCellContext {
-    address: ReportCellAddress_2;
-    cell: Readonly<GridCell_2>;
-    component: Readonly<PlanComponent_2>;
-    value: ReportCellValue_2;
-    valueType: ReportCellValueType;
-    table?: ReportCellTableIdentity_2;
-    /** Stable business identity. Physical row indices must never be used as database keys. */
-    source?: Readonly<ReportCellSource_2>;
-    editable: boolean;
-    readOnlyReason?: ReportCellReadOnlyReason;
-}
-
-declare interface ReportCellEdit {
-    address: ReportCellAddress;
-    table?: ReportCellTableIdentity;
-    source?: Readonly<ReportCellSource>;
-    previousValue: ReportCellValue;
-    previousText: string;
-    value: ReportCellValue;
-    text: string;
-}
-
-declare interface ReportCellEdit_2 {
-    address: ReportCellAddress_2;
-    table?: ReportCellTableIdentity_2;
-    source?: Readonly<ReportCellSource_2>;
-    previousValue: ReportCellValue_2;
-    previousText: string;
-    value: ReportCellValue_2;
-    text: string;
-}
-
-declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
-
-declare interface ReportCellSelection {
-    anchor: ReportCellAddress;
-    focus: ReportCellAddress;
-}
-
-/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
-declare interface ReportCellSource {
-    datasetId: string;
-    rowKey: string | number;
-    field: string;
-    revision?: string | number;
-    sourceToken?: string;
-}
-
-/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
-declare interface ReportCellSource_2 {
-    datasetId: string;
-    rowKey: string | number;
-    field: string;
-    revision?: string | number;
-    sourceToken?: string;
-}
-
-/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
-declare interface ReportCellSource_3 {
-    datasetId: string;
-    rowKey: string | number;
-    field: string;
-    revision?: string | number;
-    sourceToken?: string;
-}
-
-declare interface ReportCellTableIdentity {
-    id: string;
-    /** 逻辑表行索引；跨分页的同一行保持不变。 */
-    rowIndex: number;
-    role: PlanTableFragment["role"];
-    columnKey?: string;
-}
-
-declare interface ReportCellTableIdentity_2 {
-    id: string;
-    /** 逻辑表行索引；跨分页的同一行保持不变。 */
-    rowIndex: number;
-    role: PlanTableFragment_2["role"];
-    columnKey?: string;
-}
-
-declare type ReportCellValue = string | number | boolean | null;
-
-declare type ReportCellValue_2 = string | number | boolean | null;
-
-declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
-
-declare interface ReportDefinition {
-    /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
-    template: ReportTemplate | ReportTemplateLoader;
-    /** 静态数据；load 存在时优先使用 load 的结果。 */
-    datasets?: DatasetRows;
-    load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
-    /** 可选统一适配器；load 存在时仍优先 load，兼容已有定义。 */
-    provider?: ReportProvider;
-    /** 可选业务数据契约；声明的数据集缺失或字段不合法时，在分页前给出结构化错误。 */
-    dataSchema?: Record<string, DatasetContract>;
-    dataValidation?: Pick<DatasetValidationOptions, "maxRows" | "maxCells" | "maxIssues">;
-    /** 覆盖模板参数定义；动态模板应在此声明查询面板元数据，避免查询前先请求模板。 */
-    params?: ReportParamDef[];
-    pagination?: PaginateOptions;
-}
-
-declare interface ReportDiagnostic { code: string; message: string; path?: string; severity: "warning" | "error" | "info" }
-
-declare interface ReportEditBatch {
-    /** Idempotency identity; the server should bind it to the exact payload. */
-    requestId: string;
-    edits: ReportCellEdit_2[];
-}
-
-declare interface ReportEditConflict {
-    source?: Readonly<ReportCellSource_2>;
-    address?: ReportCellAddress_2;
-    message: string;
-    currentValue?: ReportCellValue_2;
-    revision?: string | number;
-}
-
-/** Opt in with true for local drafts, or provide host validation and persistence. */
-declare interface ReportEditingOptions {
-    canEdit?(context: ReportCellContext): boolean;
-    /** Return an error message or throw to reject the edit. */
-    validate?(edit: Readonly<ReportCellEdit_2>, operation: ReportEditOperation): void | string | Promise<void | string>;
-    /** Called before applying the change. A rejection leaves the current report untouched. */
-    save?(edit: Readonly<ReportCellEdit_2>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
-    /** Must commit all edits in one server transaction. Required for multi-cell persisted edits. */
-    saveBatch?(batch: Readonly<ReportEditBatch>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
-    /** Restrict persistence to plans that supply stable datasetId/rowKey/field metadata. */
-    requireSource?: boolean;
-}
-
-declare interface ReportEditOperation {
-    /** Reload, another import or unmount aborts the operation. Save adapters should forward this signal. */
-    signal: AbortSignal;
-    requestId?: string;
-    action?: "edit" | "undo" | "redo" | "restore";
-}
-
-declare interface ReportEditResult {
-    /** A successful result may advance concurrency tokens for the affected dataset. */
-    revision?: string | number;
-    sourceToken?: string;
-    /** Any conflict rejects the entire client batch. A server must also transact atomically. */
-    conflicts?: readonly ReportEditConflict[];
-}
-
-/** 报表含表头但业务行为空时，由接入方明确声明；组件不推测业务数据。 */
-declare interface ReportEmptyState {
-    title?: string;
-    description?: string;
-}
-
-/** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
-declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
-
-/** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
-declare interface ReportFetcher {
-    (input: ReportFetchInput): Promise<RenderPlan>;
-    getParamDefs?: (reportIds: string[]) => ReportParamDef[];
-}
-
-declare interface ReportFetchInput {
-    reportIds: string[];
-    params: Record<string, string>;
-    signal?: AbortSignal;
-    /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
-    onWarning?: (message: string) => void;
-    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
-}
-
-declare interface ReportFieldContract {
-    field: string;
-    label?: string;
-    type: "text" | "number" | "boolean" | "date" | "decimal";
-    required?: boolean;
-    nullable?: boolean;
-    enum?: readonly (string | number | boolean)[];
-    min?: number; max?: number;
-    minLength?: number; maxLength?: number;
-    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
-    unit?: string;
-}
-
-declare interface ReportFieldTarget {
-    field: string;
-    datasetId?: string;
-    rowKey?: string | number;
-}
-
-declare interface ReportInteractionOptions {
-    /** Screen-only frozen panes; exported geometry is unchanged. */
-    freezeHeaders?: boolean;
-    /** Leading identity columns, from 0 to 20. */
-    frozenColumns?: number;
-    /** Show workbook sheets / report sections when available. Default true. */
-    navigation?: boolean;
-}
-
-/** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
-declare interface ReportLoadContext {
-    reportId: string;
-    params: Record<string, string>;
-    signal?: AbortSignal;
-}
-
-/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
-declare interface ReportParamDef {
-    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
-    field: string;
-    /** 显示名（缺省用 field） */
-    label?: string;
-    type?: "text" | "number" | "date" | "select";
-    /** select 选项 */
-    options?: Array<{ label: string; value: string }>;
-    defaultValue?: string;
-    required?: boolean;
-    placeholder?: string;
-    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
-    min?: number | string;
-    max?: number | string;
-    minLength?: number;
-    maxLength?: number;
-}
-
-/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
-declare interface ReportParamDef_2 {
-    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
-    field: string;
-    /** 显示名（缺省用 field） */
-    label?: string;
-    type?: "text" | "number" | "date" | "select";
-    /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
-    defaultValue?: string;
-    required?: boolean;
-    placeholder?: string;
-    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
-    min?: number | string;
-    max?: number | string;
-    minLength?: number;
-    maxLength?: number;
-}
-
-declare interface ReportParamIssue { code: ReportParamIssueCode; path: string; field: string; message: string }
-
-declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
-
-declare interface ReportPreferencesAdapter {
-    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
-    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
-    remove?(key: string): void | Promise<void>;
-}
-
-declare interface ReportPreferencesOptions {
-    /** Host-scoped key; do not share one key between unrelated users/tenants. */
-    key: string;
-    adapter: ReportPreferencesAdapter;
-}
-
-declare type ReportPreviewPreferences = Record<ReportPreviewTool, boolean>;
-
-declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
-
-/** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
-declare interface ReportProvider {
-    query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
-    save?(input: ReportSaveInput): ReportSaveResult | Promise<ReportSaveResult>;
-    export?(input: ReportProviderExportInput): ReportProviderExportResult | Promise<ReportProviderExportResult>;
-    templates?: ReportTemplateProvider;
-}
-
-declare interface ReportProviderExportInput extends ReportLoadContext { format: "pdf" | "xlsx" }
-
-declare interface ReportProviderExportResult { bytes: Uint8Array; contentType: string; fileName?: string; diagnostics?: ReportDiagnostic[] }
-
-declare interface ReportQueryResult {
-    datasets: DatasetRows;
-    revision?: string;
-    sourceToken?: string;
-    diagnostics?: ReportDiagnostic[];
-}
-
-declare type ReportRegistry = Record<string, ReportDefinition>;
-
-declare interface ReportSaveInput extends ReportLoadContext {
-    requestId: string;
-    expectedRevision?: string;
-    sourceToken?: string;
-    edits: readonly ReportCellEdit[];
-    action?: "edit" | "undo" | "redo" | "restore";
-}
-
-declare interface ReportSaveResult {
-    revision: string;
-    sourceToken?: string;
-    conflicts?: Array<{ editIndex: number; code: string; message: string }>;
-    diagnostics?: ReportDiagnostic[];
-}
-
-declare interface ReportTemplate {
-    schemaVersion?: string;
-    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
-    params?: ReportParamDef[];
-    pages: TemplatePage[];
-}
-
-declare interface ReportTemplate_2 {
-    schemaVersion?: string;
-    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
-    params?: ReportParamDef_2[];
-    pages: TemplatePage_2[];
-}
-
-/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
-declare interface ReportTemplateDocument {
-    schemaVersion: "1.0";
-    id: string;
-    name: string;
-    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
-    revision?: string;
-    description?: string;
-    template: ReportTemplate;
-}
-
-declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
-
-declare interface ReportTemplateProvider {
-    list(context: { signal?: AbortSignal }): Promise<ReportTemplateSummary[]>;
-    get(id: string, context: { signal?: AbortSignal }): Promise<ReportTemplateDocument | undefined>;
-}
-
-declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
-
-declare interface RichParagraph {
-    segments: RichSegment[];
-    align?: ComponentStyle["align"];
-    lineHeight?: number;
-    spaceBeforeMm?: number;
-    spaceAfterMm?: number;
-    indentMm?: number;
-}
-
-declare interface RichParagraph_2 {
-    segments: RichSegment_2[];
-    align?: ComponentStyle_2["align"];
-    lineHeight?: number;
-    spaceBeforeMm?: number;
-    spaceAfterMm?: number;
-    indentMm?: number;
-}
-
-declare interface RichParagraph_3 {
-    segments: RichSegment_3[];
-    align?: ComponentStyle_3["align"];
-    lineHeight?: number;
-    spaceBeforeMm?: number;
-    spaceAfterMm?: number;
-    indentMm?: number;
-}
-
-declare interface RichSegment {
-    kind?: "text" | "field";
-    text?: string;
-    field?: string;
-    style?: ComponentStyle;
-}
-
-declare interface RichSegment_2 {
-    kind?: "text" | "field";
-    text?: string;
-    field?: string;
-    style?: ComponentStyle_2;
-}
-
-declare interface RichSegment_3 {
-    kind?: "text" | "field";
-    text?: string;
-    field?: string;
-    style?: ComponentStyle_3;
-}
-
-/** 条件格式规则求值（声明式，见 ListColumn.rules） */
-declare interface StyleRule {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-    };
-    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
-    style: Record<string, unknown>;
-}
-
-/** 条件格式规则求值（声明式，见 ListColumn.rules） */
-declare interface StyleRule_2 {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-    };
-    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
-    style: Record<string, unknown>;
-}
-
-declare type TemplateComponent = PlanComponent | ListComponent;
-
-declare type TemplateComponent_2 = PlanComponent_3 | ListComponent_2;
-
-declare interface TemplatePage {
-    widthMm: number;
-    heightMm: number;
-    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
-    layout?: "page" | "wide";
-    marginTopMm?: number;
-    marginBottomMm?: number;
-    marginLeftMm?: number;
-    marginRightMm?: number;
-    components: TemplateComponent[];
-}
-
-declare interface TemplatePage_2 {
-    widthMm: number;
-    heightMm: number;
-    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
-    layout?: "page" | "wide";
-    marginTopMm?: number;
-    marginBottomMm?: number;
-    marginLeftMm?: number;
-    marginRightMm?: number;
-    components: TemplateComponent_2[];
-}
-
-/**
- * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
- *
- * 测量模型可注入（TextMeasurer）：
- * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
- * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
- */
-
-declare interface TextMeasureOptions {
-    fontSizePt: number;
-    fontFamily?: string;
-    bold?: boolean;
-    italic?: boolean;
-    letterSpacingPt?: number;
-}
-
-/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
-declare interface TextMeasurer {
-    measureMm(text: string, options: TextMeasureOptions): number;
-}
-
-/**
- * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
- * - 网格组件 → 真表格：列宽（mm→Excel 宽度）、行高（mm→pt）、colSpan/rowSpan 合并、
- *   加粗/对齐/底色/字号直译（resolveGridLayout 复用单真相源几何）
- * - 文本组件 → 合并标题行（顺序流式输出，保字号/加粗/对齐；非像素级定位，
- *   目标是"财务能直接用的对账表"而非复刻版面）
- * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
- */
-declare interface XlsxRenderOptions extends OutputDiagnosticOptions_2 {
-    /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
-    sheetName?: (sheetIndex: number) => string;
-    /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
-    sheetMode?: "auto" | "pages" | "continuous";
-    /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
-    valueMode?: "text" | "raw";
-    /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
-    paperSize?: "auto" | "a3" | "a4" | "a5";
-}
-
-export { }
+import { AllowedComponentProps } from 'vue';
+import { App } from 'vue';
+import { ComponentCustomProps } from 'vue';
+import { ComponentOptionsMixin } from 'vue';
+import { ComputedRef } from 'vue';
+import { ExtractPropTypes } from 'vue';
+import { PropType } from 'vue';
+import { VNodeProps } from 'vue';
+declare interface AssetRenderBudget {
+    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
+    maxAssets?: number;
+    /** Maximum image payload bytes per new asset, default 32 MiB. */
+    maxImageBytes?: number;
+    /** Maximum total image payload bytes for new assets, default 128 MiB. */
+    maxTotalImageBytes?: number;
+    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
+    maxDurationMs?: number;
+}
+declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    assetBudget?: AssetRenderBudget;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+/**
+ * 列值格式化（声明式、JSON 可序列化）。
+ * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+declare type ColumnFormat = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+/**
+ * 列值格式化（声明式、JSON 可序列化）。
+ * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+declare type ColumnFormat_2 = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "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 {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+declare interface ComponentStyle_2 {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+declare interface ComponentStyle_3 {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+declare interface DatasetContract {
+    fields: readonly ReportFieldContract[];
+    rowKey?: string;
+}
+declare type DatasetRows = Record<string, Record<string, unknown>[]>;
+declare interface DatasetValidationOptions {
+    path?: string;
+    maxRows?: number;
+    maxCells?: number;
+    maxIssues?: number;
+}
+declare interface ExcelImportedSheet {
+    name: string;
+    /** Original, one-based workbook position. */
+    index: number;
+    range: string;
+    rowCount: number;
+    columnCount: number;
+    /** Zero-based index into template.pages. */
+    pageStart: number;
+    pageCount: number;
+}
+/** Limits apply to the selected rectangular ranges, including their empty cells. */
+declare interface ExcelImportLimits {
+    /** Compressed input, default 20 MiB. */
+    maxFileBytes?: number;
+    /** Declared ZIP uncompressed total, default 64 MiB. */
+    maxUncompressedBytes?: number;
+    /** Total selected cells across sheets, default 250,000; hard ceiling 1,000,000. */
+    maxCells?: number;
+    /** Rows per selected sheet, default 100,000; hard ceiling 1,048,576. */
+    maxRows?: number;
+    /** Columns per selected sheet, default 2,048; hard ceiling 16,384. */
+    maxColumns?: number;
+    /** Workbook sheets, default 32. */
+    maxSheets?: number;
+}
+/** Limits apply to the selected rectangular ranges, including their empty cells. */
+declare interface ExcelImportLimits_2 {
+    /** Compressed input, default 20 MiB. */
+    maxFileBytes?: number;
+    /** Declared ZIP uncompressed total, default 64 MiB. */
+    maxUncompressedBytes?: number;
+    /** Total selected cells across sheets, default 250,000; hard ceiling 1,000,000. */
+    maxCells?: number;
+    /** Rows per selected sheet, default 100,000; hard ceiling 1,048,576. */
+    maxRows?: number;
+    /** Columns per selected sheet, default 2,048; hard ceiling 16,384. */
+    maxColumns?: number;
+    /** Workbook sheets, default 32. */
+    maxSheets?: number;
+}
+declare interface ExcelImportOptions extends OutputTaskOptions_2 {
+    /** Sheet names or one-based workbook positions. Default: all visible sheets. */
+    sheets?: Array<string | number>;
+    /** A1 range for every sheet, or ranges keyed by exact sheet name. */
+    range?: string | Record<string, string>;
+    /** Wide preserves natural column widths. A3/A4 scale the complete width to paper. */
+    layout?: "wide" | "a3" | "a4";
+    /** Only applies to A3/A4; default landscape. */
+    landscape?: boolean;
+    /** Vertical preview segment limit, default 80, maximum 200. Merges remain intact. */
+    maxRowsPerPage?: number;
+    /** Optional resource limits; hard ceilings prevent unbounded allocations. */
+    limits?: ExcelImportLimits;
+}
+declare interface ExcelImportOptions_2 extends OutputTaskOptions_3 {
+    /** Sheet names or one-based workbook positions. Default: all visible sheets. */
+    sheets?: Array<string | number>;
+    /** A1 range for every sheet, or ranges keyed by exact sheet name. */
+    range?: string | Record<string, string>;
+    /** Wide preserves natural column widths. A3/A4 scale the complete width to paper. */
+    layout?: "wide" | "a3" | "a4";
+    /** Only applies to A3/A4; default landscape. */
+    landscape?: boolean;
+    /** Vertical preview segment limit, default 80, maximum 200. Merges remain intact. */
+    maxRowsPerPage?: number;
+    /** Optional resource limits; hard ceilings prevent unbounded allocations. */
+    limits?: ExcelImportLimits_2;
+}
+declare interface ExcelImportResult {
+    template: ReportTemplate_2;
+    warnings: string[];
+    sheets: ExcelImportedSheet[];
+}
+declare interface GridCell {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    source?: ReportCellSource;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+declare interface GridCell_2 {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    source?: ReportCellSource_2;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent_2[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle_2;
+}
+declare interface GridCell_3 {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    source?: ReportCellSource_3;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent_3[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle_3;
+}
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+declare type ListAlignment_2 = NonNullable<ComponentStyle_3["align"]> | "auto";
+declare interface ListColumn {
+    header: string;
+    field: string;
+    widthMm: number;
+    style?: ComponentStyle;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle;
+    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
+    format?: ColumnFormat;
+    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
+    rules?: StyleRule[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+}
+declare interface ListColumn_2 {
+    header: string;
+    field: string;
+    widthMm: number;
+    style?: ComponentStyle_3;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment_2;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle_3["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle_3;
+    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
+    format?: ColumnFormat_2;
+    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
+    rules?: StyleRule_2[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell_3["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+}
+declare interface ListComponent {
+    kind: "list";
+    id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
+    columns: ListColumn[];
+    fontSizePt?: number;
+    headerBold?: boolean;
+    rowHeightMm?: number;
+    paddingMm?: number;
+    headerEveryPage?: boolean;
+    headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle["align"];
+    headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
+    border?: boolean;
+    /** 分组小计（组头/组尾小计/组头防孤行） */
+    groupBy?: ListGroupBy;
+    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
+    grandTotal?: ListGrandTotal;
+}
+declare interface ListComponent_2 {
+    kind: "list";
+    id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
+    columns: ListColumn_2[];
+    fontSizePt?: number;
+    headerBold?: boolean;
+    rowHeightMm?: number;
+    paddingMm?: number;
+    headerEveryPage?: boolean;
+    headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment_2;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle_3["align"];
+    headerStyle?: ComponentStyle_3;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid_3;
+    border?: boolean;
+    /** 分组小计（组头/组尾小计/组头防孤行） */
+    groupBy?: ListGroupBy_2;
+    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
+    grandTotal?: ListGrandTotal_2;
+}
+declare type ListGrandTotal = boolean | {
+    label?: string;
+    style?: ComponentStyle;
+    /** 合计列（缺省沿用 groupBy.subtotal） */
+    fields?: string[];
+};
+declare type ListGrandTotal_2 = boolean | {
+    label?: string;
+    style?: ComponentStyle_3;
+    /** 合计列（缺省沿用 groupBy.subtotal） */
+    fields?: string[];
+};
+/** 分组小计配置（声明式，见 ListComponent.groupBy） */
+declare interface ListGroupBy {
+    /** 分组字段（值变化即切组） */
+    field: string;
+    /** 组头文案模板，{value} 占位（默认 "{value}"） */
+    headerTemplate?: string;
+    headerStyle?: ComponentStyle;
+    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
+    subtotal?: string[];
+    subtotalStyle?: ComponentStyle;
+    subtotalLabel?: string;
+    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
+    keepWithNext?: boolean;
+}
+/** 分组小计配置（声明式，见 ListComponent.groupBy） */
+declare interface ListGroupBy_2 {
+    /** 分组字段（值变化即切组） */
+    field: string;
+    /** 组头文案模板，{value} 占位（默认 "{value}"） */
+    headerTemplate?: string;
+    headerStyle?: ComponentStyle_3;
+    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
+    subtotal?: string[];
+    subtotalStyle?: ComponentStyle_3;
+    subtotalLabel?: string;
+    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
+    keepWithNext?: boolean;
+}
+declare const machReportAsyncPlugin: {
+    install(app: App, options?: MachReportPluginOptions): void;
+};
+export default machReportAsyncPlugin;
+export { machReportAsyncPlugin };
+declare interface MachReportConfig {
+    defaults: MachReportDefaults;
+    presets: Record<string, MachReportPreset>;
+    /** 默认启用的 preset 名 */
+    defaultPreset?: string;
+}
+/** defaults 层可配置项（全部可选，均有内置缺省） */
+declare interface MachReportDefaults {
+    showExport?: boolean;
+    showPrint?: boolean;
+    showPdfWindow?: boolean;
+    /** 设置入口默认显示；可在其中按需启用阅读及输出工具。 */
+    showSettings?: boolean;
+    toolbar?: MachReportToolbarOptions;
+    interaction?: ReportInteractionOptions;
+    preferences?: ReportPreferencesOptions;
+    /** Protect local input and drafts before replacing a report. Default true. */
+    guardChanges?: boolean;
+    beforeDiscard?: ReportBeforeDiscard;
+    output?: ReportOutputOptions;
+    /** Prepare optional image/chart/QR/barcode adapters once for preview and all outputs. */
+    assets?: AssetRenderOptions;
+    /** 参数面板显隐（有参数定义且未显式关闭时显示；缺省 true） */
+    showParams?: boolean;
+    /** 页间距 px */
+    gapPx?: number;
+    /** PDF 导出中文字体 URL */
+    pdfFontUrl?: string;
+    theme?: Partial<MachReportTheme>;
+    messages?: Partial<MachReportMessages>;
+    /** 校验告警等内部日志通道（默认 console；静默传 { warn: () => {}, info: () => {} }） */
+    logger?: MachReportLogger;
+    preview?: MachReportPreviewOptions;
+    /** Excel 出口配置，按字段继承；不配置使用导出器默认值。 */
+    xlsx?: XlsxRenderOptions;
+    /** 默认关闭；true 为本地草稿，对象可提供权限、校验和保存回调。 */
+    editable?: boolean | ReportEditingOptions;
+    /** 默认关闭；启用后提供导入按钮。ExcelJS 仅在导入时加载。 */
+    excelImport?: boolean | ExcelImportOptions;
+}
+/**
+ * 结构化错误（code 分类，宿主可按码决定 UX：重试 / 提示 / 降级）。
+ * error 事件契约保持 `(message: string)` 不变，新增第二参数 detail（可选）。
+ */
+declare type MachReportErrorCode = "param" | "fetch" | "validate" | "render" | "pdf" | "print" | "export" | "edit" | "import" | "config";
+/** 日志通道（默认 console；可注入 noop 静默或上报 collector） */
+declare type MachReportLogger = Pick<Console, "warn" | "info">;
+/**
+ * 配置中心（对齐 mach-table 的 defineMachTableConfig 体验）：
+ * - 应用级：app.use(machReportPlugin, { config: defineMachReportConfig({...}) })
+ * - 路由级叠加：provideMachReportConfig(overlay)（响应式，就近覆盖）
+ * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
+ */
+/** 工具栏与状态文案（默认简体中文；出海场景覆写） */
+declare interface MachReportMessages {
+    title: string;
+    prevPage: string;
+    nextPage: string;
+    /** 页码显示模板，{cur}/{total} 占位 */
+    pageInfo: string;
+    fitWidth: string;
+    exportHtml: string;
+    exportPdf: string;
+    exportExcel: string;
+    exportImage: string;
+    exportWord: string;
+    /** 导出进行中提示，{format} 占位 */
+    exporting: string;
+    print: string;
+    pdfWindow: string;
+    loading: string;
+    empty: string;
+    /** @deprecated 未被组件消费，将在下个大版本移除（保留仅为类型兼容） */
+    errorPrefix: string;
+    retry: string;
+    /** 可选新增文案，保留旧完整文案对象兼容。 */
+    pdfFontUnavailable?: string;
+    /** 搜索框占位文案 */
+    searchPlaceholder: string;
+    /** 搜索命中计数，{cur}/{total} 占位 */
+    matchInfo: string;
+    /** 上/下一个命中 */
+    prevMatch: string;
+    nextMatch: string;
+    /** 缩略图侧栏开关 */
+    thumbnails: string;
+    /** 参数面板 */
+    paramsTitle: string;
+    query: string;
+    reset: string;
+    /** 必填缺失提示（{label} 占位） */
+    paramRequired: string;
+    paramInvalid?: string;
+    paramPrompt?: string;
+    paramPromptDescription?: string;
+    paramSelectPlaceholder?: string;
+    paramTextPlaceholder?: string;
+    /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
+    searching?: string;
+    importExcel?: string;
+    importing?: string;
+    editCell?: string;
+    editingHint?: string;
+    saving?: string;
+    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;
+    columnDirectory?: string;
+    columnSearch?: string;
+    columnNoMatches?: string;
+    columnResults?: string;
+    columnGroup?: string;
+    discardTitle?: string;
+    discardDescription?: string;
+    discardKeep?: string;
+    discardProceed?: string;
+    taskQuery?: string;
+    taskValidate?: string;
+    taskLayout?: string;
+    taskAssets?: string;
+    taskEncode?: string;
+    taskDownload?: string;
+    taskPrint?: string;
+    taskCancel?: string;
+    taskCancelled?: string;
+    diagnosticsTitle?: string;
+    diagnosticsSearch?: string;
+    diagnosticsMore?: string;
+    diagnosticsLocate?: string;
+    diagnosticsLocation?: string;
+    diagnosticsStrict?: string;
+    diagnosticsDetails?: string;
+    diagnosticMissingImage?: string;
+    diagnosticUnsupported?: string;
+    diagnosticUnsupportedStyle?: string;
+    diagnosticImageFormat?: string;
+    diagnosticRichText?: string;
+    diagnosticNested?: string;
+    diagnosticImageAsync?: string;
+    diagnosticImageDecode?: string;
+    diagnosticAssetFailed?: string;
+    diagnosticAssetBudget?: string;
+}
+declare interface MachReportPluginOptions {
+    /** 报表数据源；也可直接传给 ReportPreview 的 fetcher prop */
+    fetcher?: PlanFetcher;
+    /** 常规业务接入：注册模板与取数，包内完成分页与参数面板；显式 fetcher 优先。 */
+    reports?: ReportRegistry;
+    /** 应用级配置中心（defaults/presets/文案/主题），见 defineMachReportConfig */
+    config?: MachReportConfig;
+    /** PDF 导出字体 URL（默认 /simhei.ttf；'' 跳过字体） */
+    pdfFontUrl?: string;
+    /** 自定义 PDF 导出器（缺省用懒加载引擎 /pdf 子路径的默认实现） */
+    pdfExporter?: PdfExporter;
+    /** 注册全局组件 <MachReportPreview>（默认 true；懒加载分片不影响首屏） */
+    globalComponent?: boolean;
+}
+declare type MachReportPreset = MachReportDefaults;
+/**
+ * 全局组件（懒加载分片：首次渲染才拉取组件与引擎依赖，
+ * 与局部 import 等价——首屏敏感页面零额外成本）
+ */
+export declare const MachReportPreview: typeof import("@agile-team/mach-report/vue").ReportPreview;
+/** 预览按需调优；默认已经启用正文/缩略图虚拟化及可取消的分片搜索。 */
+declare interface MachReportPreviewOptions {
+    /** 视口前后额外保留的正文页数，默认 1，归一化到 0~10 的整数。 */
+    overscanPages?: number;
+    /** 搜索输入防抖毫秒，默认 200，归一化到 0~2000。 */
+    searchDebounceMs?: number;
+}
+/** 只读快照，由组件的同一套状态驱动；无需通过事件另建状态。 */
+declare interface MachReportState {
+    readonly loading: boolean;
+    readonly hasPlan: boolean;
+    readonly pageCount: number;
+    readonly currentPage: number;
+    /** 当前导出显示名称，空闲时为 null。 */
+    readonly exporting: string | null;
+    readonly printing: boolean;
+    readonly canExport: boolean;
+    readonly canPrint: boolean;
+    readonly error: Readonly<MachReportStateError> | null;
+    readonly pdfFont: Readonly<PdfFontCheckResult>;
+    readonly editing?: boolean;
+    readonly saving?: boolean;
+    readonly importing?: boolean;
+    readonly dirty?: boolean;
+    readonly pendingLocalChanges?: boolean;
+    readonly task?: Readonly<ReportPreviewTask> | null;
+    readonly diagnostics?: readonly Readonly<ReportPreviewDiagnostic>[];
+    /** Context of the displayed API snapshot, which can differ from an unexecuted query form. */
+    readonly reportIds?: readonly string[];
+    readonly params?: Readonly<Record<string, string>>;
+    readonly canUndo?: boolean;
+    readonly canRedo?: boolean;
+    readonly changeCount?: number;
+    readonly selection?: Readonly<ReportCellSelection> | null;
+}
+declare interface MachReportStateError {
+    message: string;
+    code: MachReportErrorCode;
+    cause?: unknown;
+}
+/** 主题变量（组件外壳注入的 --mrp-* CSS 自定义属性） */
+declare interface MachReportTheme {
+    shellBg: string;
+    shellFg: string;
+    toolbarBg: string;
+    toolbarBorder: string;
+    toolbarFg: string;
+    btnFg: string;
+    btnBorder: string;
+    btnHoverBg: string;
+    btnHoverFg: string;
+    btnActiveBg: string;
+}
+declare interface MachReportToolbarOptions {
+    search?: boolean;
+    thumbnails?: boolean;
+    zoom?: boolean;
+    /** 编辑能力由 editable 授权；此项仅设置初始交互偏好，默认 true（兼容旧行为）。 */
+    editing?: boolean;
+    /** 导入能力由 excelImport 授权；此项仅设置初始交互偏好，默认 true。 */
+    excelImport?: boolean;
+    /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
+    exportFormats?: ReportExportFormat[];
+}
+declare interface OutputDiagnostic {
+    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "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" | "unsupported-style" | "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 extends OutputTaskOptions {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+declare interface OutputDiagnosticOptions_2 extends OutputTaskOptions_2 {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic_2) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+declare type OutputFormat_2 = "dom" | "canvas" | "pdf" | "xlsx";
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions_2 {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions_3 {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+declare interface PaginateOptions {
+    /** 每行额外占高（mm），压测专用钩子 */
+    mmPerRow?: number;
+    /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
+    measurer?: TextMeasurer;
+    /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
+    maxPages?: number;
+}
+/** PDF 导出器：RenderPlan → PDF 字节；第二参数可上报非致命保真告警。 */
+declare interface PdfExporter {
+    (plan: RenderPlan, onWarning?: (message: string) => void, task?: OutputTaskOptions_2 & {
+        onDiagnostic?: (entry: OutputDiagnostic) => void;
+    }): Promise<Uint8Array>;
+    /** 可选轻量字体检查；旧版自定义导出函数无需实现。取消时拒绝 AbortError。 */
+    checkFont?: (signal?: AbortSignal) => Promise<PdfFontCheckResult>;
+}
+declare interface PdfFontCheckResult {
+    status: PdfFontStatus;
+    fontUrl: string;
+    message?: string;
+    cause?: unknown;
+}
+/** available 仅表示字体资源可达；实际导出仍会校验文字能否编码。 */
+declare type PdfFontStatus = "unchecked" | "checking" | "available" | "disabled" | "unverified" | "error";
+declare interface PlanComponent {
+    kind: ComponentKind;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid;
+    table?: PlanTableFragment;
+    style?: ComponentStyle;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+declare interface PlanComponent_2 {
+    kind: ComponentKind_2;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph_2[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid_2;
+    table?: PlanTableFragment_2;
+    style?: ComponentStyle_2;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+declare interface PlanComponent_3 {
+    kind: ComponentKind_3;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph_3[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid_3;
+    table?: PlanTableFragment_3;
+    style?: ComponentStyle_3;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+declare interface PlanFetcher {
+    (input: ReportFetchInput): Promise<RenderPlan>;
+    getParamDefs?: ReportFetcher["getParamDefs"];
+}
+declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+declare interface PlanGrid_2 {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell_2 | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+declare interface PlanGrid_3 {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell_3 | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+declare interface PlanPage {
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
+    pageWidthMm: number;
+    pageHeightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: PlanComponent[];
+}
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment_2 {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource_2, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment_3 {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource_3, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+/** 预取组件分片（路由 hover / 空闲时调用，正式渲染零等待） */
+export declare function preloadMachReport(): Promise<unknown>;
+declare interface RenderPlan {
+    schemaVersion: string;
+    pages: PlanPage[];
+}
+/** Return false to keep the current report. Without a hook the preview asks inline. */
+declare type ReportBeforeDiscard = (context: Readonly<ReportBeforeDiscardContext>) => boolean | Promise<boolean>;
+declare interface ReportBeforeDiscardContext {
+    reason: ReportDiscardReason;
+    reportIds: readonly string[];
+    /** Local input or a local draft, never a synonym for persisted differences. */
+    pendingLocalChanges: true;
+}
+/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
+declare interface ReportCellAddress {
+    pageIndex: number;
+    componentIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}
+/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
+declare interface ReportCellAddress_2 {
+    pageIndex: number;
+    componentIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}
+declare interface ReportCellChoice {
+    value: Exclude<ReportCellValue_2, null>;
+    label?: string;
+}
+declare interface ReportCellContext {
+    address: ReportCellAddress_2;
+    cell: Readonly<GridCell_2>;
+    component: Readonly<PlanComponent_2>;
+    value: ReportCellValue_2;
+    valueType: ReportCellValueType;
+    table?: ReportCellTableIdentity_2;
+    /** Stable business identity. Physical row indices must never be used as database keys. */
+    source?: Readonly<ReportCellSource_2>;
+    editable: boolean;
+    readOnlyReason?: ReportCellReadOnlyReason;
+}
+declare interface ReportCellEdit {
+    address: ReportCellAddress;
+    table?: ReportCellTableIdentity;
+    source?: Readonly<ReportCellSource>;
+    previousValue: ReportCellValue;
+    previousText: string;
+    value: ReportCellValue;
+    text: string;
+}
+declare interface ReportCellEdit_2 {
+    address: ReportCellAddress_2;
+    table?: ReportCellTableIdentity_2;
+    source?: Readonly<ReportCellSource_2>;
+    previousValue: ReportCellValue_2;
+    previousText: string;
+    value: ReportCellValue_2;
+    text: string;
+}
+declare interface ReportCellFieldBase {
+    /** Presentation only; it never grants write permission. */
+    label?: string;
+    hint?: string;
+    unit?: string;
+    required?: boolean;
+}
+declare type ReportCellFieldOptions = ReportCellFieldBase & ({
+    type: "text";
+    maxLength?: number;
+} | {
+    type: "number";
+    min?: number;
+    max?: number;
+    precision?: number;
+} | {
+    type: "boolean";
+    trueLabel?: string;
+    falseLabel?: string;
+} | {
+    type: "enum";
+    options: readonly ReportCellChoice[];
+} | {
+    type: "date";
+    min?: string;
+    max?: string;
+});
+declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
+declare interface ReportCellSelection {
+    anchor: ReportCellAddress;
+    focus: ReportCellAddress;
+}
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource_2 {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource_3 {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+declare interface ReportCellTableIdentity {
+    id: string;
+    /** 逻辑表行索引；跨分页的同一行保持不变。 */
+    rowIndex: number;
+    role: PlanTableFragment["role"];
+    columnKey?: string;
+}
+declare interface ReportCellTableIdentity_2 {
+    id: string;
+    /** 逻辑表行索引；跨分页的同一行保持不变。 */
+    rowIndex: number;
+    role: PlanTableFragment_2["role"];
+    columnKey?: string;
+}
+declare type ReportCellValue = string | number | boolean | null;
+declare type ReportCellValue_2 = string | number | boolean | null;
+declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
+declare interface ReportDefinition {
+    /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
+    template: ReportTemplate | ReportTemplateLoader;
+    /** 静态数据；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 type ReportDiscardReason = "reload" | "import" | "replace" | "leave";
+declare interface ReportEditBatch {
+    /** Idempotency identity; the server should bind it to the exact payload. */
+    requestId: string;
+    edits: ReportCellEdit_2[];
+}
+declare interface ReportEditConflict {
+    source?: Readonly<ReportCellSource_2>;
+    address?: ReportCellAddress_2;
+    message: string;
+    currentValue?: ReportCellValue_2;
+    revision?: string | number;
+}
+/** Opt in with true for local drafts, or provide host validation and persistence. */
+declare interface ReportEditingOptions {
+    /** Optional field controls, keyed by source.field / table.columnKey; a resolver supports dataset-specific rules. */
+    fields?: Readonly<Record<string, ReportCellFieldOptions>> | ((context: ReportCellContext) => ReportCellFieldOptions | undefined);
+    canEdit?(context: ReportCellContext): boolean;
+    /** Return an error message or throw to reject the edit. */
+    validate?(edit: Readonly<ReportCellEdit_2>, operation: ReportEditOperation): void | string | Promise<void | string>;
+    /** Called before applying the change. A rejection leaves the current report untouched. */
+    save?(edit: Readonly<ReportCellEdit_2>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
+    /** Must commit all edits in one server transaction. Required for multi-cell persisted edits. */
+    saveBatch?(batch: Readonly<ReportEditBatch>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
+    /** Restrict persistence to plans that supply stable datasetId/rowKey/field metadata. */
+    requireSource?: boolean;
+}
+declare interface ReportEditOperation {
+    /** Reload, another import or unmount aborts the operation. Save adapters should forward this signal. */
+    signal: AbortSignal;
+    requestId?: string;
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+declare interface ReportEditResult {
+    /** A successful result may advance concurrency tokens for the affected dataset. */
+    revision?: string | number;
+    sourceToken?: string;
+    /** Any conflict rejects the entire client batch. A server must also transact atomically. */
+    conflicts?: readonly ReportEditConflict[];
+}
+/** 报表含表头但业务行为空时，由接入方明确声明；组件不推测业务数据。 */
+declare interface ReportEmptyState {
+    title?: string;
+    description?: string;
+}
+/** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
+declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+/** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
+declare interface ReportFetcher {
+    (input: ReportFetchInput): Promise<RenderPlan>;
+    getParamDefs?: (reportIds: string[]) => ReportParamDef[];
+}
+declare interface ReportFetchInput extends ReportTaskMonitoring {
+    reportIds: string[];
+    params: Record<string, string>;
+    signal?: AbortSignal;
+    /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
+    onWarning?: (message: string) => void;
+    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
+}
+declare interface ReportFieldContract {
+    field: string;
+    label?: string;
+    type: "text" | "number" | "boolean" | "date" | "decimal";
+    required?: boolean;
+    nullable?: boolean;
+    enum?: readonly (string | number | boolean)[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    unit?: string;
+}
+declare interface ReportFieldTarget {
+    field: string;
+    datasetId?: string;
+    rowKey?: string | number;
+    tableId?: string;
+}
+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;
+    params: Record<string, string>;
+    signal?: AbortSignal;
+}
+declare interface ReportOutputOptions {
+    /** warn preserves supported output and shows diagnostics; strict rejects known fidelity loss. */
+    fidelity?: "warn" | "strict";
+}
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+declare interface ReportParamDef {
+    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
+    field: string;
+    /** 显示名（缺省用 field） */
+    label?: string;
+    type?: "text" | "number" | "date" | "select";
+    /** select 选项 */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    defaultValue?: string;
+    required?: boolean;
+    placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
+}
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+declare interface ReportParamDef_2 {
+    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
+    field: string;
+    /** 显示名（缺省用 field） */
+    label?: string;
+    type?: "text" | "number" | "date" | "select";
+    /** select 选项 */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    defaultValue?: string;
+    required?: boolean;
+    placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
+}
+declare interface ReportParamIssue {
+    code: ReportParamIssueCode;
+    path: string;
+    field: string;
+    message: string;
+}
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+declare interface ReportPreferencesAdapter {
+    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
+    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
+    remove?(key: string): void | Promise<void>;
+}
+declare interface ReportPreferencesOptions {
+    /** Host-scoped key; do not share one key between unrelated users/tenants. */
+    key: string;
+    adapter: ReportPreferencesAdapter;
+}
+declare interface ReportPreviewDiagnostic {
+    code: string;
+    severity: "warning" | "error" | "info";
+    message: string;
+    path?: string;
+    format?: OutputFormat;
+    pageIndex?: number;
+    componentIndex?: number;
+    componentPath?: readonly number[];
+}
+declare type ReportPreviewPreferences = Record<ReportPreviewTool, boolean>;
+declare interface ReportPreviewTask {
+    taskId: string;
+    kind: "query" | "import" | "export" | "print";
+    stage: ReportPreviewTaskStage;
+    status: "running" | "completed" | "cancelled" | "failed";
+    /** Counts refer to the current stage, not an invented overall percentage. */
+    completed?: number;
+    total?: number;
+    cancellable: boolean;
+}
+declare type ReportPreviewTaskStage = "query" | "validate" | "layout" | "assets" | "import" | "encode" | "download" | "print";
+declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
+/** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
+declare interface ReportProvider {
+    query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
+    save?(input: ReportSaveInput): ReportSaveResult | Promise<ReportSaveResult>;
+    export?(input: ReportProviderExportInput): ReportProviderExportResult | Promise<ReportProviderExportResult>;
+    templates?: ReportTemplateProvider;
+}
+declare interface ReportProviderExportInput extends ReportLoadContext {
+    format: "pdf" | "xlsx";
+}
+declare interface ReportProviderExportResult {
+    bytes: Uint8Array;
+    contentType: string;
+    fileName?: string;
+    diagnostics?: ReportDiagnostic[];
+}
+declare interface ReportQueryResult {
+    datasets: DatasetRows;
+    revision?: string;
+    sourceToken?: string;
+    diagnostics?: ReportDiagnostic[];
+}
+declare type ReportRegistry = Record<string, ReportDefinition>;
+declare interface ReportSaveInput extends ReportLoadContext {
+    requestId: string;
+    expectedRevision?: string;
+    sourceToken?: string;
+    edits: readonly ReportCellEdit[];
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+declare interface ReportSaveResult {
+    revision: string;
+    sourceToken?: string;
+    conflicts?: Array<{
+        editIndex: number;
+        code: string;
+        message: string;
+    }>;
+    diagnostics?: ReportDiagnostic[];
+}
+/** 阶段事件只包含可序列化值；不表示估算百分比，也不包含业务数据。 */
+declare interface ReportTaskEvent {
+    taskId: string;
+    correlationId?: string;
+    stage: "query" | "validate" | "layout" | "encode";
+    status: "started" | "completed" | "failed";
+    reportId?: string;
+    completed?: number;
+    total?: number;
+}
+declare interface ReportTaskMonitoring {
+    taskId?: string;
+    correlationId?: string;
+    onEvent?: ReportTaskObserver;
+}
+declare type ReportTaskObserver = (event: ReportTaskEvent) => void;
+declare interface ReportTemplate {
+    schemaVersion?: string;
+    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
+    params?: ReportParamDef[];
+    pages: TemplatePage[];
+}
+declare interface ReportTemplate_2 {
+    schemaVersion?: string;
+    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
+    params?: ReportParamDef_2[];
+    pages: TemplatePage_2[];
+}
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+declare interface ReportTemplateDocument {
+    schemaVersion: "1.0";
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate;
+}
+declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
+declare interface ReportTemplateProvider {
+    list(context: {
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateSummary[]>;
+    get(id: string, context: {
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateDocument | undefined>;
+}
+declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+declare interface RichParagraph_2 {
+    segments: RichSegment_2[];
+    align?: ComponentStyle_2["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+declare interface RichParagraph_3 {
+    segments: RichSegment_3[];
+    align?: ComponentStyle_3["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+declare interface RichSegment_2 {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle_2;
+}
+declare interface RichSegment_3 {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle_3;
+}
+/** 条件格式规则求值（声明式，见 ListColumn.rules） */
+declare interface StyleRule {
+    when: {
+        field: string;
+        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
+        value: number | string;
+    };
+    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
+    style: Record<string, unknown>;
+}
+/** 条件格式规则求值（声明式，见 ListColumn.rules） */
+declare interface StyleRule_2 {
+    when: {
+        field: string;
+        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
+        value: number | string;
+    };
+    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
+    style: Record<string, unknown>;
+}
+declare type TemplateComponent = PlanComponent | ListComponent;
+declare type TemplateComponent_2 = PlanComponent_3 | ListComponent_2;
+declare interface TemplatePage {
+    widthMm: number;
+    heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: TemplateComponent[];
+}
+declare interface TemplatePage_2 {
+    widthMm: number;
+    heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: TemplateComponent_2[];
+}
+/**
+ * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
+ *
+ * 测量模型可注入（TextMeasurer）：
+ * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
+ * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
+ */
+declare interface TextMeasureOptions {
+    fontSizePt: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    letterSpacingPt?: number;
+}
+/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
+declare interface TextMeasurer {
+    measureMm(text: string, options: TextMeasureOptions): number;
+}
+/**
+ * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
+ * - 网格组件 → 真表格：列宽（mm→Excel 宽度）、行高（mm→pt）、colSpan/rowSpan 合并、
+ *   加粗/对齐/底色/字号直译（resolveGridLayout 复用单真相源几何）
+ * - 文本组件 → 合并标题行（顺序流式输出，保字号/加粗/对齐；非像素级定位，
+ *   目标是"财务能直接用的对账表"而非复刻版面）
+ * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
+ */
+declare interface XlsxRenderOptions extends OutputDiagnosticOptions_2 {
+    /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
+    sheetName?: (sheetIndex: number) => string;
+    /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
+    sheetMode?: "auto" | "pages" | "continuous";
+    /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
+    valueMode?: "text" | "raw";
+    /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
+    paperSize?: "auto" | "a3" | "a4" | "a5";
+}
+export {};