@agile-team/mach-report 2.15.0 → 2.17.0

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,9 +81,20 @@ 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;
 
+export declare interface FileReportDocumentStore extends ReportDocumentStore {
+    close(): Promise<void>;
+}
+
+export declare interface FileReportDocumentStoreOptions extends ReportDocumentBudget {
+    directory: string;
+}
+
 export declare interface FileReportJobStore extends ReportJobStore {
     close(): Promise<void>;
 }
@@ -85,6 +105,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,12 +130,28 @@ 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;
     workerOptions?: WorkerOptions_2;
 }
 
+/** Exclusive-process disk reference. Pages stay on disk; manifest/page reads and appends are bounded. */
+export declare function openFileReportDocumentStore(options: FileReportDocumentStoreOptions): Promise<FileReportDocumentStore>;
+
 /** Durable local store with one process owner; database adapters provide multi-instance atomic CAS. */
 export declare function openFileReportJobStore(options: FileReportJobStoreOptions): Promise<FileReportJobStore>;
 
@@ -213,6 +251,16 @@ 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. */
@@ -257,6 +305,73 @@ declare interface ReportDiagnostic {
     target?: ReportDataTarget;
 }
 
+declare interface ReportDocumentBudget {
+    maxDocuments?: number;
+    maxBytes?: number;
+    maxPages?: number;
+    maxPageBytes?: number;
+    maxManifestBytes?: number;
+}
+
+declare interface ReportDocumentManifest {
+    scope: string;
+    id: string;
+    version: string;
+    /** CAS token increases after each append and completion. */
+    revision: number;
+    state: "building" | "complete" | "failed";
+    failure?: {
+        code: "cancelled" | "generation";
+        message: string;
+    };
+    pageCount: number;
+    bytes: number;
+    plan: Omit<RenderPlan, "pages">;
+    metadata?: Omit<PreparedReport, "plan">;
+}
+
+declare interface ReportDocumentStore {
+    create(input: Pick<ReportDocumentManifest, "scope" | "id" | "version" | "plan">, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    append(scope: string, id: string, version: string, expectedRevision: number, page: PlanPage, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    complete(scope: string, id: string, version: string, expectedRevision: number, metadata?: Omit<PreparedReport, "plan">, signal?: AbortSignal): Promise<ReportDocumentManifest>;
+    fail(scope: string, id: string, version: string, expectedRevision: number, failure: NonNullable<ReportDocumentManifest["failure"]>): Promise<ReportDocumentManifest>;
+    read(scope: string, id: string, signal?: AbortSignal): Promise<ReportDocumentManifest | undefined>;
+    readPage(scope: string, id: string, version: string, index: number, signal?: AbortSignal): Promise<PlanPage | undefined>;
+    remove(scope: string, id: string, version: string, signal?: AbortSignal): Promise<boolean>;
+}
+
+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;
 };
@@ -338,6 +453,8 @@ declare interface ReportJobTombstone {
     expiresAt: number;
 }
 
+declare type ReportLocalExport = (input: ReportRuntimePreparedExportInput) => Promise<ReportRuntimeExportResult>;
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -402,6 +519,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. */
@@ -414,10 +541,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;
     };
 }
 
@@ -438,6 +566,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;
@@ -494,6 +624,7 @@ export declare class ReportWorkerError extends Error {
 
 declare interface ReportWorkerOptions {
     timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
 }
 
 declare interface RichParagraph {