@agile-team/mach-report 2.14.0 → 2.16.0

package/dist/worker.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const M=require("./task-events-DQ276fn2.cjs"),P=require("./data-explanation-BktvER5B.cjs"),A=require("./validate-BJ5HIWY8.cjs"),u="mach-report-worker/1";class l extends Error{constructor(r){super(r.message),this.name=r.name,this.code=r.code,this.path=r.path,this.issues=r.issues,this.diagnostics=r.diagnostics}}function p(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function L(e){return p(e)?["rows","pages","cells"].every(r=>typeof e[r]=="number"&&Number.isSafeInteger(e[r])&&e[r]>=0)&&typeof e.durationMs=="number"&&Number.isFinite(e.durationMs)&&e.durationMs>=0:!1}function T(e){return Array.isArray(e)&&e.every(r=>p(r)&&typeof r.code=="string"&&typeof r.message=="string"&&["info","warning","error"].includes(r.severity)&&P.hasValidDataExplanation(r))}function j(e){return p(e)&&Object.values(e).every(r=>p(r)&&(r.revision===void 0||typeof r.revision=="string")&&(r.sourceToken===void 0||typeof r.sourceToken=="string"))}function O(e){return e===void 0?!0:p(e)&&["heuristic","provided","font-bytes"].includes(e.textMetrics)&&(e.fontFingerprint===void 0||typeof e.fontFingerprint=="string"&&/^[a-f0-9]{64}$/.test(e.fontFingerprint))}function S(e,r){if(!p(e)||!L(e.stats)||!T(e.diagnostics)||!j(e.revisions)||!O(e.layout))return!1;if(r==="prepare")return A.validateRenderPlan(e.plan).ok;const t=e.format==="pdf"?"application/pdf":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";return e.bytes instanceof Uint8Array&&(e.format==="pdf"||e.format==="xlsx")&&e.contentType===t}function x(e){if(!e||typeof e!="object")return{message:String(e)};const r={};for(const t of["code","path","field","message"]){const o=e[t];typeof o=="string"&&(r[t]=o)}return r}function F(e){const r=x(e);if(!p(e))return r;for(const t of["format","severity","kind","nid"])typeof e[t]=="string"&&(r[t]=e[t]);for(const t of["pageIndex","componentIndex"])Number.isSafeInteger(e[t])&&e[t]>=0&&(r[t]=e[t]);return Array.isArray(e.componentPath)&&e.componentPath.every(t=>Number.isSafeInteger(t)&&t>=0)&&(r.componentPath=e.componentPath),r}function N(e){if(!(e instanceof Error))return{name:"Error",message:String(e)};const r=e;return{name:e.name,message:e.message,...typeof r.code=="string"?{code:r.code}:{},...typeof r.path=="string"?{path:r.path}:{},...Array.isArray(r.issues)?{issues:r.issues.map(x)}:{},...Array.isArray(r.diagnostics)?{diagnostics:r.diagnostics.map(F)}:{}}}function v(e){if(!e||typeof e!="object")return!1;const r=e;return r.protocol===u&&typeof r.id=="string"&&(r.operation==="prepare"||r.operation==="export"||r.operation==="exportPrepared")&&!!r.input&&typeof r.input=="object"}async function z(e,r,t){try{const o=r.operation==="prepare"?await e.prepare({...r.input,onEvent:t}):r.operation==="exportPrepared"?await e.exportPrepared({...r.input,onEvent:t}):await e.export({...r.input,onEvent:t});return{protocol:u,id:r.id,result:o}}catch(o){return{protocol:u,id:r.id,error:N(o)}}}function _(e){const r=e.result;return!r||!("bytes"in r)||!(r.bytes.buffer instanceof ArrayBuffer)?[]:[r.bytes.buffer]}function $(e,r){if(!p(e)||typeof e.taskId!="string"||!e.taskId||r.taskId!==void 0&&e.taskId!==r.taskId||e.correlationId!==r.correlationId||e.reportId!==void 0&&(typeof e.reportId!="string"||!("reportIds"in r&&r.reportIds.includes(e.reportId)))||!["query","validate","layout","assets","encode"].includes(e.stage)||!["started","completed","failed"].includes(e.status))return!1;for(const t of["completed","total"])if(e[t]!==void 0&&(typeof e[t]!="number"||!Number.isFinite(e[t])||e[t]<0))return!1;return e.completed===void 0||e.total===void 0||e.completed<=e.total}let B=0;function w(e){const r=new Error("报表 Worker 任务已取消");return r.name="AbortError",Object.defineProperty(r,"cause",{value:e}),r}function D(e,r){if(!e||typeof e!="object")return;const t=e;return t.protocol===u&&t.id===r?t:void 0}function q(e,r={}){const t=r.timeoutMs??12e4;if(!Number.isFinite(t)||t<=0||t>2147483647)throw new RangeError("Worker timeoutMs 应为正有限数字，且不能超过 2147483647");const o=(s,a,n,d)=>n?.aborted?Promise.reject(w(n.reason)):new Promise((I,b)=>{let g;try{g=e()}catch(c){b(c);return}const R=`mach-report-${Date.now()}-${++B}`;let y=!1,E=()=>{},k;const f=(c,i)=>{y||(y=!0,k&&clearTimeout(k),E(),n?.removeEventListener("abort",h),Promise.resolve().then(()=>g.terminate()).then(()=>c===void 0?I(i):b(c),m=>b(c??m)))},h=()=>f(w(n?.reason)),W=c=>{const i=D(c,R);if(!(!i||y)){if("type"in i&&i.type==="event"){const m="event"in i?i.event:void 0;$(m,a)?M.notifyReportTaskEvent(d,m,n):f(new Error("报表 Worker 返回无效阶段事件"));return}i.error&&typeof i.error.name=="string"&&typeof i.error.message=="string"?f(new l(i.error)):S(i.result,s)&&(s==="prepare"||"format"in i.result&&"format"in a&&i.result.format===a.format)?f(void 0,i.result):f(new Error("报表 Worker 返回无效响应"))}};try{if(E=g.subscribe(W,c=>f(c??new Error("报表 Worker 执行失败"))),y){E();return}if(n?.addEventListener("abort",h,{once:!0}),k=setTimeout(()=>f(new l({name:"ReportRuntimeError",code:"timeout",message:`报表 Worker 执行超过 ${t}ms`})),t),n?.aborted)h();else{const{onEvent:c,signal:i,...m}=a;g.postMessage({protocol:u,id:R,operation:s,input:m})}}catch(c){f(c)}});return{exportPrepared:(s,a,n)=>o("exportPrepared",s,a,n),prepare:(s,a,n)=>o("prepare",s,a,n),export:(s,a,n)=>o("export",s,a,n)}}function C(e,r={}){return q(()=>{const t=e();return{postMessage:o=>t.postMessage(o),terminate:()=>t.terminate(),subscribe:(o,s)=>{const a=d=>o(d.data),n=d=>s(d instanceof ErrorEvent?new Error(d.message):new Error("报表 Worker 消息无法解码"));return t.addEventListener("message",a),t.addEventListener("error",n),t.addEventListener("messageerror",n),()=>{t.removeEventListener("message",a),t.removeEventListener("error",n),t.removeEventListener("messageerror",n)}}}},r)}function K(e,r=globalThis){const t=o=>{v(o.data)&&z(e,o.data,s=>r.postMessage({protocol:u,id:o.data.id,type:"event",event:s})).then(s=>r.postMessage(s,_(s)))};return r.addEventListener("message",t),()=>r.removeEventListener("message",t)}exports.ReportWorkerError=l;exports.createBrowserReportExecutor=C;exports.serveReportWorker=K;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./protocol-BzwMP4Vw.cjs"),s=require("./auto-uVBjX1j5.cjs"),R=require("./encoding-BYF9ZTl9.cjs");function p(n,e=globalThis){const a=t=>{r.isReportWorkerRequest(t.data)&&r.runReportWorkerRequest(n,t.data,o=>e.postMessage({protocol:r.REPORT_WORKER_PROTOCOL,id:t.data.id,type:"event",event:o})).then(o=>e.postMessage(o,r.reportWorkerTransferList(o)))};return e.addEventListener("message",a),()=>e.removeEventListener("message",a)}exports.ReportWorkerError=r.ReportWorkerError;exports.ReportWorkerStartError=s.ReportWorkerStartError;exports.createAutoReportExporter=s.createAutoReportExporter;exports.createBrowserReportExecutor=s.createBrowserReportExecutor;exports.serveReportEncodingWorker=R.serveReportEncodingWorker;exports.serveReportWorker=p;

package/dist/worker.d.cts

@@ -77,10 +77,15 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+/** Small exports stay local; large exports use the supplied bundler/CSP-compatible Worker factory. */
+export declare function createAutoReportExporter(options?: ReportExportExecutionOptions): ReportAutoExporter;
+
 /** factory 每次返回全新 Worker，例如 () => new Worker(new URL('./worker.ts', import.meta.url), {type:'module'})。 */
 export declare function createBrowserReportExecutor(factory: () => BrowserReportWorker, options?: ReportWorkerOptions): ReportRuntimeExecutor;
 
 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 绘制。 */
@@ -104,6 +109,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;
+}
+
 declare interface PlanComponent {
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions;
@@ -181,6 +199,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";
@@ -195,8 +215,20 @@ declare interface RenderPlan {
     pages: PlanPage[];
 }
 
+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;
@@ -210,6 +242,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 {
@@ -235,6 +269,40 @@ 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;
+}
+
+export 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;
+}
+
+export declare interface ReportExportThresholds {
+    cells?: number;
+    pages?: number;
+    bytes?: number;
+}
+
+export declare type ReportLocalExport = (input: ReportRuntimePreparedExportInput) => Promise<ReportRuntimeExportResult>;
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -247,6 +315,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;
@@ -264,7 +336,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;
@@ -295,6 +367,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. */
@@ -307,10 +389,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;
     };
 }
 
@@ -331,6 +414,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;
@@ -338,6 +423,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;
@@ -378,6 +472,7 @@ export declare class ReportWorkerError extends Error {
 
 export declare interface ReportWorkerOptions {
     timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
 }
 
 export declare interface ReportWorkerScope {
@@ -386,6 +481,11 @@ export declare interface ReportWorkerScope {
     removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
 }
 
+export declare class ReportWorkerStartError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -411,6 +511,8 @@ declare interface SerializedReportError {
     diagnostics?: unknown;
 }
 
+export declare function serveReportEncodingWorker(scope?: ReportWorkerScope): () => void;
+
 /** 在 Worker 入口注册一次 runtime；返回函数可清理监听器，浏览器主线程无需引入 Node。 */
 export declare function serveReportWorker(runtime: ReportRuntime, scope?: ReportWorkerScope): () => void;
 

package/dist/worker.d.ts

@@ -77,10 +77,15 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+/** Small exports stay local; large exports use the supplied bundler/CSP-compatible Worker factory. */
+export declare function createAutoReportExporter(options?: ReportExportExecutionOptions): ReportAutoExporter;
+
 /** factory 每次返回全新 Worker，例如 () => new Worker(new URL('./worker.ts', import.meta.url), {type:'module'})。 */
 export declare function createBrowserReportExecutor(factory: () => BrowserReportWorker, options?: ReportWorkerOptions): ReportRuntimeExecutor;
 
 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 绘制。 */
@@ -104,6 +109,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;
+}
+
 declare interface PlanComponent {
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions;
@@ -181,6 +199,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";
@@ -195,8 +215,20 @@ declare interface RenderPlan {
     pages: PlanPage[];
 }
 
+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;
@@ -210,6 +242,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 {
@@ -235,6 +269,40 @@ 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;
+}
+
+export 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;
+}
+
+export declare interface ReportExportThresholds {
+    cells?: number;
+    pages?: number;
+    bytes?: number;
+}
+
+export declare type ReportLocalExport = (input: ReportRuntimePreparedExportInput) => Promise<ReportRuntimeExportResult>;
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -247,6 +315,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;
@@ -264,7 +336,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;
@@ -295,6 +367,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. */
@@ -307,10 +389,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;
     };
 }
 
@@ -331,6 +414,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;
@@ -338,6 +423,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;
@@ -378,6 +472,7 @@ export declare class ReportWorkerError extends Error {
 
 export declare interface ReportWorkerOptions {
     timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
 }
 
 export declare interface ReportWorkerScope {
@@ -386,6 +481,11 @@ export declare interface ReportWorkerScope {
     removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
 }
 
+export declare class ReportWorkerStartError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -411,6 +511,8 @@ declare interface SerializedReportError {
     diagnostics?: unknown;
 }
 
+export declare function serveReportEncodingWorker(scope?: ReportWorkerScope): () => void;
+
 /** 在 Worker 入口注册一次 runtime；返回函数可清理监听器，浏览器主线程无需引入 Node。 */
 export declare function serveReportWorker(runtime: ReportRuntime, scope?: ReportWorkerScope): () => void;
 

package/dist/worker.js

@@ -1,162 +1,18 @@
-import { n as P } from "./task-events-Dpsvf_t2.js";
-import { h as W } from "./data-explanation-C_J6jYNi.js";
-import { v as A } from "./validate-CkQBWCeg.js";
-const u = "mach-report-worker/1";
-class R extends Error {
-  constructor(r) {
-    super(r.message), this.name = r.name, this.code = r.code, this.path = r.path, this.issues = r.issues, this.diagnostics = r.diagnostics;
-  }
-}
-function p(e) {
-  return !!e && typeof e == "object" && !Array.isArray(e);
-}
-function L(e) {
-  return p(e) ? ["rows", "pages", "cells"].every((r) => typeof e[r] == "number" && Number.isSafeInteger(e[r]) && e[r] >= 0) && typeof e.durationMs == "number" && Number.isFinite(e.durationMs) && e.durationMs >= 0 : !1;
-}
-function T(e) {
-  return Array.isArray(e) && e.every((r) => p(r) && typeof r.code == "string" && typeof r.message == "string" && ["info", "warning", "error"].includes(r.severity) && W(r));
-}
-function j(e) {
-  return p(e) && Object.values(e).every((r) => p(r) && (r.revision === void 0 || typeof r.revision == "string") && (r.sourceToken === void 0 || typeof r.sourceToken == "string"));
-}
-function O(e) {
-  return e === void 0 ? !0 : p(e) && ["heuristic", "provided", "font-bytes"].includes(e.textMetrics) && (e.fontFingerprint === void 0 || typeof e.fontFingerprint == "string" && /^[a-f0-9]{64}$/.test(e.fontFingerprint));
-}
-function F(e, r) {
-  if (!p(e) || !L(e.stats) || !T(e.diagnostics) || !j(e.revisions) || !O(e.layout)) return !1;
-  if (r === "prepare") return A(e.plan).ok;
-  const t = e.format === "pdf" ? "application/pdf" : "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
-  return e.bytes instanceof Uint8Array && (e.format === "pdf" || e.format === "xlsx") && e.contentType === t;
-}
-function x(e) {
-  if (!e || typeof e != "object") return { message: String(e) };
-  const r = {};
-  for (const t of ["code", "path", "field", "message"]) {
-    const o = e[t];
-    typeof o == "string" && (r[t] = o);
-  }
-  return r;
-}
-function N(e) {
-  const r = x(e);
-  if (!p(e)) return r;
-  for (const t of ["format", "severity", "kind", "nid"]) typeof e[t] == "string" && (r[t] = e[t]);
-  for (const t of ["pageIndex", "componentIndex"]) Number.isSafeInteger(e[t]) && e[t] >= 0 && (r[t] = e[t]);
-  return Array.isArray(e.componentPath) && e.componentPath.every((t) => Number.isSafeInteger(t) && t >= 0) && (r.componentPath = e.componentPath), r;
-}
-function S(e) {
-  if (!(e instanceof Error)) return { name: "Error", message: String(e) };
-  const r = e;
-  return {
-    name: e.name,
-    message: e.message,
-    ...typeof r.code == "string" ? { code: r.code } : {},
-    ...typeof r.path == "string" ? { path: r.path } : {},
-    ...Array.isArray(r.issues) ? { issues: r.issues.map(x) } : {},
-    ...Array.isArray(r.diagnostics) ? { diagnostics: r.diagnostics.map(N) } : {}
-  };
-}
-function z(e) {
-  if (!e || typeof e != "object") return !1;
-  const r = e;
-  return r.protocol === u && typeof r.id == "string" && (r.operation === "prepare" || r.operation === "export" || r.operation === "exportPrepared") && !!r.input && typeof r.input == "object";
-}
-async function _(e, r, t) {
-  try {
-    const o = r.operation === "prepare" ? await e.prepare({ ...r.input, onEvent: t }) : r.operation === "exportPrepared" ? await e.exportPrepared({ ...r.input, onEvent: t }) : await e.export({ ...r.input, onEvent: t });
-    return { protocol: u, id: r.id, result: o };
-  } catch (o) {
-    return { protocol: u, id: r.id, error: S(o) };
-  }
-}
-function $(e) {
-  const r = e.result;
-  return !r || !("bytes" in r) || !(r.bytes.buffer instanceof ArrayBuffer) ? [] : [r.bytes.buffer];
-}
-function D(e, r) {
-  if (!p(e) || typeof e.taskId != "string" || !e.taskId || r.taskId !== void 0 && e.taskId !== r.taskId || e.correlationId !== r.correlationId || e.reportId !== void 0 && (typeof e.reportId != "string" || !("reportIds" in r && r.reportIds.includes(e.reportId))) || !["query", "validate", "layout", "assets", "encode"].includes(e.stage) || !["started", "completed", "failed"].includes(e.status)) return !1;
-  for (const t of ["completed", "total"]) if (e[t] !== void 0 && (typeof e[t] != "number" || !Number.isFinite(e[t]) || e[t] < 0)) return !1;
-  return e.completed === void 0 || e.total === void 0 || e.completed <= e.total;
-}
-let v = 0;
-function w(e) {
-  const r = new Error("报表 Worker 任务已取消");
-  return r.name = "AbortError", Object.defineProperty(r, "cause", { value: e }), r;
-}
-function B(e, r) {
-  if (!e || typeof e != "object") return;
-  const t = e;
-  return t.protocol === u && t.id === r ? t : void 0;
-}
-function C(e, r = {}) {
-  const t = r.timeoutMs ?? 12e4;
-  if (!Number.isFinite(t) || t <= 0 || t > 2147483647) throw new RangeError("Worker timeoutMs 应为正有限数字，且不能超过 2147483647");
-  const o = (s, a, n, d) => n?.aborted ? Promise.reject(w(n.reason)) : new Promise((I, b) => {
-    let g;
-    try {
-      g = e();
-    } catch (c) {
-      b(c);
-      return;
-    }
-    const l = `mach-report-${Date.now()}-${++v}`;
-    let y = !1, E = () => {
-    }, h;
-    const f = (c, i) => {
-      y || (y = !0, h && clearTimeout(h), E(), n?.removeEventListener("abort", k), Promise.resolve().then(() => g.terminate()).then(
-        () => c === void 0 ? I(i) : b(c),
-        (m) => b(c ?? m)
-      ));
-    }, k = () => f(w(n?.reason)), M = (c) => {
-      const i = B(c, l);
-      if (!(!i || y)) {
-        if ("type" in i && i.type === "event") {
-          const m = "event" in i ? i.event : void 0;
-          D(m, a) ? P(d, m, n) : f(new Error("报表 Worker 返回无效阶段事件"));
-          return;
-        }
-        i.error && typeof i.error.name == "string" && typeof i.error.message == "string" ? f(new R(i.error)) : F(i.result, s) && (s === "prepare" || "format" in i.result && "format" in a && i.result.format === a.format) ? f(void 0, i.result) : f(new Error("报表 Worker 返回无效响应"));
-      }
-    };
-    try {
-      if (E = g.subscribe(M, (c) => f(c ?? new Error("报表 Worker 执行失败"))), y) {
-        E();
-        return;
-      }
-      if (n?.addEventListener("abort", k, { once: !0 }), h = setTimeout(() => f(new R({ name: "ReportRuntimeError", code: "timeout", message: `报表 Worker 执行超过 ${t}ms` })), t), n?.aborted) k();
-      else {
-        const { onEvent: c, signal: i, ...m } = a;
-        g.postMessage({ protocol: u, id: l, operation: s, input: m });
-      }
-    } catch (c) {
-      f(c);
-    }
-  });
-  return { exportPrepared: (s, a, n) => o("exportPrepared", s, a, n), prepare: (s, a, n) => o("prepare", s, a, n), export: (s, a, n) => o("export", s, a, n) };
-}
-function G(e, r = {}) {
-  return C(() => {
-    const t = e();
-    return {
-      postMessage: (o) => t.postMessage(o),
-      terminate: () => t.terminate(),
-      subscribe: (o, s) => {
-        const a = (d) => o(d.data), n = (d) => s(d instanceof ErrorEvent ? new Error(d.message) : new Error("报表 Worker 消息无法解码"));
-        return t.addEventListener("message", a), t.addEventListener("error", n), t.addEventListener("messageerror", n), () => {
-          t.removeEventListener("message", a), t.removeEventListener("error", n), t.removeEventListener("messageerror", n);
-        };
-      }
-    };
-  }, r);
-}
-function H(e, r = globalThis) {
+import { i as a, r as R, R as p, a as n } from "./protocol-kt4Iy6-3.js";
+import { b as W } from "./protocol-kt4Iy6-3.js";
+import { R as g, c as k, a as u } from "./auto-YR7a4BtF.js";
+import { s as x } from "./encoding-BOGq4qYL.js";
+function d(s, r = globalThis) {
   const t = (o) => {
-    z(o.data) && _(e, o.data, (s) => r.postMessage({ protocol: u, id: o.data.id, type: "event", event: s })).then((s) => r.postMessage(s, $(s)));
+    a(o.data) && R(s, o.data, (e) => r.postMessage({ protocol: p, id: o.data.id, type: "event", event: e })).then((e) => r.postMessage(e, n(e)));
   };
   return r.addEventListener("message", t), () => r.removeEventListener("message", t);
 }
 export {
-  R as ReportWorkerError,
-  G as createBrowserReportExecutor,
-  H as serveReportWorker
+  W as ReportWorkerError,
+  g as ReportWorkerStartError,
+  k as createAutoReportExporter,
+  u as createBrowserReportExecutor,
+  x as serveReportEncodingWorker,
+  d as serveReportWorker
 };