@agile-team/mach-report 2.5.0 → 2.7.0

package/dist/index.d.ts

@@ -1,8 +1,40 @@
 /** 复制发生变化的页/组件/行；原计划保持不变，并拒绝覆盖已改变的单元格。 */
 export declare function applyReportCellEdit(plan: RenderPlan, edit: ReportCellEdit): RenderPlan;
 
+/** Transactional from the caller's perspective: a later conflict never exposes earlier writes. */
+export declare function applyReportCellEditBatch(plan: RenderPlan, batch: Pick<ReportEditBatch, "edits">): RenderPlan;
+
+/** Refresh concurrency metadata without changing values, layout, or the host's source objects. */
+export declare function applyReportEditResult(plan: RenderPlan, batch: ReportEditBatch, result: void | ReportEditResult): RenderPlan;
+
 export declare function assertRenderPlan(input: unknown): PlanPage[];
 
+export declare function assertReportParams(defs: readonly ReportParamDef[], input?: Record<string, unknown>): Record<string, string>;
+
+export 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;
+}
+
+export 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;
+}
+
+export declare interface AsyncCanvasRenderOptions extends CanvasRenderOptions, AssetRenderOptions {
+    /** Optional image decoder for CORS-aware URLs or custom assets. Browser default supports image data URLs. */
+    imageLoader?: CanvasImageLoader;
+}
+
 /** 盒子边框语义：四边开关 + 内部网格线（四边全关则内线不画） */
 export declare interface BoxBorders {
     top: boolean;
@@ -13,6 +45,8 @@ export declare interface BoxBorders {
     inner: boolean;
 }
 
+export declare type CanvasImageLoader = (source: string, signal?: AbortSignal) => Promise<CanvasImageSource>;
+
 export declare interface CanvasPager {
     /** 挂载到滚动容器（viewport，overflow:auto），接管其内容 */
     attach(viewport: HTMLElement): void;
@@ -24,7 +58,7 @@ export declare interface CanvasPager {
     };
 }
 
-export declare interface CanvasPagerOptions extends CanvasRenderOptions {
+export declare interface CanvasPagerOptions extends AsyncCanvasRenderOptions {
     /** 预渲染页数缓冲（窗口两侧各加 N 页），默认 1 */
     overscan?: number;
     /** 页间距 px，默认 18 */
@@ -33,10 +67,12 @@ export declare interface CanvasPagerOptions extends CanvasRenderOptions {
     pagesPerFrame?: number;
 }
 
-export declare interface CanvasRenderOptions {
+export declare interface CanvasRenderOptions extends OutputDiagnosticOptions {
     /** 设备像素比，默认取运行环境 devicePixelRatio */
     dpr?: number;
     dpi?: number;
+    /** Per-page bitmap allocation guard; default 64 million pixels (about 256 MB RGBA). */
+    maxCanvasPixels?: number;
     /** 文本默认字体族 */
     fontFamily?: string;
     /** 文本测量器（默认启发式） */
@@ -48,6 +84,7 @@ export declare interface CanvasRenderOptions {
 
 export declare interface CanvasRenderResult {
     canvases: HTMLCanvasElement[];
+    diagnostics: OutputDiagnostic[];
 }
 
 export declare function charWidthEm(ch: string): number;
@@ -79,6 +116,19 @@ export declare type ColumnFormat = {
     pattern?: string;
 };
 
+/** 同一字段契约生成列语义和表头，业务侧无需复制另一份字段清单。 */
+export declare function columnsFromContract(contract: DatasetContract, overrides?: Record<string, Partial<TableTemplateColumn>>): TableTemplateColumn[];
+
+export declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+export declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
 export declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 
 export declare interface ComponentStyle {
@@ -127,15 +177,30 @@ export declare function createCanvasPager(plan: RenderPlan, options?: CanvasPage
 /** 兼容旧 API：默认启发式测量 */
 export declare function createHeuristicMeasurer(): TextMeasurer;
 
+/** 单进程参考适配器；多实例服务请实现具备数据库事务/CAS 的持久化适配器。 */
+export declare function createMemoryTemplateStore(): ReportTemplateStore;
+
+export declare function createProviderReport(definition: Omit<ReportDefinition, "load" | "datasets"> & {
+    provider: ReportProvider;
+}): ReportDefinition;
+
 /** 生成可供宿主持久化/审计的补丁；不修改 plan 或宿主业务对象。 */
 export declare function createReportCellEdit(plan: RenderPlan, address: ReportCellAddress, input: ReportCellValue): ReportCellEdit;
 
+/** Parse and validate every value before persistence. No plan or source objects are mutated. */
+export declare function createReportCellEditBatch(plan: RenderPlan, inputs: readonly ReportCellInput[], requestId: string): ReportEditBatch;
+
+/** Operation-scoped index: avoids repeated geometry work without caching mutable plans globally. */
+export declare function createReportCellResolver(plan: RenderPlan): (address: ReportCellAddress) => ReportCellContext | null;
+
 /**
  * 框架无关的报表数据源：注册一次模板与取数，包内完成分页、校验、按 ID 顺序合并。
  * 不缓存业务结果、不推断接口包装、不自动重试；鉴权与完整数据范围由宿主决定。
  */
 export declare function createReportSource(reports: ReportRegistry, options?: {
     onWarning?: (message: string) => void;
+    onDatasets?: (reportId: string, datasets: DatasetRows, template: ReportTemplate) => void;
+    maxPages?: number;
 }): ReportSource;
 
 /**
@@ -146,16 +211,48 @@ export declare function createTableTemplate(options: TableTemplateOptions): Repo
 
 export declare function createTemplate(): TemplateBuilder;
 
+/** 持久化和框架无关的发布流程；历史返回快照，回滚会产生新修订而不会覆盖旧历史。 */
+export declare function createTemplateManager(store: ReportTemplateStore, options?: {
+    migrate?: (input: unknown) => unknown | Promise<unknown>;
+    now?: () => Date;
+}): ReportTemplateManager;
+
 /** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
 export declare function createTemplateRegistry(documents?: readonly ReportTemplateDocument[]): ReportTemplateRegistry;
 
 export declare const CSS_DPI = 96;
 
+export declare interface DatasetContract {
+    fields: readonly ReportFieldContract[];
+    rowKey?: string;
+}
+
+export declare interface DatasetIssue {
+    code: "schema" | "budget" | "row" | "required" | "type" | "enum" | "range" | "row-key";
+    path: string;
+    message: string;
+    rowIndex?: number;
+    field?: string;
+}
+
+/** 公开JSON Schema供Java DTO/表单/接口文档复用；decimal保持文本以免精度丢失。 */
+export declare function datasetJsonSchema(contract: DatasetContract): Record<string, unknown>;
+
 export declare type DatasetRows = Record<string, Record<string, unknown>[]>;
 
+export declare interface DatasetValidationOptions {
+    path?: string;
+    maxRows?: number;
+    maxCells?: number;
+    maxIssues?: number;
+}
+
 /** 默认边框线宽（pt） */
 export declare const DEFAULT_BORDER_PT = 0.75;
 
+/** Browser preview, Canvas metrics and pagination use the same fallback font stack. */
+export declare const DEFAULT_FONT_FAMILY = "\"Microsoft YaHei\", sans-serif";
+
 /** 默认字号（pt） */
 export declare const DEFAULT_FONT_PT = 10.5;
 
@@ -185,6 +282,9 @@ export declare function evalStyleRule(row: Record<string, unknown>, when: StyleR
 /** 同步 text/raw value，所有输出后端读取同一份更新后的 RenderPlan。 */
 export declare function formatReportCellEdit(context: ReportCellContext, value: ReportCellValue): string;
 
+/** TSV with Excel-compatible quoting; quoted line breaks remain inside their cells. */
+export declare function formatReportClipboard(rows: readonly (readonly string[])[]): string;
+
 /**
  * 应用格式化。非数值/无法解析时原样返回基础文本（降级不报错）：
  * - number：digits 小数位 + 可选千分位（12,345.60；thousands 默认 false）
@@ -195,7 +295,6 @@ export declare function formatValue(value: unknown, format?: ColumnFormat): stri
 
 declare type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthMm" | "heightMm">>;
 
-/** 缺失、被合并覆盖、显式 null 占位不生成编辑目标。 */
 export declare function getReportCellContext(plan: RenderPlan, address: ReportCellAddress): ReportCellContext | null;
 
 export declare interface GridCell {
@@ -209,6 +308,7 @@ export declare interface GridCell {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -253,7 +353,9 @@ export declare interface GridLayout {
 /** 启发式测量器：无 Canvas 时的默认宽度估算 */
 export declare const heuristicMeasurer: TextMeasurer;
 
-export declare interface ImageRenderOptions extends CanvasRenderOptions {
+export declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+
+export declare interface ImageRenderOptions extends AsyncCanvasRenderOptions {
     /** 图片格式（默认 png；jpeg 体积更小但无透明） */
     format?: "png" | "jpeg";
     /** jpeg 质量 0-1（默认 0.92，仅 jpeg 生效） */
@@ -262,10 +364,15 @@ export declare interface ImageRenderOptions extends CanvasRenderOptions {
 
 export declare interface ImageRenderResult {
     blobs: Blob[];
+    diagnostics: OutputDiagnostic[];
 }
 
+export declare function inspectOutputCapabilities(plan: RenderPlan, format: OutputFormat): OutputDiagnostic[];
+
 export declare function isImageBackedComponent(comp: PlanComponent): boolean;
 
+export declare function isReportDate(value: string): boolean;
+
 export declare function isRichText(comp: PlanComponent): boolean;
 
 /** 默认行高倍数（基线距 = 字号 × 该系数） */
@@ -293,6 +400,8 @@ export declare interface ListColumn {
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
     valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
 }
 
 export declare interface ListComponent {
@@ -306,6 +415,10 @@ export declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     fontSizePt?: number;
     headerBold?: boolean;
@@ -318,6 +431,8 @@ export declare interface ListComponent {
     /** 表头默认对齐，列配置可覆盖。 */
     headerAlign?: ComponentStyle["align"];
     headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -363,6 +478,46 @@ export declare function mmToPx(value: number, dpi?: number): number;
 
 export declare function mmToPxFactor(dpi?: number): number;
 
+export declare class OutputAssetError extends Error {
+    readonly diagnostic: OutputDiagnostic;
+    readonly cause: unknown;
+    constructor(diagnostic: OutputDiagnostic, cause?: unknown);
+}
+
+export 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;
+}
+
+export 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";
+}
+
+export declare class OutputFidelityError extends Error {
+    readonly diagnostics: readonly OutputDiagnostic[];
+    readonly code = "output-fidelity";
+    constructor(diagnostics: readonly OutputDiagnostic[]);
+}
+
+export declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+export declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+
 export declare class PageBuilder {
     private readonly parent;
     private readonly page;
@@ -408,6 +563,15 @@ export declare interface PaginateOptions {
     mmPerRow?: number;
     /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
     measurer?: TextMeasurer;
+    /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
+    maxPages?: number;
+}
+
+export declare class PaginatePageLimitError extends Error {
+    readonly limit: number;
+    readonly actual: number;
+    readonly code = "page-limit";
+    constructor(limit: number, actual: number);
 }
 
 export declare interface PaginateResult {
@@ -429,9 +593,15 @@ export declare type PaperName = keyof typeof PAPER_SIZES;
 /** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
 export declare function parseDateLocal(input: string): Date | null;
 
+/** Core type parsing is authoritative; field controls add restrictions, never coerce IDs or bypass readonly. */
+export declare function parseReportCellFieldInput(context: ReportCellContext, input: ReportCellValue, field?: ReportCellFieldOptions): ReportCellValue;
+
 /** 严格解析编辑输入；文本列不隐式推断数值，清空数值/布尔列得到 null。 */
 export declare function parseReportCellInput(context: ReportCellContext, input: ReportCellValue): ReportCellValue;
 
+/** Bounded parser for clipboard data; invalid quotes are rejected before edits are built. */
+export declare function parseReportClipboard(text: string, maxCells?: number): string[][];
+
 /** 校验文件 JSON 文本或接口返回的未知对象，返回独立模板快照。 */
 export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
 
@@ -448,6 +618,8 @@ export declare interface PlanComponent {
     lines?: string[];
     richParagraphs?: RichParagraph[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid;
     table?: PlanTableFragment;
     style?: ComponentStyle;
@@ -495,6 +667,10 @@ export declare interface PlanTableFragment {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 export declare function ptToPx(pt: number, dpi?: number): number;
@@ -505,7 +681,7 @@ export declare const RENDER_PLAN_SCHEMA_VERSION = "1.0.0-mach";
 
 export declare function renderComponent(comp: PlanComponent, dpi: number, options: RenderOptions, doc: Document): HTMLElement;
 
-export declare interface RenderOptions {
+export declare interface RenderOptions extends OutputDiagnosticOptions {
     dpi?: number;
     classNames?: Partial<Record<ClassKey, string>>;
 }
@@ -528,6 +704,9 @@ export declare function renderPlan(plan: RenderPlan, doc: Document, options?: Re
  */
 export declare function renderPlanToCanvas(plan: RenderPlan, options?: CanvasRenderOptions): CanvasRenderResult;
 
+/** Browser async raster output: waits for every image and preserves component paint order. */
+export declare function renderPlanToCanvasAsync(plan: RenderPlan, options?: AsyncCanvasRenderOptions): Promise<CanvasRenderResult>;
+
 /**
  * RenderPlan → 每页一张图片 Blob（浏览器环境）：
  * 复用位图渲染管线（区间/dpr/字体/测量器均可配），再 toBlob 编码。
@@ -536,7 +715,7 @@ export declare function renderPlanToCanvas(plan: RenderPlan, options?: CanvasRen
 export declare function renderPlanToImages(plan: RenderPlan, options?: ImageRenderOptions): Promise<ImageRenderResult>;
 
 /** 模板存储文档版本；与渲染计划版本独立演进。 */
-export declare const REPORT_TEMPLATE_DOCUMENT_VERSION: "1.0";
+export declare const REPORT_TEMPLATE_DOCUMENT_VERSION = "1.0";
 
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 export declare interface ReportCellAddress {
@@ -546,6 +725,11 @@ export declare interface ReportCellAddress {
     columnIndex: number;
 }
 
+export declare interface ReportCellChoice {
+    value: Exclude<ReportCellValue, null>;
+    label?: string;
+}
+
 export declare interface ReportCellContext {
     address: ReportCellAddress;
     cell: Readonly<GridCell>;
@@ -553,6 +737,8 @@ export declare interface ReportCellContext {
     value: ReportCellValue;
     valueType: ReportCellValueType;
     table?: ReportCellTableIdentity;
+    /** Stable business identity. Physical row indices must never be used as database keys. */
+    source?: Readonly<ReportCellSource>;
     editable: boolean;
     readOnlyReason?: ReportCellReadOnlyReason;
 }
@@ -560,6 +746,7 @@ export declare interface ReportCellContext {
 export declare interface ReportCellEdit {
     address: ReportCellAddress;
     table?: ReportCellTableIdentity;
+    source?: Readonly<ReportCellSource>;
     previousValue: ReportCellValue;
     previousText: string;
     value: ReportCellValue;
@@ -571,10 +758,65 @@ export declare class ReportCellEditError extends Error {
     constructor(code: ReportCellEditErrorCode);
 }
 
-export declare type ReportCellEditErrorCode = "missing" | "readonly" | "number" | "boolean" | "conflict";
+export declare type ReportCellEditErrorCode = "missing" | "readonly" | "number" | "boolean" | "conflict" | "duplicate" | "limit" | "atomic" | "clipboard";
+
+export declare function reportCellEditKey(edit: Pick<ReportCellEdit, "address" | "source" | "table">): string;
+
+declare interface ReportCellFieldBase {
+    /** Presentation only; it never grants write permission. */
+    label?: string;
+    hint?: string;
+    unit?: string;
+    required?: boolean;
+}
+
+/** Shared structured validation for browser editors, pasted values and backend adapters. */
+export declare class ReportCellFieldError extends Error {
+    readonly code: ReportCellFieldErrorCode;
+    readonly field: ReportCellFieldOptions;
+    readonly expected?: string | number | undefined;
+    constructor(code: ReportCellFieldErrorCode, field: ReportCellFieldOptions, expected?: string | number | undefined);
+}
+
+export declare type ReportCellFieldErrorCode = "definition" | "type" | "required" | "min" | "max" | "precision" | "length" | "choice" | "date";
+
+export 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;
+});
+
+export declare interface ReportCellInput {
+    address: ReportCellAddress;
+    value: ReportCellValue;
+}
 
 export declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
 
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+export declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
 export declare interface ReportCellTableIdentity {
     id: string;
     /** 逻辑表行索引；跨分页的同一行保持不变。 */
@@ -593,6 +835,11 @@ export declare interface ReportDefinition {
     /** 静态数据；load 存在时优先使用 load 的结果。 */
     datasets?: DatasetRows;
     load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
+    /** 可选统一适配器；load 存在时仍优先 load，兼容已有定义。 */
+    provider?: ReportProvider;
+    /** 可选业务数据契约；声明的数据集缺失或字段不合法时，在分页前给出结构化错误。 */
+    dataSchema?: Record<string, DatasetContract>;
+    dataValidation?: Pick<DatasetValidationOptions, "maxRows" | "maxCells" | "maxIssues">;
     /** 覆盖模板参数定义；动态模板应在此声明查询面板元数据，避免查询前先请求模板。 */
     params?: ReportParamDef[];
     pagination?: PaginateOptions;
@@ -603,18 +850,63 @@ export declare interface ReportDefinitionOptions<TData> extends Omit<ReportDefin
     mapData: (data: TData, context: ReportLoadContext) => DatasetRows;
 }
 
+export declare interface ReportDiagnostic {
+    code: string;
+    message: string;
+    path?: string;
+    severity: "warning" | "error" | "info";
+}
+
+export declare interface ReportEditBatch {
+    /** Idempotency identity; the server should bind it to the exact payload. */
+    requestId: string;
+    edits: ReportCellEdit[];
+}
+
+export declare interface ReportEditConflict {
+    source?: Readonly<ReportCellSource>;
+    address?: ReportCellAddress;
+    message: string;
+    currentValue?: ReportCellValue;
+    revision?: string | number;
+}
+
+export 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[];
+}
+
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 export declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
     getParamDefs?: (reportIds: string[]) => ReportParamDef[];
 }
 
-export declare interface ReportFetchInput {
+export declare interface ReportFetchInput extends ReportTaskMonitoring {
     reportIds: string[];
     params: Record<string, string>;
     signal?: AbortSignal;
     /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
     onWarning?: (message: string) => void;
+    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
+}
+
+export 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;
 }
 
 /** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
@@ -624,6 +916,8 @@ export declare interface ReportLoadContext {
     signal?: AbortSignal;
 }
 
+export declare function reportOutputDiagnostics(plan: RenderPlan, format: OutputFormat, options: OutputDiagnosticOptions): OutputDiagnostic[];
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 export declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -639,10 +933,87 @@ export declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
+}
+
+export declare interface ReportParamIssue {
+    code: ReportParamIssueCode;
+    path: string;
+    field: string;
+    message: string;
+}
+
+export declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+
+/** 描述 typedValues 的 Draft 2020-12 Schema；日期区间额外保留 x-report-* 扩展。 */
+export declare function reportParamsJsonSchema(defs: readonly ReportParamDef[]): Record<string, unknown>;
+
+export declare interface ReportParamValidation {
+    ok: boolean;
+    /** 保留历史取数契约的字符串形式；未知参数保留，不能代替接口权限白名单。 */
+    values: Record<string, string>;
+    /** JSON Schema 对应的规范值：number 参数转换为有限数字。 */
+    typedValues: Record<string, string | number>;
+    issues: ReportParamIssue[];
+}
+
+export declare class ReportParamValidationError extends Error {
+    readonly issues: readonly ReportParamIssue[];
+    readonly code = "params";
+    constructor(issues: readonly ReportParamIssue[]);
+}
+
+/** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
+export declare interface ReportProvider {
+    query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
+    save?(input: ReportSaveInput): ReportSaveResult | Promise<ReportSaveResult>;
+    export?(input: ReportProviderExportInput): ReportProviderExportResult | Promise<ReportProviderExportResult>;
+    templates?: ReportTemplateProvider;
+}
+
+export declare interface ReportProviderExportInput extends ReportLoadContext {
+    format: "pdf" | "xlsx";
+}
+
+export declare interface ReportProviderExportResult {
+    bytes: Uint8Array;
+    contentType: string;
+    fileName?: string;
+    diagnostics?: ReportDiagnostic[];
+}
+
+export declare interface ReportQueryResult {
+    datasets: DatasetRows;
+    revision?: string;
+    sourceToken?: string;
+    diagnostics?: ReportDiagnostic[];
 }
 
 export declare type ReportRegistry = Record<string, ReportDefinition>;
 
+export declare interface ReportSaveInput extends ReportLoadContext {
+    requestId: string;
+    expectedRevision?: string;
+    sourceToken?: string;
+    edits: readonly ReportCellEdit[];
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+
+export declare interface ReportSaveResult {
+    revision: string;
+    sourceToken?: string;
+    conflicts?: Array<{
+        editIndex: number;
+        code: string;
+        message: string;
+    }>;
+    diagnostics?: ReportDiagnostic[];
+}
+
 export declare interface ReportSource extends ReportFetcher {
     getParamDefs(reportIds: string[]): ReportParamDef[];
 }
@@ -653,6 +1024,25 @@ export declare class ReportSourceError extends Error {
     constructor(code: ReportSourceError["code"], message: string, cause?: unknown);
 }
 
+/** 阶段事件只包含可序列化值；不表示估算百分比，也不包含业务数据。 */
+export declare interface ReportTaskEvent {
+    taskId: string;
+    correlationId?: string;
+    stage: "query" | "validate" | "layout" | "encode";
+    status: "started" | "completed" | "failed";
+    reportId?: string;
+    completed?: number;
+    total?: number;
+}
+
+export declare interface ReportTaskMonitoring {
+    taskId?: string;
+    correlationId?: string;
+    onEvent?: ReportTaskObserver;
+}
+
+export declare type ReportTaskObserver = (event: ReportTaskEvent) => void;
+
 export declare interface ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
@@ -662,7 +1052,7 @@ export declare interface ReportTemplate {
 
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 export declare interface ReportTemplateDocument {
-    schemaVersion: typeof REPORT_TEMPLATE_DOCUMENT_VERSION;
+    schemaVersion: "1.0";
     id: string;
     name: string;
     /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
@@ -678,6 +1068,35 @@ export declare class ReportTemplateError extends Error {
 
 export declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
 
+export declare interface ReportTemplateManager {
+    list(signal?: AbortSignal): ReturnType<ReportTemplateStore["list"]>;
+    get(id: string, options?: {
+        draft?: boolean;
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateDocument | undefined>;
+    history(id: string, signal?: AbortSignal): Promise<readonly ReportTemplateVersion[]>;
+    saveDraft(input: unknown, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
+    publish(id: string, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
+    rollback(id: string, revision: string, options: TemplateMutationOptions): Promise<ReportTemplateRecord>;
+}
+
+export declare interface ReportTemplateProvider {
+    list(context: {
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateSummary[]>;
+    get(id: string, context: {
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateDocument | undefined>;
+}
+
+export declare interface ReportTemplateRecord {
+    id: string;
+    revision: string;
+    draft?: ReportTemplateDocument;
+    publishedRevision?: string;
+    published?: ReportTemplateDocument;
+}
+
 export declare interface ReportTemplateRegistry {
     /** 返回独立快照，调用方编辑不会改变目录中的已注册模板。 */
     get(id: string): ReportTemplateDocument | undefined;
@@ -689,8 +1108,34 @@ export declare interface ReportTemplateRegistry {
     remove(id: string): boolean;
 }
 
+/** compareAndSwap 必须由宿主数据库/文件适配器保证原子性，不能用先读再无条件写替代。 */
+export declare interface ReportTemplateStore {
+    read(id: string, signal?: AbortSignal): Promise<ReportTemplateRecord | undefined>;
+    list(signal?: AbortSignal): Promise<Array<{
+        id: string;
+        revision: string;
+        publishedRevision?: string;
+    }>>;
+    history(id: string, signal?: AbortSignal): Promise<ReportTemplateVersion[]>;
+    getVersion(id: string, revision: string, signal?: AbortSignal): Promise<ReportTemplateVersion | undefined>;
+    /** 状态更新和 publication 的不可变追加必须处于同一原子事务；草稿写入不读取历史。 */
+    compareAndSwap(id: string, expectedRevision: string | null, next: ReportTemplateRecord, options: TemplateStoreWriteOptions): Promise<boolean>;
+}
+
+export declare class ReportTemplateStoreError extends Error {
+    readonly code: "conflict" | "missing" | "draft" | "history";
+    constructor(code: "conflict" | "missing" | "draft" | "history", message: string);
+}
+
 export declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
 
+export declare interface ReportTemplateVersion {
+    revision: string;
+    publishedAt: string;
+    document: ReportTemplateDocument;
+    restoredFrom?: string;
+}
+
 /**
  * 边框开关解析：
  * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）
@@ -731,6 +1176,19 @@ export declare function resolvePaper(paper: PaperName | {
     heightMm: number;
 };
 
+/** Resolve optional third-party chart/barcode/QR adapters once, before any output backend. Input stays immutable. */
+export declare function resolvePlanAssets(plan: RenderPlan, options?: ResolvePlanAssetsOptions): Promise<{
+    plan: RenderPlan;
+    diagnostics: OutputDiagnostic[];
+}>;
+
+export declare interface ResolvePlanAssetsOptions extends AssetRenderOptions {
+    /** Only labels diagnostics; no output library is imported. Default dom. */
+    format?: OutputFormat;
+    start?: number;
+    end?: number;
+}
+
 /** 描边解析：颜色 + 线宽（pt） */
 export declare function resolveStroke(style: Pick<ComponentStyle, "borderColor" | "lineColor" | "lineWidthPt"> | undefined, fallbackColor?: string): {
     color: string;
@@ -775,6 +1233,9 @@ export declare interface StyleRule {
     style: Record<string, unknown>;
 }
 
+/** Ordered, net changes for review; a change restored to its original value disappears. */
+export declare function summarizeReportCellEdits(edits: readonly ReportCellEdit[]): ReportCellEdit[];
+
 /** 明细列：显式 widthMm 优先；纸张模式按 flex 分余量，宽表模式按 flex 放大基准列宽。 */
 export declare type TableTemplateColumn = Omit<ListColumn, "widthMm"> & {
     widthMm?: number;
@@ -842,6 +1303,11 @@ export declare class TemplateBuilder {
 
 export declare type TemplateComponent = PlanComponent | ListComponent;
 
+export declare interface TemplateMutationOptions {
+    expectedRevision: string | null;
+    signal?: AbortSignal;
+}
+
 export declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
@@ -854,6 +1320,11 @@ export declare interface TemplatePage {
     components: TemplateComponent[];
 }
 
+export declare interface TemplateStoreWriteOptions {
+    publication?: ReportTemplateVersion;
+    signal?: AbortSignal;
+}
+
 /**
  * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
  *
@@ -863,7 +1334,9 @@ export declare interface TemplatePage {
  */
 export declare interface TextMeasureOptions {
     fontSizePt: number;
+    fontFamily?: string;
     bold?: boolean;
+    italic?: boolean;
     letterSpacingPt?: number;
 }
 
@@ -879,10 +1352,25 @@ export declare function toNumber(value: unknown): number | null;
 
 export declare function validateComponent(comp: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
 
+/** 浏览器/Node共用的只读值校验；返回精确路径，不以0或空数组掩盖接口结构错误。 */
+export declare function validateDatasetRows(input: unknown, contract: DatasetContract, options?: DatasetValidationOptions): {
+    ok: boolean;
+    issues: DatasetIssue[];
+};
+
 export declare function validatePage(page: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
 
 export declare function validateRenderPlan(input: unknown): ValidationResult;
 
+/** Check configuration before opening an input, including JSON/JavaScript callers. */
+export declare function validateReportCellFieldDefinition(context: ReportCellContext, field: ReportCellFieldOptions): void;
+
+/** 模板参数配置错误也统一返回结构化问题，不让无效默认值或边界静默进入后端。 */
+export declare function validateReportParamDefinitions(defs: readonly ReportParamDef[]): ReportParamIssue[];
+
+/** 在浏览器或服务端执行相同默认值、必填、类型、枚举及范围规则。 */
+export declare function validateReportParams(defs: readonly ReportParamDef[], input?: Record<string, unknown>): ReportParamValidation;
+
 /** 对入库/导入模板做声明式校验，不执行分页或数据请求。 */
 export declare function validateReportTemplate(input: unknown): ValidationResult;