@agile-team/mach-report 2.16.0 → 2.18.0

package/dist/vue/async.d.cts

@@ -17,8 +17,39 @@ declare interface AggregateDefinition_2 {
     numeric?: "number" | "decimal";
     digits?: number;
 }
+declare interface AggregateDefinition_3 {
+    /** Output column; valueField defaults to this field. */
+    field: string;
+    op: AggregateOperation_3;
+    valueField?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
 declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 declare type AggregateOperation_2 = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+declare type AggregateOperation_3 = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+declare interface AggregateRequest {
+    op: AggregateOperation;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+declare interface AggregateRequest_2 {
+    op: AggregateOperation_2;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+declare interface AggregateRequest_3 {
+    op: AggregateOperation_3;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
 declare interface AssetRenderBudget {
     /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
     maxAssets?: number;
@@ -29,13 +60,34 @@ declare interface AssetRenderBudget {
     /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
     maxDurationMs?: number;
 }
+declare interface AssetRenderBudget_2 {
+    /** 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, ImageMediaOptions {
     assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    /** Explicit id/version registry; unbound components continue using assetRenderers by kind. */
+    assetRegistry?: ComponentAssetRegistry;
     assetBudget?: AssetRenderBudget;
     /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
     assetFailure?: "throw" | "placeholder";
     signal?: AbortSignal;
 }
+declare interface AssetRenderOptions_2 extends OutputDiagnosticOptions_2, ImageMediaOptions_2 {
+    assetRenderers?: Partial<Record<ImageComponentKind_2, ComponentImageRenderer_2>>;
+    /** Explicit id/version registry; unbound components continue using assetRenderers by kind. */
+    assetRegistry?: ComponentAssetRegistry_2;
+    assetBudget?: AssetRenderBudget_2;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
 declare interface BrowserReportWorker {
     postMessage(value: unknown, transfer?: Transferable[]): void;
     terminate(): void;
@@ -143,6 +195,46 @@ declare type ColumnFormat_3 = {
     kind: "date";
     pattern?: string;
 };
+declare type ColumnVisual = {
+    /** Defaults to the column field; never changes the cell's raw value or business identity. */
+    field?: string;
+    /** Numeric text requires explicit opt-in; formatting an identifier does not turn it into a measure. */
+    numeric?: "number" | "decimal";
+    min?: number;
+    max?: number;
+} & ({
+    kind: "colorScale";
+    lowColor?: string;
+    highColor?: string;
+} | {
+    kind: "dataBar";
+    color?: string;
+    negativeColor?: string;
+});
+declare type ColumnVisual_2 = {
+    /** Defaults to the column field; never changes the cell's raw value or business identity. */
+    field?: string;
+    /** Numeric text requires explicit opt-in; formatting an identifier does not turn it into a measure. */
+    numeric?: "number" | "decimal";
+    min?: number;
+    max?: number;
+} & ({
+    kind: "colorScale";
+    lowColor?: string;
+    highColor?: string;
+} | {
+    kind: "dataBar";
+    color?: string;
+    negativeColor?: string;
+});
+declare interface ComponentAssetRegistry {
+    rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
+declare interface ComponentAssetRegistry_2 {
+    rendererFor(component: Readonly<PlanComponent_2>): ComponentImageRenderer_2 | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 declare interface ComponentBinding {
     field: string;
@@ -174,7 +266,15 @@ declare interface ComponentImageContext {
     readonly componentPath: readonly number[];
     readonly signal: AbortSignal;
 }
+declare interface ComponentImageContext_2 {
+    readonly component: Readonly<PlanComponent_2>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
 declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+declare type ComponentImageRenderer_2 = (context: ComponentImageContext_2) => 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";
@@ -265,6 +365,15 @@ declare interface ComputedField_2 extends ExpressionOptions_2 {
     /** String adapter expressions cannot be inspected; declare dependencies explicitly. */
     dependsOn?: readonly string[];
 }
+declare interface ComputedField_3 extends ExpressionOptions_3 {
+    field: string;
+    expression: ReportExpression_3 | string;
+    /** Scope controls aggregate inputs; row expressions may reference the current row in any scope. */
+    scope?: "row" | "group" | "dataset";
+    groupBy?: readonly string[];
+    /** String adapter expressions cannot be inspected; declare dependencies explicitly. */
+    dependsOn?: readonly string[];
+}
 declare interface DatasetContract {
     fields: readonly ReportFieldContract[];
     rowKey?: string;
@@ -362,6 +471,12 @@ declare interface ExpressionOptions_2 {
     nulls?: "propagate" | "error";
     divisionByZero?: "null" | "error";
 }
+declare interface ExpressionOptions_3 {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
 declare interface FormulaAdapter {
     /** Explicit trusted engine; core never evaluates source code/macros/external workbook references. */
     evaluate(expression: string, context: {
@@ -370,7 +485,21 @@ declare interface FormulaAdapter {
         rows: readonly Record<string, unknown>[];
     }): unknown;
 }
+declare interface FormulaAdapter_2 {
+    /** Explicit trusted engine; core never evaluates source code/macros/external workbook references. */
+    evaluate(expression: string, context: {
+        row: Readonly<Record<string, unknown>>;
+        rowIndex: number;
+        rows: readonly Record<string, unknown>[];
+    }): unknown;
+}
 declare interface GridCell {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph[];
     text?: string;
@@ -396,6 +525,12 @@ declare interface GridCell {
     style?: ComponentStyle;
 }
 declare interface GridCell_2 {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph_2[];
     text?: string;
@@ -421,6 +556,12 @@ declare interface GridCell_2 {
     style?: ComponentStyle_2;
 }
 declare interface GridCell_3 {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph_3[];
     text?: string;
@@ -446,6 +587,7 @@ declare interface GridCell_3 {
     style?: ComponentStyle_3;
 }
 declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+declare type ImageComponentKind_2 = "image" | "chart" | "barcode" | "qrcode";
 /** Bounded binary image inspection shared by PDF, Excel and template import. No decoder is loaded. */
 declare interface ImageMediaOptions {
     maxImageBytes?: number;
@@ -489,6 +631,8 @@ declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -514,6 +658,8 @@ declare interface ListColumn_2 {
     format?: ColumnFormat_3;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule_2[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual_2;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -616,11 +762,11 @@ declare interface ListComponent_2 {
     groupBy?: ListGroupBy_2;
     /** Ordered outer-to-inner grouping; groupBy remains the single-level shorthand. */
     groups?: ListGroupBy_2[];
-    computed?: ComputedField_2[];
+    computed?: ComputedField_3[];
     /** Dynamic pivot of the current source dataset, with read-only derived identities. */
     matrix?: MatrixTableOptions_2;
     /** Full ordered hierarchy; source parent values and descendant-leaf rollups are explicit. */
-    tree?: TreeTableOptions_2;
+    tree?: TreeTableOptions_3;
     /** Explicit row visibility; hidden rows do not participate in summaries. */
     rowVisibleWhen?: StyleRule_2["when"];
     /** Master/detail relation is keyed by business identity, never by display row index. */
@@ -670,7 +816,7 @@ declare type ListGrandTotal_2 = boolean | {
     style?: ComponentStyle_3;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
-    aggregates?: AggregateDefinition_2[];
+    aggregates?: AggregateDefinition_3[];
 };
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
 declare interface ListGroupBy {
@@ -702,7 +848,7 @@ declare interface ListGroupBy_2 {
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
-    aggregates?: AggregateDefinition_2[];
+    aggregates?: AggregateDefinition_3[];
     /** Repeat this group heading after page breaks within the group. */
     repeatHeader?: boolean;
 }
@@ -753,6 +899,10 @@ declare interface MachReportDefaults {
     xlsx?: XlsxRenderOptions;
     /** 默认关闭；true 为本地草稿，对象可提供权限、校验和保存回调。 */
     editable?: boolean | ReportEditingOptions;
+    /** Optional reference-data loader; review and atomic editing are maintained inside the package. */
+    prefill?: ReportPrefillReviewOptions | false;
+    /** Compare a reference with the same query result rendered in the report. */
+    dataComparison?: ReportDataComparisonReviewOptions | false;
     /** 默认关闭；启用后提供导入按钮。ExcelJS 仅在导入时加载。 */
     excelImport?: boolean | ExcelImportOptions;
 }
@@ -770,7 +920,14 @@ declare type MachReportLogger = Pick<Console, "warn" | "info">;
  * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-declare interface MachReportMessages extends Partial<ReportCalculationMessages>, ReportPrintMessages, ReportParamOptionsMessages {
+declare interface MachReportMessages extends Partial<ReportCalculationMessages>, Partial<ReportDataReviewMessages>, ReportPrintMessages, ReportParamOptionsMessages {
+    reviewTools?: string;
+    validationTitle?: string;
+    validationError?: string;
+    validationWarning?: string;
+    validationDataset?: string;
+    validationRow?: string;
+    validationMore?: string;
     drillActions?: string;
     drillOpening?: string;
     drillMissingValue?: string;
@@ -1028,6 +1185,40 @@ declare interface MachReportToolbarOptions {
     /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
     exportFormats?: ReportExportFormat[];
 }
+declare interface MatrixAxisOptions {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+declare interface MatrixAxisOptions_2 {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder_2[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+declare type MatrixDimensionOrder = "source" | "asc" | "desc";
+declare type MatrixDimensionOrder_2 = "source" | "asc" | "desc";
+declare interface MatrixHierarchyOptions {
+    row?: MatrixAxisOptions;
+    column?: MatrixAxisOptions;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+declare interface MatrixHierarchyOptions_2 {
+    row?: MatrixAxisOptions_2;
+    column?: MatrixAxisOptions_2;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
 declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -1042,11 +1233,15 @@ declare interface MatrixTableOptions {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 declare interface MatrixTableOptions_2 {
     rowFields: readonly string[];
     columnFields: readonly string[];
-    measures: readonly (AggregateDefinition_2 & {
+    measures: readonly (AggregateDefinition_3 & {
         label?: string;
     })[];
     totals?: boolean;
@@ -1057,6 +1252,10 @@ declare interface MatrixTableOptions_2 {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions_2;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 declare interface OutputDiagnostic {
     code: "invalid-image-data" | "image-budget-exceeded" | "component-render-failed" | "unsupported-text" | "output-degraded" | "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";
@@ -1068,6 +1267,11 @@ declare interface OutputDiagnostic {
     componentPath?: readonly number[];
     kind: string;
     nid?: string;
+    /** Declarative extension identity only; no property values or business binding data enter diagnostics. */
+    extension?: {
+        id: string;
+        version: string;
+    };
     message: string;
 }
 declare interface OutputDiagnostic_2 {
@@ -1080,6 +1284,11 @@ declare interface OutputDiagnostic_2 {
     componentPath?: readonly number[];
     kind: string;
     nid?: string;
+    /** Declarative extension identity only; no property values or business binding data enter diagnostics. */
+    extension?: {
+        id: string;
+        version: string;
+    };
     message: string;
 }
 declare interface OutputDiagnosticOptions extends OutputTaskOptions {
@@ -1120,6 +1329,8 @@ declare interface PaginateOptions {
     maxPages?: number;
     /** Actual grid cells, including repeated furniture and nested children; checked before each page is appended. */
     maxCells?: number;
+    /** Shared bound-chart primitive budget, checked before expansion; default 50000, range 1..1000000. */
+    maxChartComponents?: number;
     signal?: AbortSignal;
     /** Streaming total-page anchors can skip the bounded counting pass when known. */
     knownTotalPages?: number;
@@ -1146,6 +1357,8 @@ declare interface PdfFontCheckResult {
 /** available 仅表示字体资源可达；实际导出仍会校验文字能否编码。 */
 declare type PdfFontStatus = "unchecked" | "checking" | "available" | "disabled" | "unverified" | "error";
 declare interface PlanComponent {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding;
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions;
     /** Template-only binding; resolved and removed before constructing the output plan. */
@@ -1174,6 +1387,8 @@ declare interface PlanComponent {
     fallbackText?: string;
 }
 declare interface PlanComponent_2 {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding_2;
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions_2;
     /** Template-only binding; resolved and removed before constructing the output plan. */
@@ -1202,6 +1417,8 @@ declare interface PlanComponent_2 {
     fallbackText?: string;
 }
 declare interface PlanComponent_3 {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding_3;
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions_3;
     /** Template-only binding; resolved and removed before constructing the output plan. */
@@ -1272,6 +1489,18 @@ declare interface PlanPage {
     marginRightMm?: number;
     components: PlanComponent[];
 }
+declare interface PlanPage_2 {
+    meta?: Record<string, unknown>;
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
+    pageWidthMm: number;
+    pageHeightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: PlanComponent_2[];
+}
 /** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
 declare interface PlanTableFragment {
     /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
@@ -1328,6 +1557,12 @@ declare interface RenderPlan {
     requiresRecalculation?: boolean;
     pages: PlanPage[];
 }
+declare interface RenderPlan_2 {
+    schemaVersion: string;
+    /** 编辑需要模板重算上下文；跨 Worker/JSON 保留要求，但不声明本地会话可用。 */
+    requiresRecalculation?: boolean;
+    pages: PlanPage_2[];
+}
 /** 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 {
@@ -1365,6 +1600,10 @@ declare interface ReportCalculationMessages {
     calculationErrorOverflow: string;
     calculationErrorPrecision: string;
 }
+declare interface ReportCandidateValidationOptions extends Pick<ReportDatasetValidationOptions, "rules" | "maxChecks" | "maxIssues"> {
+    /** Warnings are visible and allowed by default; block explicitly when required by business policy. */
+    warningPolicy?: "allow" | "block";
+}
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 declare interface ReportCellAddress {
     pageIndex: number;
@@ -1492,6 +1731,229 @@ declare interface ReportCellTableIdentity_2 {
 declare type ReportCellValue = string | number | boolean | null;
 declare type ReportCellValue_2 = string | number | boolean | null;
 declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+declare interface ReportChartBinding_2 {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure_2[];
+    type: ReportChartOptions_2["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+declare interface ReportChartBinding_3 {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure_3[];
+    type: ReportChartOptions_3["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+declare interface ReportChartMeasure_2 extends AggregateRequest_2 {
+    label?: string;
+    color?: string;
+}
+declare interface ReportChartMeasure_3 extends AggregateRequest_3 {
+    label?: string;
+    color?: string;
+}
+declare interface ReportChartOptions {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+declare interface ReportChartOptions_2 {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries_2[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+declare interface ReportChartOptions_3 {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries_3[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+declare interface ReportChartSeries {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+declare interface ReportChartSeries_2 {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+declare interface ReportChartSeries_3 {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+declare interface ReportComparison {
+    field: string;
+    op: ">" | ">=" | "<" | "<=" | "==" | "!=" | "between" | "contains" | "isNull" | "isNotNull";
+    /** Legacy scalar thresholds remain supported. Use right for field-to-field comparisons. */
+    value?: ReportPredicateScalar;
+    right?: ReportPredicateOperand;
+    values?: readonly [
+        ReportPredicateScalar,
+        ReportPredicateScalar
+    ];
+    numeric?: "number" | "decimal";
+    valueType?: "number" | "decimal" | "text" | "date" | "boolean";
+}
+declare interface ReportComparison_2 {
+    field: string;
+    op: ">" | ">=" | "<" | "<=" | "==" | "!=" | "between" | "contains" | "isNull" | "isNotNull";
+    /** Legacy scalar thresholds remain supported. Use right for field-to-field comparisons. */
+    value?: ReportPredicateScalar_2;
+    right?: ReportPredicateOperand_2;
+    values?: readonly [
+        ReportPredicateScalar_2,
+        ReportPredicateScalar_2
+    ];
+    numeric?: "number" | "decimal";
+    valueType?: "number" | "decimal" | "text" | "date" | "boolean";
+}
+declare interface ReportComparison_3 {
+    field: string;
+    op: ">" | ">=" | "<" | "<=" | "==" | "!=" | "between" | "contains" | "isNull" | "isNotNull";
+    /** Legacy scalar thresholds remain supported. Use right for field-to-field comparisons. */
+    value?: ReportPredicateScalar_3;
+    right?: ReportPredicateOperand_3;
+    values?: readonly [
+        ReportPredicateScalar_3,
+        ReportPredicateScalar_3
+    ];
+    numeric?: "number" | "decimal";
+    valueType?: "number" | "decimal" | "text" | "date" | "boolean";
+}
+declare interface ReportDataComparisonField {
+    field: string;
+    label?: string;
+    /** Numeric comparison is explicit; identifiers containing digits stay text. */
+    type?: "value" | "decimal";
+    /** Absolute decimal tolerance, inclusive. No binary floating-point subtraction. */
+    tolerance?: string;
+    /** Fractional ratio digits. changeRatio is (after - before) / before, not a percent. */
+    ratioDigits?: number;
+    zeroDenominator?: "omit" | "zero-if-equal";
+    missing?: "distinct" | "empty-equivalent" | "zero";
+}
+declare interface ReportDataComparisonReviewOptions extends ReportDataReviewSource {
+    fields: readonly ReportDataComparisonField[];
+    maxDifferences?: number;
+}
+declare interface ReportDataLimits {
+    maxRows?: number;
+    maxFields?: number;
+    maxCells?: number;
+}
+/** A business record, never a physical report row index. */
+declare interface ReportDataRecord {
+    rowKey: string | number;
+    values: Readonly<Record<string, ReportCellValue_2>>;
+}
+declare interface ReportDataReviewMessages {
+    prefillTitle: string;
+    prefillHint: string;
+    prefillCurrent: string;
+    prefillReference: string;
+    prefillLoad: string;
+    prefillApply: string;
+    prefillMatched: string;
+    prefillChanged: string;
+    prefillSkipped: string;
+    prefillConflict: string;
+    prefillUnchanged: string;
+    prefillReadonly: string;
+    prefillOccupied: string;
+    prefillMissingSource: string;
+    prefillMissingTarget: string;
+    prefillAmbiguous: string;
+    prefillInvalid: string;
+    comparisonTitle: string;
+    comparisonHint: string;
+    comparisonLoad: string;
+    comparisonAdded: string;
+    comparisonRemoved: string;
+    comparisonChanged: string;
+    comparisonUnchanged: string;
+    reviewCancel: string;
+    reviewClose: string;
+    reviewBefore: string;
+    reviewAfter: string;
+    reviewField: string;
+    reviewKey: string;
+    reviewDelta: string;
+    reviewRatio: string;
+    reviewLocate: string;
+    reviewEmpty: string;
+    reviewPrevious: string;
+    reviewNext: string;
+    reviewPage: string;
+}
+declare interface ReportDataReviewSource extends ReportDataLimits {
+    sourceScope?: string;
+    datasetId: string;
+    label?: string;
+    /** The host chooses history/instances; this package never guesses an endpoint or period. */
+    load(operation: {
+        signal: AbortSignal;
+    }): readonly ReportDataRecord[] | Promise<readonly ReportDataRecord[]>;
+    /** Cancel loaders that do not finish; default 15 seconds, bounded at 120 seconds. */
+    timeoutMs?: number;
+}
+declare interface ReportDatasetValidationOptions {
+    rules: readonly ReportValidationRule[];
+    rowKey?: string;
+    computed?: readonly ComputedField_2[];
+    /** Explicit trusted engine, shared with pagination; never read from a serialized template. */
+    formula?: FormulaAdapter_2;
+    /** Uses the same bounded tree preparation and descendant-leaf summaries as pagination. */
+    tree?: TreeTableOptions_2;
+    maxChecks?: number;
+    maxIssues?: number;
+    signal?: AbortSignal;
+}
 declare interface ReportDataTarget {
     datasetId: string;
     field: string;
@@ -1599,6 +2061,10 @@ 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>;
+    /** Same declarative rules can be run in Node via validateReportDataset. Requires a source-backed session. */
+    validation?: ReportCandidateValidationOptions;
+    /** Optional host batch validation sees the fully recalculated candidate plan. */
+    validateBatch?(batch: Readonly<ReportEditBatch>, candidate: RenderPlan_2, operation: ReportEditOperation): void | readonly ReportValidationIssue[] | Promise<void | readonly ReportValidationIssue[]>;
     /** 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. */
@@ -1663,7 +2129,9 @@ declare type ReportExpression = {
     field?: string;
     weightField?: string;
 } | {
-    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    op: ReportExpressionOperation;
+    /** Required for if; args are [then, else], and only the selected branch is evaluated. */
+    condition?: ReportPredicate;
     args: readonly ReportExpression[];
 };
 declare type ReportExpression_2 = {
@@ -1675,9 +2143,28 @@ declare type ReportExpression_2 = {
     field?: string;
     weightField?: string;
 } | {
-    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    op: ReportExpressionOperation_2;
+    /** Required for if; args are [then, else], and only the selected branch is evaluated. */
+    condition?: ReportPredicate_2;
     args: readonly ReportExpression_2[];
 };
+declare type ReportExpression_3 = {
+    field: string;
+} | {
+    value: string | number | boolean | null;
+} | {
+    aggregate: AggregateOperation_3;
+    field?: string;
+    weightField?: string;
+} | {
+    op: ReportExpressionOperation_3;
+    /** Required for if; args are [then, else], and only the selected branch is evaluated. */
+    condition?: ReportPredicate_3;
+    args: readonly ReportExpression_3[];
+};
+declare type ReportExpressionOperation = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
+declare type ReportExpressionOperation_2 = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
+declare type ReportExpressionOperation_3 = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -1692,7 +2179,13 @@ declare interface ReportFetchInput extends ReportTaskMonitoring {
     /** Index scopes diagnostics when reports share datasets or a report ID is repeated. */
     onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
-declare interface ReportFieldContract {
+declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+declare interface ReportFieldCalculation {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
     type: "text" | "number" | "boolean" | "date" | "decimal";
@@ -1706,6 +2199,16 @@ declare interface ReportFieldContract {
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
     unit?: string;
 }
+declare interface ReportFieldSemantics {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat;
+    calculation?: ReportFieldCalculation;
+}
 declare interface ReportFieldTarget {
     field: string;
     datasetId?: string;
@@ -1759,12 +2262,9 @@ declare interface ReportParamDef {
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select" | "multiSelect" | "cascader" | "numberRange";
     /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ReportParamTreeOption[];
     /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
     optionsSource?: string;
     /** Select dependencies must be declared parameters; changing a parent clears descendants. */
@@ -1777,6 +2277,9 @@ declare interface ReportParamDef {
     max?: number | string;
     minLength?: number;
     maxLength?: number;
+    /** multiSelect item count (maximum 100). Cascader paths are bounded to 16 levels. */
+    minItems?: number;
+    maxItems?: number;
 }
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef_2 {
@@ -1784,12 +2287,9 @@ declare interface ReportParamDef_2 {
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select" | "multiSelect" | "cascader" | "numberRange";
     /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ReportParamTreeOption_2[];
     /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
     optionsSource?: string;
     /** Select dependencies must be declared parameters; changing a parent clears descendants. */
@@ -1802,6 +2302,9 @@ declare interface ReportParamDef_2 {
     max?: number | string;
     minLength?: number;
     maxLength?: number;
+    /** multiSelect item count (maximum 100). Cascader paths are bounded to 16 levels. */
+    minItems?: number;
+    maxItems?: number;
 }
 declare interface ReportParamIssue {
     code: ReportParamIssueCode;
@@ -1809,10 +2312,11 @@ declare interface ReportParamIssue {
     field: string;
     message: string;
 }
-declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength" | "minItems" | "maxItems";
 declare interface ReportParamOption {
     readonly label: string;
     readonly value: string;
+    readonly children?: readonly ReportParamOption[];
 }
 declare interface ReportParamOptionsInput {
     readonly source: string;
@@ -1832,6 +2336,20 @@ declare interface ReportParamOptionsMessages {
     paramOptionsMissingLoader?: string;
     paramOptionsDependencies?: string;
     paramOptionsClear?: string;
+    paramNumberRangeStart?: string;
+    paramNumberRangeEnd?: string;
+}
+/** Cascader values are unique within each sibling list. */
+declare interface ReportParamTreeOption {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption[];
+}
+/** Cascader values are unique within each sibling list. */
+declare interface ReportParamTreeOption_2 {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption_2[];
 }
 /** Licensed local font bytes; never downloaded implicitly by the runtime. */
 declare interface ReportPdfFontOptions {
@@ -1844,6 +2362,45 @@ declare interface ReportPdfFontOptions {
         boldItalic?: Uint8Array | ArrayBuffer;
     };
 }
+declare type ReportPredicate = ReportComparison | {
+    all: readonly ReportPredicate[];
+} | {
+    any: readonly ReportPredicate[];
+} | {
+    not: ReportPredicate;
+};
+declare type ReportPredicate_2 = ReportComparison_2 | {
+    all: readonly ReportPredicate_2[];
+} | {
+    any: readonly ReportPredicate_2[];
+} | {
+    not: ReportPredicate_2;
+};
+declare type ReportPredicate_3 = ReportComparison_3 | {
+    all: readonly ReportPredicate_3[];
+} | {
+    any: readonly ReportPredicate_3[];
+} | {
+    not: ReportPredicate_3;
+};
+declare type ReportPredicateOperand = {
+    field: string;
+} | {
+    value: ReportPredicateScalar;
+};
+declare type ReportPredicateOperand_2 = {
+    field: string;
+} | {
+    value: ReportPredicateScalar_2;
+};
+declare type ReportPredicateOperand_3 = {
+    field: string;
+} | {
+    value: ReportPredicateScalar_3;
+};
+declare type ReportPredicateScalar = string | number | boolean | null;
+declare type ReportPredicateScalar_2 = string | number | boolean | null;
+declare type ReportPredicateScalar_3 = string | number | boolean | null;
 declare interface ReportPreferencesAdapter {
     load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
     save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
@@ -1854,6 +2411,16 @@ declare interface ReportPreferencesOptions {
     key: string;
     adapter: ReportPreferencesAdapter;
 }
+declare interface ReportPrefillField {
+    field: string;
+    sourceField?: string;
+    label?: string;
+}
+declare interface ReportPrefillReviewOptions extends ReportDataReviewSource {
+    fields: readonly ReportPrefillField[];
+    mode?: "empty" | "replace";
+    maxChanges?: number;
+}
 declare interface ReportPreviewDataTarget extends ReportDataTarget_2 {
     /** Added by the query adapter; isolates identical dataset/row/field identities across reports. */
     reportScope?: string;
@@ -1939,6 +2506,8 @@ declare interface ReportRuntimeBudget {
     maxRows?: number;
     maxPages?: number;
     maxCells?: number;
+    /** Aggregate bound-chart primitives per prepare, before expansion; default 50000, hard maximum 1000000. */
+    maxChartComponents?: number;
     maxOutputBytes?: number;
     /** Bound the plain JSON snapshot accepted by exportPrepared (default 64 MB). */
     maxPreparedBytes?: number;
@@ -2031,6 +2600,29 @@ declare interface ReportTemplateRepeat_2 {
     };
 }
 declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+declare interface ReportValidationIssue {
+    ruleId: string;
+    rowKey?: string | number;
+    rowIndex?: number;
+    field?: string;
+    dataset?: string;
+    sourceScope?: string;
+    severity: "error" | "warning";
+    message: string;
+}
+declare interface ReportValidationRule {
+    id: string;
+    /** Optional target; omitted applies to each candidate dataset. */
+    dataset?: string;
+    assert: ReportPredicate_2;
+    when?: ReportPredicate_2;
+    field?: string;
+    severity?: "error" | "warning";
+    message: string;
+    scope?: "row" | "dataset";
+    /** Dataset-scope assertions read this explicit summary row, never an arbitrary detail row. */
+    aggregates?: readonly AggregateDefinition_2[];
+}
 /** Optional business explanations never replace raw data or schema validation. */
 declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
 /** Optional business explanations never replace raw data or schema validation. */
@@ -2079,25 +2671,13 @@ declare interface RichSegment_3 {
 }
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-        /** Explicit decimal comparisons retain decimal thresholds as text. */
-        numeric?: "number" | "decimal";
-    };
+    when: ReportPredicate;
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
 }
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule_2 {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-        /** Explicit decimal comparisons retain decimal thresholds as text. */
-        numeric?: "number" | "decimal";
-    };
+    when: ReportPredicate_3;
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
 }
@@ -2187,6 +2767,25 @@ declare interface TreeTableOptions_2 {
     /** Bounded leaf-to-ancestor aggregate work; default one million. */
     maxAggregationVisits?: number;
 }
+/** A serialized tree contract. Sibling and root order follow input order. */
+declare interface TreeTableOptions_3 {
+    input: "flat" | "nested";
+    idField: string;
+    /** Flat roots have null/undefined parent values. */
+    parentField?: string;
+    /** Nested child arrays, defaults to children. Every node still needs an ID. */
+    childrenField?: string;
+    labelField: string;
+    indentMm?: number;
+    orphan?: "error" | "root";
+    /** Source preserves parent values; leaf-aggregate derives only parents from descendant leaves. */
+    parentValues?: "source" | "leaf-aggregate";
+    aggregates?: AggregateDefinition_3[];
+    maxRows?: number;
+    maxDepth?: number;
+    /** Bounded leaf-to-ancestor aggregate work; default one million. */
+    maxAggregationVisits?: number;
+}
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;
 /** The same declarative formatting used by list columns, before any output backend. */
@@ -2202,13 +2801,15 @@ declare type XlsxImageOptions = ImageMediaOptions_2;
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 原生 richText 保留基础字形；未支持组件、段落专有排版与单元格嵌套组件计入 diagnostics / warnings
  */
-declare interface XlsxRenderOptions extends OutputDiagnosticOptions_2, XlsxImageOptions {
+declare interface XlsxRenderOptions extends AssetRenderOptions_2, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
     valueMode?: "text" | "raw";
+    /** Static data-bar drawing budget; fail explicitly rather than omitting bars. Default 10,000. */
+    maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
 }