@agile-team/mach-report 2.15.0 → 2.17.0

package/dist/index.d.cts

@@ -42,6 +42,8 @@ export declare interface AssetRenderBudget {
 
 export 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";
@@ -162,6 +164,11 @@ export declare type ColumnFormat = {
 /** 同一字段契约生成列语义和表头，业务侧无需复制另一份字段清单。 */
 export declare function columnsFromContract(contract: DatasetContract, overrides?: Record<string, Partial<TableTemplateColumn>>): TableTemplateColumn[];
 
+export declare interface ComponentAssetRegistry {
+    rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
+
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 export declare interface ComponentBinding {
     field: string;
@@ -265,6 +272,16 @@ export declare function createLocalTemplateCatalog(input: LocalTemplateCatalogIt
 /** 单进程参考适配器；多实例服务请实现具备数据库事务/CAS 的持久化适配器。 */
 export declare function createMemoryTemplateStore(): ReportTemplateStore;
 
+/** Owned preview controller; only mounted grids are windowed. Static renderPage and exports stay complete. */
+export declare function createPageViewportRenderer(page: PlanPage, dpi: number, options: RenderOptions, doc: Document): {
+    element: HTMLElement;
+    update(viewport: ReportViewport, retained?: {
+        componentIndex: number;
+        rowIndex: number;
+        columnIndex: number;
+    }): boolean;
+};
+
 export declare function createProviderReport(definition: Omit<ReportDefinition, "load" | "datasets"> & {
     provider: ReportProvider;
 }): ReportDefinition;
@@ -278,6 +295,9 @@ export declare function createReportCellEditBatch(plan: RenderPlan, inputs: read
 /** Operation-scoped index: avoids repeated geometry work without caching mutable plans globally. */
 export declare function createReportCellResolver(plan: RenderPlan): (address: ReportCellAddress) => ReportCellContext | null;
 
+/** Explicit per-host registry. Templates contain bounded JSON bindings; loaders never come from a template. */
+export declare function createReportComponentRegistry(definitions: readonly ReportComponentExtensionDefinition[]): ReportComponentRegistry;
+
 /** Revalidates the current cell on activation; returns only bounded scalar values and explicit return state. */
 export declare function createReportDrillRequest(plan: RenderPlan, address: ReportCellAddress, action: ReportDrillAction, params?: Readonly<Record<string, string>>): ReportDrillRequest;
 
@@ -310,6 +330,8 @@ export declare function createTemplate(): TemplateBuilder;
 /** 持久化和框架无关的发布流程；历史返回快照，回滚会产生新修订而不会覆盖旧历史。 */
 export declare function createTemplateManager(store: ReportTemplateStore, options?: {
     migrate?: (input: unknown) => unknown | Promise<unknown>;
+    /** Explicit schema chain, applied to saved drafts and loaded/rolled-back documents. Legacy migrate remains save-only. */
+    migrations?: readonly ReportTemplateMigration[];
     now?: () => Date;
     /** Optional publication gate; receives explicit draft snapshots and never replaces CAS. */
     beforePublish?: (context: {
@@ -319,6 +341,9 @@ export declare function createTemplateManager(store: ReportTemplateStore, option
     }) => ReportTemplateReview | Promise<ReportTemplateReview>;
 }): ReportTemplateManager;
 
+/** Explicit, bounded migration chain. Unknown/future versions are never silently downgraded. */
+export declare function createTemplateMigrator(steps?: readonly ReportTemplateMigration[]): (input: unknown) => Promise<ReportTemplateMigrationResult>;
+
 /** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
 export declare function createTemplateRegistry(documents?: readonly ReportTemplateDocument[]): ReportTemplateRegistry;
 
@@ -409,6 +434,9 @@ export declare function evalStyleRule(row: Record<string, unknown>, when: StyleR
 /** A tiny arithmetic parser: no functions, property access, globals, assignments or executable source. */
 export declare function evaluateReportAggregateExpression(expression: string, values: Readonly<Record<string, number>>): number;
 
+/** Derives locatable explanations only from explicit business declarations; never evaluates formulas. */
+export declare function explainDatasetField(contract: DatasetContract, target: ReportDataTarget): ReportDiagnostic[];
+
 declare interface ExpressionOptions {
     numeric?: "number" | "decimal";
     digits?: number;
@@ -448,6 +476,8 @@ export declare function getReportCellContext(plan: RenderPlan, address: ReportCe
 export declare function getReportEditSession(plan: RenderPlan): ReportEditSession | undefined;
 
 export declare interface GridCell {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -777,6 +807,26 @@ export declare interface LocalTemplateCatalogItem {
 /** O(action count), no row scans or listeners per cell; invoke for the focused cell only. */
 export declare function matchReportDrillActions(plan: RenderPlan, address: ReportCellAddress, actions: readonly ReportDrillAction[]): ReportDrillAction[];
 
+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 type MatrixDimensionOrder = "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 MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -791,6 +841,10 @@ 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;
 }
 
 export declare function measurePageSizePx(page: Pick<PlanPage, "pageWidthMm" | "pageHeightMm">, dpi?: number): {
@@ -825,6 +879,11 @@ export 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;
 }
 
@@ -1223,6 +1282,74 @@ export declare type ReportCellValue = string | number | boolean | null;
 
 export declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
 
+export declare interface ReportComponentExtensionBinding {
+    id: string;
+    version: string;
+    props: Readonly<Record<string, ReportComponentValue>>;
+    /** Host-defined JSON only: core does not execute queries, scripts or property paths in this binding. */
+    binding?: ReportComponentJson;
+}
+
+export declare interface ReportComponentExtensionContext extends ComponentImageContext {
+    readonly extension: Readonly<ReportComponentExtensionBinding>;
+}
+
+export declare interface ReportComponentExtensionDefinition extends ReportComponentExtensionMetadata {
+    /** Trusted runtime loader, never read from template JSON or a remote import URL. */
+    load(signal: AbortSignal): ReportComponentExtensionRenderer | Promise<ReportComponentExtensionRenderer>;
+}
+
+export declare class ReportComponentExtensionError extends Error {
+    readonly code: "definition" | "binding" | "load" | "disposed";
+    readonly path: string;
+    readonly extensionId?: string | undefined;
+    constructor(code: "definition" | "binding" | "load" | "disposed", message: string, path?: string, extensionId?: string | undefined);
+}
+
+export declare interface ReportComponentExtensionMetadata {
+    id: string;
+    version: string;
+    kind: ImageComponentKind;
+    label: string;
+    description?: string;
+    properties?: Readonly<Record<string, ReportComponentProperty>>;
+}
+
+export declare interface ReportComponentExtensionRenderer {
+    render(context: ReportComponentExtensionContext): string | Promise<string>;
+    dispose?(): void | Promise<void>;
+}
+
+export declare type ReportComponentJson = ReportComponentValue | readonly ReportComponentJson[] | {
+    readonly [key: string]: ReportComponentJson;
+};
+
+export declare interface ReportComponentProperty {
+    label: string;
+    type: "string" | "number" | "boolean";
+    required?: boolean;
+    default?: ReportComponentValue;
+    options?: readonly ReportComponentValue[];
+    min?: number;
+    max?: number;
+    maxLength?: number;
+}
+
+export declare interface ReportComponentRegistry extends ComponentAssetRegistry {
+    /** Pass directly as Preview/Runtime assets; no component-specific adapter wiring is needed. */
+    readonly assets: Readonly<Pick<AssetRenderOptions, "assetRegistry">>;
+    describe(kind?: ImageComponentKind): readonly Readonly<ReportComponentExtensionMetadata>[];
+    /** Add native geometry and insert into the existing template/canvas command path. */
+    createComponent(id: string, values?: {
+        props?: Readonly<Record<string, ReportComponentValue>>;
+        binding?: ReportComponentJson;
+    }): Pick<PlanComponent, "kind" | "meta">;
+    /** Idempotent. Abort active consumers, release loaded renderers, and release a late loader when it finishes. */
+    dispose(): Promise<void>;
+}
+
+export declare type ReportComponentValue = string | number | boolean | null;
+
 export declare interface ReportDataTarget {
     datasetId: string;
     field: string;
@@ -1391,7 +1518,15 @@ export declare interface ReportFetchInput extends ReportTaskMonitoring {
     onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 
-export declare interface ReportFieldContract {
+export declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+
+export declare interface ReportFieldCalculation {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+
+export declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
     type: "text" | "number" | "boolean" | "date" | "decimal";
@@ -1406,6 +1541,17 @@ export declare interface ReportFieldContract {
     unit?: string;
 }
 
+export 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;
+}
+
 export declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
     componentIds: string[];
@@ -1701,6 +1847,26 @@ export declare interface ReportTemplateManager {
     rollback(id: string, revision: string, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
 }
 
+export declare interface ReportTemplateMigration {
+    from: string;
+    to: string;
+    /** Pure document transformation; business data, credentials and I/O belong to the host. */
+    migrate(input: Readonly<Record<string, unknown>>): unknown | Promise<unknown>;
+}
+
+export declare class ReportTemplateMigrationError extends Error {
+    readonly code: "definition" | "unsupported" | "result";
+    constructor(code: "definition" | "unsupported" | "result", message: string);
+}
+
+export declare interface ReportTemplateMigrationResult {
+    document: ReportTemplateDocument;
+    steps: readonly {
+        from: string;
+        to: string;
+    }[];
+}
+
 export declare interface ReportTemplateProvider {
     list(context: {
         signal?: AbortSignal;
@@ -1819,6 +1985,14 @@ export declare interface ReportTemplateVersion {
 /** Optional business explanations never replace raw data or schema validation. */
 export declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
 
+/** Preview coordinates only. Output plans and their complete geometry remain unchanged. */
+export declare interface ReportViewport {
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+}
+
 /**
  * 边框开关解析：
  * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）

package/dist/index.d.ts

@@ -42,6 +42,8 @@ export declare interface AssetRenderBudget {
 
 export 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";
@@ -162,6 +164,11 @@ export declare type ColumnFormat = {
 /** 同一字段契约生成列语义和表头，业务侧无需复制另一份字段清单。 */
 export declare function columnsFromContract(contract: DatasetContract, overrides?: Record<string, Partial<TableTemplateColumn>>): TableTemplateColumn[];
 
+export declare interface ComponentAssetRegistry {
+    rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
+
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 export declare interface ComponentBinding {
     field: string;
@@ -265,6 +272,16 @@ export declare function createLocalTemplateCatalog(input: LocalTemplateCatalogIt
 /** 单进程参考适配器；多实例服务请实现具备数据库事务/CAS 的持久化适配器。 */
 export declare function createMemoryTemplateStore(): ReportTemplateStore;
 
+/** Owned preview controller; only mounted grids are windowed. Static renderPage and exports stay complete. */
+export declare function createPageViewportRenderer(page: PlanPage, dpi: number, options: RenderOptions, doc: Document): {
+    element: HTMLElement;
+    update(viewport: ReportViewport, retained?: {
+        componentIndex: number;
+        rowIndex: number;
+        columnIndex: number;
+    }): boolean;
+};
+
 export declare function createProviderReport(definition: Omit<ReportDefinition, "load" | "datasets"> & {
     provider: ReportProvider;
 }): ReportDefinition;
@@ -278,6 +295,9 @@ export declare function createReportCellEditBatch(plan: RenderPlan, inputs: read
 /** Operation-scoped index: avoids repeated geometry work without caching mutable plans globally. */
 export declare function createReportCellResolver(plan: RenderPlan): (address: ReportCellAddress) => ReportCellContext | null;
 
+/** Explicit per-host registry. Templates contain bounded JSON bindings; loaders never come from a template. */
+export declare function createReportComponentRegistry(definitions: readonly ReportComponentExtensionDefinition[]): ReportComponentRegistry;
+
 /** Revalidates the current cell on activation; returns only bounded scalar values and explicit return state. */
 export declare function createReportDrillRequest(plan: RenderPlan, address: ReportCellAddress, action: ReportDrillAction, params?: Readonly<Record<string, string>>): ReportDrillRequest;
 
@@ -310,6 +330,8 @@ export declare function createTemplate(): TemplateBuilder;
 /** 持久化和框架无关的发布流程；历史返回快照，回滚会产生新修订而不会覆盖旧历史。 */
 export declare function createTemplateManager(store: ReportTemplateStore, options?: {
     migrate?: (input: unknown) => unknown | Promise<unknown>;
+    /** Explicit schema chain, applied to saved drafts and loaded/rolled-back documents. Legacy migrate remains save-only. */
+    migrations?: readonly ReportTemplateMigration[];
     now?: () => Date;
     /** Optional publication gate; receives explicit draft snapshots and never replaces CAS. */
     beforePublish?: (context: {
@@ -319,6 +341,9 @@ export declare function createTemplateManager(store: ReportTemplateStore, option
     }) => ReportTemplateReview | Promise<ReportTemplateReview>;
 }): ReportTemplateManager;
 
+/** Explicit, bounded migration chain. Unknown/future versions are never silently downgraded. */
+export declare function createTemplateMigrator(steps?: readonly ReportTemplateMigration[]): (input: unknown) => Promise<ReportTemplateMigrationResult>;
+
 /** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
 export declare function createTemplateRegistry(documents?: readonly ReportTemplateDocument[]): ReportTemplateRegistry;
 
@@ -409,6 +434,9 @@ export declare function evalStyleRule(row: Record<string, unknown>, when: StyleR
 /** A tiny arithmetic parser: no functions, property access, globals, assignments or executable source. */
 export declare function evaluateReportAggregateExpression(expression: string, values: Readonly<Record<string, number>>): number;
 
+/** Derives locatable explanations only from explicit business declarations; never evaluates formulas. */
+export declare function explainDatasetField(contract: DatasetContract, target: ReportDataTarget): ReportDiagnostic[];
+
 declare interface ExpressionOptions {
     numeric?: "number" | "decimal";
     digits?: number;
@@ -448,6 +476,8 @@ export declare function getReportCellContext(plan: RenderPlan, address: ReportCe
 export declare function getReportEditSession(plan: RenderPlan): ReportEditSession | undefined;
 
 export declare interface GridCell {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -777,6 +807,26 @@ export declare interface LocalTemplateCatalogItem {
 /** O(action count), no row scans or listeners per cell; invoke for the focused cell only. */
 export declare function matchReportDrillActions(plan: RenderPlan, address: ReportCellAddress, actions: readonly ReportDrillAction[]): ReportDrillAction[];
 
+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 type MatrixDimensionOrder = "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 MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -791,6 +841,10 @@ 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;
 }
 
 export declare function measurePageSizePx(page: Pick<PlanPage, "pageWidthMm" | "pageHeightMm">, dpi?: number): {
@@ -825,6 +879,11 @@ export 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;
 }
 
@@ -1223,6 +1282,74 @@ export declare type ReportCellValue = string | number | boolean | null;
 
 export declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
 
+export declare interface ReportComponentExtensionBinding {
+    id: string;
+    version: string;
+    props: Readonly<Record<string, ReportComponentValue>>;
+    /** Host-defined JSON only: core does not execute queries, scripts or property paths in this binding. */
+    binding?: ReportComponentJson;
+}
+
+export declare interface ReportComponentExtensionContext extends ComponentImageContext {
+    readonly extension: Readonly<ReportComponentExtensionBinding>;
+}
+
+export declare interface ReportComponentExtensionDefinition extends ReportComponentExtensionMetadata {
+    /** Trusted runtime loader, never read from template JSON or a remote import URL. */
+    load(signal: AbortSignal): ReportComponentExtensionRenderer | Promise<ReportComponentExtensionRenderer>;
+}
+
+export declare class ReportComponentExtensionError extends Error {
+    readonly code: "definition" | "binding" | "load" | "disposed";
+    readonly path: string;
+    readonly extensionId?: string | undefined;
+    constructor(code: "definition" | "binding" | "load" | "disposed", message: string, path?: string, extensionId?: string | undefined);
+}
+
+export declare interface ReportComponentExtensionMetadata {
+    id: string;
+    version: string;
+    kind: ImageComponentKind;
+    label: string;
+    description?: string;
+    properties?: Readonly<Record<string, ReportComponentProperty>>;
+}
+
+export declare interface ReportComponentExtensionRenderer {
+    render(context: ReportComponentExtensionContext): string | Promise<string>;
+    dispose?(): void | Promise<void>;
+}
+
+export declare type ReportComponentJson = ReportComponentValue | readonly ReportComponentJson[] | {
+    readonly [key: string]: ReportComponentJson;
+};
+
+export declare interface ReportComponentProperty {
+    label: string;
+    type: "string" | "number" | "boolean";
+    required?: boolean;
+    default?: ReportComponentValue;
+    options?: readonly ReportComponentValue[];
+    min?: number;
+    max?: number;
+    maxLength?: number;
+}
+
+export declare interface ReportComponentRegistry extends ComponentAssetRegistry {
+    /** Pass directly as Preview/Runtime assets; no component-specific adapter wiring is needed. */
+    readonly assets: Readonly<Pick<AssetRenderOptions, "assetRegistry">>;
+    describe(kind?: ImageComponentKind): readonly Readonly<ReportComponentExtensionMetadata>[];
+    /** Add native geometry and insert into the existing template/canvas command path. */
+    createComponent(id: string, values?: {
+        props?: Readonly<Record<string, ReportComponentValue>>;
+        binding?: ReportComponentJson;
+    }): Pick<PlanComponent, "kind" | "meta">;
+    /** Idempotent. Abort active consumers, release loaded renderers, and release a late loader when it finishes. */
+    dispose(): Promise<void>;
+}
+
+export declare type ReportComponentValue = string | number | boolean | null;
+
 export declare interface ReportDataTarget {
     datasetId: string;
     field: string;
@@ -1391,7 +1518,15 @@ export declare interface ReportFetchInput extends ReportTaskMonitoring {
     onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 
-export declare interface ReportFieldContract {
+export declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+
+export declare interface ReportFieldCalculation {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+
+export declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
     type: "text" | "number" | "boolean" | "date" | "decimal";
@@ -1406,6 +1541,17 @@ export declare interface ReportFieldContract {
     unit?: string;
 }
 
+export 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;
+}
+
 export declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
     componentIds: string[];
@@ -1701,6 +1847,26 @@ export declare interface ReportTemplateManager {
     rollback(id: string, revision: string, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
 }
 
+export declare interface ReportTemplateMigration {
+    from: string;
+    to: string;
+    /** Pure document transformation; business data, credentials and I/O belong to the host. */
+    migrate(input: Readonly<Record<string, unknown>>): unknown | Promise<unknown>;
+}
+
+export declare class ReportTemplateMigrationError extends Error {
+    readonly code: "definition" | "unsupported" | "result";
+    constructor(code: "definition" | "unsupported" | "result", message: string);
+}
+
+export declare interface ReportTemplateMigrationResult {
+    document: ReportTemplateDocument;
+    steps: readonly {
+        from: string;
+        to: string;
+    }[];
+}
+
 export declare interface ReportTemplateProvider {
     list(context: {
         signal?: AbortSignal;
@@ -1819,6 +1985,14 @@ export declare interface ReportTemplateVersion {
 /** Optional business explanations never replace raw data or schema validation. */
 export declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
 
+/** Preview coordinates only. Output plans and their complete geometry remain unchanged. */
+export declare interface ReportViewport {
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+}
+
 /**
  * 边框开关解析：
  * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）