@agile-team/mach-report 2.14.0 → 2.16.0

package/dist/server/node.d.cts

@@ -2,6 +2,15 @@
 
 import { WorkerOptions as WorkerOptions_2 } from 'node:worker_threads';
 
+declare interface BrowserReportWorker {
+    postMessage(value: unknown, transfer?: Transferable[]): void;
+    terminate(): void;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    addEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+}
+
 /** Serializable symbol settings. Encoders remain in the optional /codes entry. */
 declare interface CodeOptions {
     /** Explicit content, including an empty value, takes precedence over legacy fallbackText. */
@@ -72,6 +81,9 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+/** Node needs no URL factory: this module is the isolated encoding entry in both ESM and CommonJS builds. */
+export declare function createNodeAutoReportExporter(options?: Omit<ReportExportExecutionOptions, "workerFactory">): ReportAutoExporter;
+
 /** 独立 worker_threads 适配器；worker 入口注册自己的模板/Provider，不把函数跨线程序列化。 */
 export declare function createNodeReportExecutor(options: NodeReportExecutorOptions): ReportRuntimeExecutor;
 
@@ -85,6 +97,8 @@ export declare interface FileReportJobStoreOptions extends ReportJobStoreBudgetO
 }
 
 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 绘制。 */
@@ -108,6 +122,19 @@ declare interface GridCell {
     style?: ComponentStyle;
 }
 
+/** Bounded binary image inspection shared by PDF, Excel and template import. No decoder is loaded. */
+declare interface ImageMediaOptions {
+    maxImageBytes?: number;
+    maxTotalImageBytes?: number;
+    maxImages?: number;
+    /** Decoded pixels per unique image, default 16 million. */
+    maxImagePixels?: number;
+    /** Total decoded pixels for unique media, default 64 million. */
+    maxTotalImagePixels?: number;
+    /** Maximum source dimension, default 16384 pixels. */
+    maxImageDimension?: number;
+}
+
 export declare interface NodeReportExecutorOptions extends ReportWorkerOptions {
     filename?: string | URL;
     workerUrl?: string | URL;
@@ -194,6 +221,8 @@ declare interface PreparedReport {
         revision?: string;
         sourceToken?: string;
     }>;
+    /** Ordered occurrences; legacy revisions remains last-value-by-ID for compatibility. */
+    sources?: ReportRuntimeSource[];
     /** Captured metrics identity; absence on old saved instances remains supported with diagnostics. */
     layout?: {
         textMetrics: "heuristic" | "provided" | "font-bytes";
@@ -211,8 +240,20 @@ declare interface RenderPlan {
 /** Optional publication digest for Node hosts; use as reviewReportPublication({ digest }). */
 export declare function reportArtifactSha256(bytes: Uint8Array): string;
 
+export declare interface ReportAutoExporter {
+    exportPrepared(input: ReportRuntimePreparedExportInput, localOverride?: ReportLocalExport): Promise<ReportAutoExportResult>;
+    cancel(): void;
+    dispose(): void;
+}
+
+export declare interface ReportAutoExportResult extends ReportRuntimeExportResult {
+    execution: ReportExportDecision;
+}
+
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 declare interface ReportCellSource {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
     datasetId: string;
     rowKey: string | number;
     field: string;
@@ -226,6 +267,8 @@ declare interface ReportDataTarget {
     rowKey?: string | number;
     /** Use table identity when the same dataset appears in several tables. */
     tableId?: string;
+    /** Assigned by the source/runtime when several reports share dataset names. */
+    reportScope?: string;
 }
 
 declare interface ReportDescription {
@@ -251,6 +294,38 @@ declare interface ReportDiagnostic {
     target?: ReportDataTarget;
 }
 
+export declare interface ReportExportDecision {
+    mode: "local" | "worker";
+    reason: ReportExportDecisionReason;
+    /** Lower bounds: traversal stops as soon as isolation is warranted. No font or image hashing. */
+    estimate: {
+        pages: number;
+        cells: number;
+        bytes: number;
+    };
+    hardCancellation: boolean;
+}
+
+declare type ReportExportDecisionReason = "small-task" | "threshold" | "scan-limit" | "explicit-local" | "explicit-worker" | "worker-unavailable" | "worker-start-failed" | "nonserializable-options";
+
+export declare interface ReportExportExecutionOptions {
+    mode?: "auto" | "worker" | "local";
+    /** A fresh bundler-managed module Worker for every call; never a shared worker. */
+    workerFactory?: () => BrowserReportWorker;
+    thresholds?: ReportExportThresholds;
+    /** Auto only. Startup unavailability may use local; encoding failures never retry. */
+    fallback?: "local" | "error";
+    timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
+    onDecision?: (decision: ReportExportDecision) => void;
+}
+
+declare interface ReportExportThresholds {
+    cells?: number;
+    pages?: number;
+    bytes?: number;
+}
+
 declare type ReportJobJson = null | boolean | number | string | ReportJobJson[] | {
     [key: string]: ReportJobJson;
 };
@@ -332,6 +407,8 @@ declare interface ReportJobTombstone {
     expiresAt: number;
 }
 
+declare type ReportLocalExport = (input: ReportRuntimePreparedExportInput) => Promise<ReportRuntimeExportResult>;
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -344,6 +421,10 @@ declare interface ReportParamDef {
         label: string;
         value: string;
     }>;
+    /** 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. */
+    dependsOn?: string[];
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
@@ -361,7 +442,7 @@ declare interface ReportParamIssue {
     message: string;
 }
 
-declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
 
 declare interface ReportParamValidation {
     ok: boolean;
@@ -392,6 +473,16 @@ declare interface ReportRuntime {
     exportPrepared(input: ReportRuntimePreparedExportInput): Promise<ReportRuntimeExportResult>;
 }
 
+declare interface ReportRuntimeBudget {
+    maxRows?: number;
+    maxPages?: number;
+    maxCells?: number;
+    maxOutputBytes?: number;
+    /** Bound the plain JSON snapshot accepted by exportPrepared (default 64 MB). */
+    maxPreparedBytes?: number;
+    maxDurationMs?: number;
+}
+
 /** 可用 worker_threads/进程/RPC 实现；接收可序列化请求，signal 由桥接层映射为取消消息。 */
 declare interface ReportRuntimeExecutor {
     /** Old custom executors may omit this; the runtime explicitly rejects unsupported prepared output. */
@@ -404,10 +495,11 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
     format: "pdf" | "xlsx";
     /** strict 在编码前拒绝已识别的输出降级；默认保留诊断并继续。 */
     fidelity?: "warn" | "strict";
-    xlsx?: {
+    xlsx?: ImageMediaOptions & {
         sheetMode?: "auto" | "pages" | "continuous";
         valueMode?: "text" | "raw";
         paperSize?: "auto" | "a3" | "a4" | "a5";
+        sheetName?: (sheetIndex: number) => string;
     };
 }
 
@@ -428,6 +520,8 @@ declare interface ReportRuntimeInput extends ReportTaskMonitoring {
 /** Encode an existing plan without querying providers or repaginating. */
 declare interface ReportRuntimePreparedExportInput extends ReportTaskMonitoring {
     prepared: PreparedReport;
+    /** verify checks font metric identity; preserve explicitly keeps existing geometry, with a diagnostic. Encoding fidelity is unchanged. */
+    layoutPolicy?: "verify" | "preserve";
     format: ReportRuntimeExportInput["format"];
     fidelity?: ReportRuntimeExportInput["fidelity"];
     pdf?: ReportPdfFontOptions;
@@ -435,6 +529,15 @@ declare interface ReportRuntimePreparedExportInput extends ReportTaskMonitoring
     signal?: AbortSignal;
 }
 
+/** One query occurrence; repeated report IDs retain independent provenance. */
+declare interface ReportRuntimeSource {
+    reportId: string;
+    reportIndex: number;
+    reportScope: string;
+    revision?: string;
+    sourceToken?: string;
+}
+
 declare interface ReportRuntimeStats {
     rows: number;
     pages: number;
@@ -475,6 +578,7 @@ export declare class ReportWorkerError extends Error {
 
 declare interface ReportWorkerOptions {
     timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
 }
 
 declare interface RichParagraph {

package/dist/server/node.d.ts

@@ -2,6 +2,15 @@
 
 import { WorkerOptions as WorkerOptions_2 } from 'node:worker_threads';
 
+declare interface BrowserReportWorker {
+    postMessage(value: unknown, transfer?: Transferable[]): void;
+    terminate(): void;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    addEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+}
+
 /** Serializable symbol settings. Encoders remain in the optional /codes entry. */
 declare interface CodeOptions {
     /** Explicit content, including an empty value, takes precedence over legacy fallbackText. */
@@ -72,6 +81,9 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+/** Node needs no URL factory: this module is the isolated encoding entry in both ESM and CommonJS builds. */
+export declare function createNodeAutoReportExporter(options?: Omit<ReportExportExecutionOptions, "workerFactory">): ReportAutoExporter;
+
 /** 独立 worker_threads 适配器；worker 入口注册自己的模板/Provider，不把函数跨线程序列化。 */
 export declare function createNodeReportExecutor(options: NodeReportExecutorOptions): ReportRuntimeExecutor;
 
@@ -85,6 +97,8 @@ export declare interface FileReportJobStoreOptions extends ReportJobStoreBudgetO
 }
 
 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 绘制。 */
@@ -108,6 +122,19 @@ declare interface GridCell {
     style?: ComponentStyle;
 }
 
+/** Bounded binary image inspection shared by PDF, Excel and template import. No decoder is loaded. */
+declare interface ImageMediaOptions {
+    maxImageBytes?: number;
+    maxTotalImageBytes?: number;
+    maxImages?: number;
+    /** Decoded pixels per unique image, default 16 million. */
+    maxImagePixels?: number;
+    /** Total decoded pixels for unique media, default 64 million. */
+    maxTotalImagePixels?: number;
+    /** Maximum source dimension, default 16384 pixels. */
+    maxImageDimension?: number;
+}
+
 export declare interface NodeReportExecutorOptions extends ReportWorkerOptions {
     filename?: string | URL;
     workerUrl?: string | URL;
@@ -194,6 +221,8 @@ declare interface PreparedReport {
         revision?: string;
         sourceToken?: string;
     }>;
+    /** Ordered occurrences; legacy revisions remains last-value-by-ID for compatibility. */
+    sources?: ReportRuntimeSource[];
     /** Captured metrics identity; absence on old saved instances remains supported with diagnostics. */
     layout?: {
         textMetrics: "heuristic" | "provided" | "font-bytes";
@@ -211,8 +240,20 @@ declare interface RenderPlan {
 /** Optional publication digest for Node hosts; use as reviewReportPublication({ digest }). */
 export declare function reportArtifactSha256(bytes: Uint8Array): string;
 
+export declare interface ReportAutoExporter {
+    exportPrepared(input: ReportRuntimePreparedExportInput, localOverride?: ReportLocalExport): Promise<ReportAutoExportResult>;
+    cancel(): void;
+    dispose(): void;
+}
+
+export declare interface ReportAutoExportResult extends ReportRuntimeExportResult {
+    execution: ReportExportDecision;
+}
+
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 declare interface ReportCellSource {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
     datasetId: string;
     rowKey: string | number;
     field: string;
@@ -226,6 +267,8 @@ declare interface ReportDataTarget {
     rowKey?: string | number;
     /** Use table identity when the same dataset appears in several tables. */
     tableId?: string;
+    /** Assigned by the source/runtime when several reports share dataset names. */
+    reportScope?: string;
 }
 
 declare interface ReportDescription {
@@ -251,6 +294,38 @@ declare interface ReportDiagnostic {
     target?: ReportDataTarget;
 }
 
+export declare interface ReportExportDecision {
+    mode: "local" | "worker";
+    reason: ReportExportDecisionReason;
+    /** Lower bounds: traversal stops as soon as isolation is warranted. No font or image hashing. */
+    estimate: {
+        pages: number;
+        cells: number;
+        bytes: number;
+    };
+    hardCancellation: boolean;
+}
+
+declare type ReportExportDecisionReason = "small-task" | "threshold" | "scan-limit" | "explicit-local" | "explicit-worker" | "worker-unavailable" | "worker-start-failed" | "nonserializable-options";
+
+export declare interface ReportExportExecutionOptions {
+    mode?: "auto" | "worker" | "local";
+    /** A fresh bundler-managed module Worker for every call; never a shared worker. */
+    workerFactory?: () => BrowserReportWorker;
+    thresholds?: ReportExportThresholds;
+    /** Auto only. Startup unavailability may use local; encoding failures never retry. */
+    fallback?: "local" | "error";
+    timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
+    onDecision?: (decision: ReportExportDecision) => void;
+}
+
+declare interface ReportExportThresholds {
+    cells?: number;
+    pages?: number;
+    bytes?: number;
+}
+
 declare type ReportJobJson = null | boolean | number | string | ReportJobJson[] | {
     [key: string]: ReportJobJson;
 };
@@ -332,6 +407,8 @@ declare interface ReportJobTombstone {
     expiresAt: number;
 }
 
+declare type ReportLocalExport = (input: ReportRuntimePreparedExportInput) => Promise<ReportRuntimeExportResult>;
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -344,6 +421,10 @@ declare interface ReportParamDef {
         label: string;
         value: string;
     }>;
+    /** 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. */
+    dependsOn?: string[];
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
@@ -361,7 +442,7 @@ declare interface ReportParamIssue {
     message: string;
 }
 
-declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
 
 declare interface ReportParamValidation {
     ok: boolean;
@@ -392,6 +473,16 @@ declare interface ReportRuntime {
     exportPrepared(input: ReportRuntimePreparedExportInput): Promise<ReportRuntimeExportResult>;
 }
 
+declare interface ReportRuntimeBudget {
+    maxRows?: number;
+    maxPages?: number;
+    maxCells?: number;
+    maxOutputBytes?: number;
+    /** Bound the plain JSON snapshot accepted by exportPrepared (default 64 MB). */
+    maxPreparedBytes?: number;
+    maxDurationMs?: number;
+}
+
 /** 可用 worker_threads/进程/RPC 实现；接收可序列化请求，signal 由桥接层映射为取消消息。 */
 declare interface ReportRuntimeExecutor {
     /** Old custom executors may omit this; the runtime explicitly rejects unsupported prepared output. */
@@ -404,10 +495,11 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
     format: "pdf" | "xlsx";
     /** strict 在编码前拒绝已识别的输出降级；默认保留诊断并继续。 */
     fidelity?: "warn" | "strict";
-    xlsx?: {
+    xlsx?: ImageMediaOptions & {
         sheetMode?: "auto" | "pages" | "continuous";
         valueMode?: "text" | "raw";
         paperSize?: "auto" | "a3" | "a4" | "a5";
+        sheetName?: (sheetIndex: number) => string;
     };
 }
 
@@ -428,6 +520,8 @@ declare interface ReportRuntimeInput extends ReportTaskMonitoring {
 /** Encode an existing plan without querying providers or repaginating. */
 declare interface ReportRuntimePreparedExportInput extends ReportTaskMonitoring {
     prepared: PreparedReport;
+    /** verify checks font metric identity; preserve explicitly keeps existing geometry, with a diagnostic. Encoding fidelity is unchanged. */
+    layoutPolicy?: "verify" | "preserve";
     format: ReportRuntimeExportInput["format"];
     fidelity?: ReportRuntimeExportInput["fidelity"];
     pdf?: ReportPdfFontOptions;
@@ -435,6 +529,15 @@ declare interface ReportRuntimePreparedExportInput extends ReportTaskMonitoring
     signal?: AbortSignal;
 }
 
+/** One query occurrence; repeated report IDs retain independent provenance. */
+declare interface ReportRuntimeSource {
+    reportId: string;
+    reportIndex: number;
+    reportScope: string;
+    revision?: string;
+    sourceToken?: string;
+}
+
 declare interface ReportRuntimeStats {
     rows: number;
     pages: number;
@@ -475,6 +578,7 @@ export declare class ReportWorkerError extends Error {
 
 declare interface ReportWorkerOptions {
     timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
 }
 
 declare interface RichParagraph {