@agile-team/mach-report 2.21.1 → 2.23.0

package/dist/{workbook-session-oinxX3qo.js → workbook-session-C9ZmCBwY.js}

@@ -1,7 +1,6 @@
-import { b as ve, w as Ke, o as He, f as er } from "./progress-Hc2vxoCs.js";
-import { c as Kt, g as gr } from "./_commonjsHelpers-DaMA6jEr.js";
-import { R as yr } from "./component-tree-1_QCiQJX.js";
-import { o as Ze, s as cr, r as vr, t as Ge, u as wr, w as _r, x as xr, y as Sr, q as kr } from "./region-binding-workflow-Cy4GIOUo.js";
+import { v as ve, w as Ke, o as He, R as gr, z as er } from "./progress-ByiOxUD3.js";
+import { c as Kt, g as yr } from "./_commonjsHelpers-DaMA6jEr.js";
+import { o as Ze, s as cr, r as vr, t as Ge, u as wr, w as _r, x as xr, y as Sr, q as kr } from "./region-binding-workflow-DjrXuR1q.js";
 import { c as Cr } from "./media-Y90dHK9z.js";
 import { f as Er } from "./number-format-BA_KwrZe.js";
 function $e(G) {
@@ -22573,11 +22572,11 @@ use chrome, FireFox or Internet Explorer 11`);
   })(qe)), qe.exports;
 }
 var Tr = Mr();
-const Ar = /* @__PURE__ */ gr(Tr), hr = 25.4 / 96;
+const Ar = /* @__PURE__ */ yr(Tr), hr = 25.4 / 96;
 function Rr(G) {
   return (G < 1 ? G * 12 : G * 7 + 5) * hr;
 }
-function Sn(G) {
+function xn(G) {
   const tt = G / hr;
   return tt < 12 ? tt / 12 : (tt - 5) / 7;
 }
@@ -22641,7 +22640,7 @@ function Nr(G, tt, s, C, _, d) {
     return l;
   };
 }
-function kn(G, tt) {
+function Sn(G, tt) {
   const s = G.meta?.xlsxOverlay;
   if (s === void 0) return;
   if (!s || typeof s != "object") throw new Error("Excel 图片定位元数据无效");
@@ -23179,11 +23178,11 @@ function mr(G, tt, s) {
   });
   return ve(tt.signal), { sheets: C, warnings: s.result() };
 }
-async function Cn(G, tt = {}) {
+async function kn(G, tt = {}) {
   const s = new Ve(), { workbook: C } = await Je(G, tt, s);
   return mr(C, tt, s);
 }
-async function En(G, tt = {}) {
+async function Cn(G, tt = {}) {
   const s = new Ve(), { workbook: C, resolved: _ } = await Je(G, tt, s);
   return br(C, tt, _, s);
 }
@@ -23192,7 +23191,7 @@ async function br(G, tt, s, C) {
   ve(tt.signal);
   const d = un(G, tt);
   if (!d.length) throw new Error("Excel 中没有可导入的可见工作表；可通过 sheets 显式选择隐藏工作表");
-  const o = { schemaVersion: yr, pages: [] }, a = [];
+  const o = { schemaVersion: gr, pages: [] }, a = [];
   let r = s.limits.maxCells;
   for (const t of d) {
     const e = cr(t, pr(tt, t.name));
@@ -23242,17 +23241,17 @@ function bn(G) {
   const tt = new Ve();
   return G.result().forEach((s) => tt.add(s)), tt;
 }
-const Mn = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+const En = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   openExcelWorkbook: mn
 }, Symbol.toStringTag, { value: "Module" }));
 export {
   Ar as E,
-  En as a,
-  Cn as b,
+  Cn as a,
+  kn as b,
   Rr as e,
-  kn as i,
-  Sn as m,
+  Sn as i,
+  xn as m,
   mn as o,
-  Mn as w
+  En as w
 };

package/dist/workbook-sheets-CaPAulQ6.cjs

@@ -0,0 +1,2 @@
+"use strict";function y(r){if(typeof r!="string"||!r.trim()||r.length>31||/[\\/*?:[\]]/.test(r)||/^'|'$/.test(r))throw new TypeError("工作表名称无效");return r}function c(r){if(r!==void 0){if(!Array.isArray(r)||r.length>1e4)throw new RangeError("工作表名称列表最多 10000 项");return Array.from(r,y)}}function g(r){if(!Array.isArray(r)||r.length>16384)throw new TypeError("附加工作表行应为最多 16384 列的标量数组");return Array.from(r,n=>{if(n===null||typeof n=="boolean"||typeof n=="number"&&Number.isFinite(n)||typeof n=="string"&&n.length<=32767&&n.split(`
+`).length<=254)return n;throw new TypeError("附加工作表仅接受 Excel 范围内的文本、有限数值、布尔或空值")})}function A(r){if(r===void 0)return;if(!Array.isArray(r)||r.length>100)throw new RangeError("附加工作表最多 100 张");let n=0,i=0,f=0;const a=new Set;return Array.from(r,o=>{if(!o)throw new TypeError("附加工作表声明无效");const w=y(o.name).toLowerCase();if(a.has(w))throw new TypeError(`附加工作表名称重复 ${o.name}`);if(a.add(w),!Array.isArray(o.rows)||o.rows.length>1e5)throw new RangeError("附加工作表最多 100000 行");if(f+=o.rows.length,f>1e5)throw new RangeError("附加工作表总行数超过 100000");const m=Array.from(o.rows,t=>{const s=g(t);if(n+=s.length,n>1e5)throw new RangeError("附加工作表总单元格超过 100000");for(const h of s)typeof h=="string"&&(i+=h.length);if(i>4e6)throw new RangeError("附加工作表文本超过 4000000 字符");return s}),e=o.columnWidths;if(e&&(!Array.isArray(e)||e.length>16384||Array.from(e).some(t=>!Number.isFinite(t)||t<=0||t>255)))throw new RangeError("附加工作表列宽应在 0 到 255 之间");return{name:o.name,rows:m,...e?{columnWidths:[...e]}:{}}})}exports.snapshotAdditionalSheets=A;exports.snapshotSheetNames=c;

package/dist/workbook-sheets-D4M7XXBh.js

@@ -0,0 +1,44 @@
+function h(r) {
+  if (typeof r != "string" || !r.trim() || r.length > 31 || /[\\/*?:[\]]/.test(r) || /^'|'$/.test(r)) throw new TypeError("工作表名称无效");
+  return r;
+}
+function A(r) {
+  if (r !== void 0) {
+    if (!Array.isArray(r) || r.length > 1e4) throw new RangeError("工作表名称列表最多 10000 项");
+    return Array.from(r, h);
+  }
+}
+function m(r) {
+  if (!Array.isArray(r) || r.length > 16384) throw new TypeError("附加工作表行应为最多 16384 列的标量数组");
+  return Array.from(r, (n) => {
+    if (n === null || typeof n == "boolean" || typeof n == "number" && Number.isFinite(n) || typeof n == "string" && n.length <= 32767 && n.split(`
+`).length <= 254) return n;
+    throw new TypeError("附加工作表仅接受 Excel 范围内的文本、有限数值、布尔或空值");
+  });
+}
+function E(r) {
+  if (r === void 0) return;
+  if (!Array.isArray(r) || r.length > 100) throw new RangeError("附加工作表最多 100 张");
+  let n = 0, i = 0, f = 0;
+  const a = /* @__PURE__ */ new Set();
+  return Array.from(r, (o) => {
+    if (!o) throw new TypeError("附加工作表声明无效");
+    const w = h(o.name).toLowerCase();
+    if (a.has(w)) throw new TypeError(`附加工作表名称重复 ${o.name}`);
+    if (a.add(w), !Array.isArray(o.rows) || o.rows.length > 1e5) throw new RangeError("附加工作表最多 100000 行");
+    if (f += o.rows.length, f > 1e5) throw new RangeError("附加工作表总行数超过 100000");
+    const g = Array.from(o.rows, (t) => {
+      const s = m(t);
+      if (n += s.length, n > 1e5) throw new RangeError("附加工作表总单元格超过 100000");
+      for (const y of s) typeof y == "string" && (i += y.length);
+      if (i > 4e6) throw new RangeError("附加工作表文本超过 4000000 字符");
+      return s;
+    }), e = o.columnWidths;
+    if (e && (!Array.isArray(e) || e.length > 16384 || Array.from(e).some((t) => !Number.isFinite(t) || t <= 0 || t > 255))) throw new RangeError("附加工作表列宽应在 0 到 255 之间");
+    return { name: o.name, rows: g, ...e ? { columnWidths: [...e] } : {} };
+  });
+}
+export {
+  A as a,
+  E as s
+};

package/dist/worker.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./protocol-C8VWF9An.cjs"),s=require("./auto-Tq7ReIC1.cjs"),R=require("./encoding-B79hW4zq.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;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./protocol-B9YgfQ_d.cjs"),s=require("./auto-4pK9HePf.cjs"),R=require("./encoding-BefcaHdp.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

@@ -462,6 +462,8 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
         paperSize?: "auto" | "a3" | "a4" | "a5";
         maxDataBars?: number;
         sheetName?: (sheetIndex: number) => string;
+        sheetNames?: readonly string[];
+        additionalSheets?: readonly XlsxAdditionalSheet[];
     };
 }
 
@@ -587,4 +589,11 @@ export declare function serveReportWorker(runtime: ReportRuntime, scope?: Report
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;
 
+/** 可序列化的附加工作表在编码前写入，浏览器与 Worker 共用同一声明。 */
+declare interface XlsxAdditionalSheet {
+    name: string;
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+    columnWidths?: readonly number[];
+}
+
 export { }

package/dist/worker.d.ts

@@ -462,6 +462,8 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
         paperSize?: "auto" | "a3" | "a4" | "a5";
         maxDataBars?: number;
         sheetName?: (sheetIndex: number) => string;
+        sheetNames?: readonly string[];
+        additionalSheets?: readonly XlsxAdditionalSheet[];
     };
 }
 
@@ -587,4 +589,11 @@ export declare function serveReportWorker(runtime: ReportRuntime, scope?: Report
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;
 
+/** 可序列化的附加工作表在编码前写入，浏览器与 Worker 共用同一声明。 */
+declare interface XlsxAdditionalSheet {
+    name: string;
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+    columnWidths?: readonly number[];
+}
+
 export { }

package/dist/worker.js

@@ -1,7 +1,7 @@
-import { i as a, r as R, R as p, a as n } from "./protocol-Bs9-ohHN.js";
-import { b as W } from "./protocol-Bs9-ohHN.js";
-import { R as g, c as k, a as u } from "./auto-BkdGiNtr.js";
-import { s as x } from "./encoding-BSeUwrN7.js";
+import { i as a, r as R, R as p, a as n } from "./protocol-DxeUKGYG.js";
+import { b as W } from "./protocol-DxeUKGYG.js";
+import { R as g, c as k, a as u } from "./auto-CTIJ6PnR.js";
+import { s as x } from "./encoding-CL6rXEkR.js";
 function d(s, r = globalThis) {
   const t = (o) => {
     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)));

package/dist/xlsx.cjs

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const M=require("./progress-B0ctFpKf.cjs"),N=require("./index-CUNw7dL9.cjs"),L=require("./data-bar-YltqGTaC.cjs"),x=require("./grid-geometry-D8ReblRV.cjs"),p=require("./workbook-session-NYv01LHe.cjs"),C=require("./component-tree-BjZIp6w9.cjs"),G=require("./media-B7vnpD8k.cjs"),R=require("./assets-vbjAGgk8.cjs"),m=require("./region-binding-workflow-JNowHd0A.cjs");function j(e){const t=N.encodePng({width:1,height:1,channels:4,depth:8,data:new Uint8Array([1,3,5].map(o=>parseInt(e.slice(o,o+2),16)).concat(89))});return`data:image/png;base64,${btoa(String.fromCharCode(...t))}`}function H(e,t,o){const n=new Map;let r=0;return(a,i,s,l)=>{const c=L.dataBarBox(i.cell.dataBar,i.widthMm,i.heightMm,l);if(!c)return;if(++r>t)throw new Error(`Excel 数据条超过 ${t} 个绘图预算，请缩小范围或调整 maxDataBars`);let d=n.get(c.color);d||(d=j(c.color),n.set(c.color,d)),r===1&&o.push("数据条为静态半透明视觉快照，保留原始单元格值；Excel 编辑不会重算条形，绘图叠加文字的混色与预览可能略有差异。"),e.write(a,{kind:"image",leftMm:0,topMm:0,widthMm:c.width,heightMm:c.height,imageData:d},s,{leftMm:i.xMm+c.x,offsetMm:c.y})}}async function q(e,t,o){const n=e.pages.flatMap(i=>i.components),r=M.createOutputScheduler(o);let a=0;for(;n.length;){const i=n.pop();for(const s of i.grid?.cells??[])for(const l of s){if(l?.dataBar&&l.dataBar.end>l.dataBar.start&&++a>t)throw new Error(`Excel 数据条超过 ${t} 个绘图预算，请缩小范围或调整 maxDataBars`);l?.children&&n.push(...l.children);const c=r();c&&await c}}}function A(e,t){return{richText:e.flatMap((o,n)=>[...n?[{text:`
-`}]:[],...o.segments.map(r=>{const a=x.mergeComponentStyles(t,r.style),i=a.color?.replace(/^#/,"");return{text:r.kind==="field"?r.field??"":r.text??"",font:{name:a.fontFamily,bold:a.bold,italic:a.italic,underline:a.underline,size:x.resolveFontSize(a).fontSizePt,.../^[a-f\d]{6}$/i.test(i??"")?{color:{argb:`FF${i.toUpperCase()}`}}:{}}}})])}}function _(e,t){const o=e.children?.filter(a=>a.kind==="text"&&!a.grid)??[];if(!e.richParagraphs?.length&&!o.length)return;const n=x.mergeComponentStyles(t,e.style),r=e.richParagraphs?.length?[...e.richParagraphs]:e.text?[{segments:[{text:e.text}]}]:[];for(const a of o){const i=x.mergeComponentStyles(n,a.style),s=a.richParagraphs?.length?a.richParagraphs:[{segments:[{text:a.lines?.join(`
-`)??a.text??""}]}];for(const l of s)r.push({...l,segments:l.segments.map(c=>({...c,style:x.mergeComponentStyles(i,c.style)}))})}return A(r,n)}function U(e,t,o){let n=o*72/25.4;if(!Number.isFinite(n)||t+Math.ceil(n/409)-1>1048576)throw new Error("Excel 图片占位超过工作表行数上限");for(;n>0;){if(t>1048576)throw new Error("Excel 图片占位超过工作表行数上限");const r=Math.min(409,n);e.getRow(t++).height=r,n-=r}return t}function X(e,t,o){let n=Math.round(t*36e3),r=0;if(!Number.isSafeInteger(n))throw new Error("Excel 图片锚点超出安全坐标范围");for(e.properties.defaultColWidth??=8.43;r<16384;){const a=e.getColumn(r+1).width??e.properties.defaultColWidth,i=Math.round(p.excelColumnWidthToMm(a)*36e3);if(!Number.isSafeInteger(i)||i<=0)throw new Error("Excel 图片锚点所在列宽无效");if(n<i)return{col:r+n/i,row:o-1,nativeCol:r,nativeColOff:n,nativeRow:o-1,nativeRowOff:0};n-=i,r++}throw new Error("Excel 图片锚点超过16384列上限")}function K(e,t,o){let n=o*72/25.4;if(!Number.isFinite(n)||Math.abs(n)>1048576*409)throw new Error("Excel 图片纵向偏移超过工作表范围");const r=a=>{const i=e.getRow(a).height??e.properties.defaultRowHeight??15;if(!Number.isFinite(i)||i<=0)throw new Error("Excel 图片锚点所在行高无效");return i};for(;n<0&&t>1;)n+=r(--t);for(;t<=1048576&&n>=r(t);)n-=r(t++);if(t>1048576||n<0)throw new Error("Excel 图片移动到工作表边界之外");return{nativeRow:t-1,nativeRowOff:Math.round(n*25.4/72*36e3)}}function J(e,t,o){const n=G.createImageMediaInspector(t),r=new Map;return{write(a,i,s,l){if(![i.widthMm,i.heightMm,i.leftMm].every(Number.isFinite)||i.widthMm<0||i.heightMm<0||i.leftMm<0)throw new Error("Excel 图片尺寸无效");if(!i.widthMm||!i.heightMm)return s;if(!i.imageData||!/^data:image\/(png|jpe?g);base64,/i.test(i.imageData))return o.push(`${i.nid??i.kind}: Excel 图片仅支持 PNG/JPEG data URI，已跳过`),s;const c=n(i.imageData);let d=r.get(c.dataUrl);d===void 0&&(d=e.addImage({base64:c.dataUrl,extension:c.extension}),r.set(c.dataUrl,d));const h=l?s:U(a,s,i.heightMm);return a.addImage(d,{tl:{...X(a,l?.leftMm??i.leftMm,s),...l?K(a,s,l.offsetMm):{}},ext:{width:i.widthMm*96/25.4,height:i.heightMm*96/25.4},editAs:"oneCell"}),h}}}function T(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function W(e,t){const o=e.meta?.xlsxFlow;if(o===void 0)return;if(!T(o)||o.version!=="1.0"||!Number.isSafeInteger(o.columnStart)||Number(o.columnStart)<0)throw new Error("Excel 多区域几何标记无效，不能按列序猜测输出");if(!e.grid)throw new Error("Excel 多区域输出只接受显式网格组件");const n=o,r=e.grid.colWidthsMm;if(!r?.length||n.columnStart+r.length>t.length||r.some((a,i)=>Math.abs(a-t[n.columnStart+i])>.001))throw new Error("Excel 多区域列位置与网格列宽不一致");return n}function F(e){const t=e.meta?.xlsxFlow;if(t===void 0){if(e.components.some(n=>n.meta?.xlsxFlow!==void 0))throw new Error("Excel 多区域页面缺少完整列几何标记");return}const o=V(t,e.meta?.reportScope);for(const n of e.components){const r=W(n,o.widths);if(!r)throw new Error("Excel 多区域页面混入没有区域几何的组件，请使用独立页面模板");const a=o.widths.slice(0,r.columnStart).reduce((s,l)=>s+l,e.marginLeftMm??0),i=n.grid.colWidthsMm.reduce((s,l)=>s+l,0);if(Math.abs(a-n.leftMm)>.01||Math.abs(i-n.widthMm)>.01)throw new Error("Excel 多区域标记与真实横向位置不一致")}return o}function V(e,t){if(!T(e)||e.version!=="1.0"||typeof e.sheet!="string"||!e.sheet.trim()||typeof e.templateId!="string"||!e.templateId.trim())throw new Error("Excel 多区域工作表标识无效");if(!Array.isArray(e.fullWidthsMm)||!e.fullWidthsMm.length||e.fullWidthsMm.length>16384||e.fullWidthsMm.some(o=>typeof o!="number"||!Number.isFinite(o)||o<=0||o>2e3))throw new Error("Excel 多区域完整列宽无效");if(t!==void 0&&(typeof t!="string"||!t.trim()))throw new Error("Excel 多区域报表命名空间无效");return{key:JSON.stringify([t??e.templateId,e.sheet]),sheet:e.sheet,widths:e.fullWidthsMm}}function v(e){return Math.round(e*1e6)/1e6}function Q(e,t,o,n,r){return e.components.filter(a=>n?a.pageAnchor==="header"?t===0:a.pageAnchor==="footer"?t===o-1:a.table?.role!=="header"?!0:r.has(a.table.id)?!1:(r.add(a.table.id),!0):!0)}function Y(e,t,o,n){const r=e.components.filter(i=>!t.includes(i)&&i.table?.role==="header"),a=t.filter(i=>!i.pageAnchor).reduce((i,s)=>Math.max(i,s.topMm+s.heightMm),e.marginTopMm??0);return t.map(i=>{let s=i.topMm;return o&&i.pageAnchor==="footer"&&(s=a),s-=r.filter(l=>l.topMm+l.heightMm<=s+.001).reduce((l,c)=>l+c.heightMm,0),{component:i,layout:x.resolveGridLayout(i.grid,i.widthMm,i.heightMm),top:s,column:W(i,n).columnStart}})}function Z(e,t,o){const n=t.length-1;if(n*o.length>1e6)throw new Error("Excel 多区域单页超过 100 万几何单元格，请减小预览分页高度或列数");const r=new Map(t.map((s,l)=>[s,l])),a=new Map,i=new Map;for(const s of e)for(const l of s.layout.cells){if(!Object.keys(l.cell).length)continue;const c=r.get(v(s.top+l.yMm)),d=r.get(v(s.top+l.yMm+l.heightMm)),h=s.column+l.ci,u=h+(l.cell.colSpan??1),g=`${c}:${h}`;for(let f=c;f<d;f++)for(let w=h;w<u;w++){const b=`${f}:${w}`;if(i.has(b))throw new Error("Excel 多区域实际单元格互相覆盖，已终止输出，未覆盖已有内容");i.set(b,g)}a.set(g,{...l.cell,style:x.mergeComponentStyles(s.component.style,l.cell.style),rowSpan:d-c,colSpan:u-h})}return Array.from({length:n},(s,l)=>{const c=[];for(let d=0;d<o.length;d++){const h=`${l}:${d}`,u=a.get(h);u?(c.push(u),d+=(u.colSpan??1)-1):i.has(h)||c.push(null)}return c})}function ee(e,t){const o=new Set,n=[];let r;for(const[a,{page:i}]of e.entries()){const s=F(i);if(r&&(s.key!==r.key||s.widths.length!==r.widths.length||s.widths.some((g,f)=>Math.abs(g-r.widths[f])>.001)))throw new Error("Excel 多区域分页的工作表或列结构不一致");r??=s;const l=Q(i,a,e.length,t,o),c=Y(i,l,t,s.widths);if(!c.length)continue;const d=[...new Set(c.flatMap(g=>[...g.layout.rows.map(f=>v(g.top+f.pos)),v(g.top+g.component.heightMm)]))].sort((g,f)=>g-f),h=Z(c,d,s.widths),u=d.slice(1).map((g,f)=>g-d[f]);n.push({kind:"rect",leftMm:0,topMm:0,widthMm:s.widths.reduce((g,f)=>g+f,0),heightMm:u.reduce((g,f)=>g+f,0),grid:{cells:h,colWidthsMm:s.widths,rowHeightsMm:u}})}return n}const P=72/25.4,te=32767,ne=253;function E(e,t){if(typeof e!="string")return;if(e.length>te)throw new Error(`Excel 单元格 ${t} 最多支持 32767 个字符，无法无损导出；内容未裁剪`);let o=0;for(let n=0;n<e.length;n++)if(e.charCodeAt(n)===10&&++o>ne)throw new Error(`Excel 单元格 ${t} 最多支持 253 个换行，无法无损导出；内容未改写`)}function y(e){if(!e)return;const t=e.replace("#","");return/^[0-9a-fA-F]{6}$/.test(t)?`FF${t.toUpperCase()}`:void 0}function I(e,t={}){e.font={name:t.fontFamily,bold:t.bold===!0,italic:t.italic===!0,underline:t.underline===!0,size:x.resolveFontSize(t).fontSizePt,color:y(t.color)?{argb:y(t.color)}:void 0}}const S={a3:{width:297,height:420,code:8},a4:{width:210,height:297,code:9},a5:{width:148,height:210,code:11}};function ie(e,t,o,n){if(t&&t!=="auto")return S[t].code;const r=Math.min(e.pageWidthMm,e.pageHeightMm),a=Math.max(e.pageWidthMm,e.pageHeightMm),i=Object.values(S).find(s=>Math.abs(r-s.width)<=1&&Math.abs(a-s.height)<=1);return i?i.code:(n.push(`page ${o+1}: 自定义纸张 ${e.pageWidthMm}×${e.pageHeightMm}mm 无对应 Excel 纸型，打印设置回退 A4；可显式配置 paperSize`),S.a4.code)}function re(e,t,o,n){const r=typeof t.text=="string"?t.text:"";if(o!=="raw"||!Object.prototype.hasOwnProperty.call(t,"value")){E(r,e.address),e.value=r;return}const a=t.value;if(a===null||typeof a=="string"||typeof a=="boolean"||typeof a=="number"&&Number.isFinite(a)){E(a,e.address),e.value=a,t.numberFormat&&(e.numFmt=t.numberFormat);return}E(r,e.address),e.value=r,n.push(`原始单元格值无效，已保留显示文本：${e.address}`)}function oe(e){const t=F(e);return t?{id:`xlsx-flow:${t.key}`,title:t.sheet,wide:!0,flow:!0}:ae(e)}function ae(e){const o=e.components.filter(n=>n.table!==void 0)[0]?.table;if(!(!o||typeof o.id!="string"||!o.id.trim()||!Array.isArray(o.columnKeys)||!o.columnKeys.length)){for(const n of e.components){if(n.table){if(!n.grid||n.table.id!==o.id)return;continue}if(n.grid||n.kind!=="text"&&!C.isImageBackedComponent(n))return}return{id:o.id,title:o.title,wide:o.layout==="wide"||e.layout==="wide"}}}function se(e,t){const o=new Set;for(const[n,r]of e.pages.entries())if(!t[n])for(const a of r.components)typeof a.table?.id=="string"&&o.add(a.table.id);return o}function B(e){return e.layout==="wide"||e.components.some(t=>t.table?.layout==="wide")}function le(e,t,o){const n=[],r=e.pages.map(oe),a=se(e,r);for(const[i,s]of e.pages.entries()){const l=r[i],c=l&&!a.has(l.id),d=t==="pages"||!c?void 0:l;if(t==="continuous"&&!d)throw new Error(`page ${i+1}: continuous Excel 需要完整、单一的逻辑表来源；自由布局请使用 sheetMode: 'pages'`);const h=d!==void 0&&(t==="continuous"||d.wide);!h&&t!=="pages"&&B(s)&&o.push(`page ${i+1}: 混合或缺少逻辑表来源，已保留独立 Sheet，未猜测合并内容`);const u=n[n.length-1];h&&u?.continuous&&u.tableId===d.id?u.pages.push({page:s,index:i}):n.push({pages:[{page:s,index:i}],continuous:h,...h?{tableId:d.id,title:d.title}:{},...l?.flow?{flow:!0,title:l.title}:{}})}return n}function $(e,t,o){return!e||e.length===t.length&&e.every((n,r)=>o(n,t[r]))}function ce(e,t,o,n){const r=e.table,a=t.columns.map(l=>l.size),i=$(n.keys,r.columnKeys,(l,c)=>l===c),s=$(n.widths,a,(l,c)=>Math.abs(l-c)<=.001);if(r.columnKeys.length!==a.length||!i||!s)throw new Error(`page ${o+1}: 连续 Excel 逻辑表 ${r.id} 的列结构或列宽不一致`);if(n.keys??=r.columnKeys,n.widths??=a,r.role==="header"){if(r.rowIndex!==-1)throw new Error(`page ${o+1}: 连续 Excel 表头 rowIndex 必须为 -1`);n.headerSeen=!0}else{if(!["body","group-header","subtotal","grand-total"].includes(r.role)||r.rowIndex!==n.expectedRow)throw new Error(`page ${o+1}: 连续 Excel 逻辑行来源不连续或重复（期望 ${n.expectedRow}）`);n.expectedRow+=t.rows.length}}function de(e,t){const o={expectedRow:0,headerSeen:!1};for(const{page:n,index:r}of e.pages)for(const a of n.components){const i=t.get(a);a.table&&i&&ce(a,i,r,o)}if(!o.headerSeen)throw new Error("连续 Excel 逻辑表缺少明确表头来源")}function he(e,t,o){let n=(e?.replace(/[\\/*?:[\]]/g," ").replace(/\s+/g," ").trim()||`Sheet${t+1}`).slice(0,31).replace(/^'+|'+$/g,"").trim()||`Sheet${t+1}`;n.toLowerCase()==="history"&&(n+=" 报表");let r=n,a=1;for(;o.has(r.toLowerCase());){const i=` (${++a})`;r=n.slice(0,31-i.length)+i}return o.add(r.toLowerCase()),r}function ge(e){const t=new Set;function o(n,r,a,i){return n<=r?n:(t.has(a)||(e.push(i),t.add(a)),r)}return{column:n=>o(n,255,"column","Excel 单列宽度上限为 255 字符，超宽列已收敛至 255；单元格值完整保留，显示范围可能受限"),row:n=>o(n,409,"row","Excel 行高上限为 409pt，超高行已收敛至 409pt；单元格值完整保留，显示范围可能受限")}}async function fe(e,t){const o=e.flow?ee(e.pages,e.continuous).map(i=>({comp:i,pageIndex:e.pages[0].index})):e.pages.flatMap(({page:i,index:s},l)=>i.components.filter(c=>!e.continuous||(c.pageAnchor!=="header"||l===0)&&(c.pageAnchor!=="footer"||l===e.pages.length-1)).map(c=>({comp:c,pageIndex:s}))),n=new Map;let r=1,a=0;for(const{comp:i}of o)if(i.grid){const s=x.resolveGridLayout(i.grid,i.widthMm,i.heightMm);n.set(i,s),r=Math.max(r,s.columns.length);const l=t(s.cells.length);l&&await l}else i.kind==="text"&&(a=Math.max(a,i.widthMm));if(r>16384)throw new Error("Excel 最多支持 16384 列，无法无损导出此报表");return{components:o,grids:n,columnCount:r,textWidthMm:a}}function ue(e,t,o){const{page:n,index:r}=e.pages[0],a=t!==void 0&&t!=="auto";return(e.continuous||B(n))&&!a?{}:{pageSetup:{paperSize:ie(n,t,r,o),orientation:n.pageWidthMm>n.pageHeightMm?"landscape":"portrait",fitToPage:!0,...e.continuous?{fitToWidth:1,fitToHeight:0}:{}}}}function me(e){const t=y(e.borderColor??e.lineColor),o={style:"thin",...t?{color:{argb:t}}:{}};return{...e.borderTop!==!1?{top:o}:{},...e.borderLeft!==!1?{left:o}:{},...e.borderBottom!==!1?{bottom:o}:{},...e.borderRight!==!1?{right:o}:{}}}function we(e,t){e.alignment={horizontal:t.align??"left",vertical:t.verticalAlign??"middle",wrapText:!0};const o=y(t.backgroundColor);o&&(e.fill={type:"pattern",pattern:"solid",fgColor:{argb:o}}),e.border=me(t),I(e,t)}function xe(e,t){for(const[o,n]of t.columns.entries()){const r=e.sheet.getColumn(o+1),a=e.limits.column(p.mmToExcelColumnWidth(n.size));(r.width==null||r.width<a)&&(r.width=a)}}function pe(e,t,o){for(const[n,r]of t.rows.entries()){const a=e.sheet.getRow(o+n),i=e.limits.row(r.size*P);(a.height==null||a.height<i)&&(a.height=i)}}function Me(e,t,o,n){const r=Math.max(1,Math.min(t.cell.colSpan??1,o.columns.length-t.ci)),a=Math.max(1,Math.min(t.cell.rowSpan??1,o.rows.length-t.ri));(r>1||a>1)&&e.mergeCells(n+t.ri,t.ci+1,n+t.ri+a-1,t.ci+r)}async function Ee(e,t,o,n){if(n+o.rows.length-1>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");pe(e,o,n);for(const r of o.cells){const a=e.sheet.getCell(n+r.ri,r.ci+1);re(a,r.cell,e.valueMode,e.warnings);const i=_(r.cell,t.style);i&&(E(i.richText.map(c=>c.text).join(""),a.address),a.value=i);const s=t.grid?.paddingMm??.5;e.dataBars(e.sheet,r,n+r.ri,s);for(const c of r.cell.children??[])C.isImageBackedComponent(c)&&!c.grid&&e.images.write(e.sheet,c,n+r.ri,{leftMm:r.xMm+s+(r.cell.indentMm??0)+c.leftMm,offsetMm:s+c.topMm});we(a,x.mergeComponentStyles(t.style,r.cell.style)),r.cell.indentMm&&(a.alignment={...a.alignment,indent:Math.min(250,Math.max(1,Math.round(r.cell.indentMm/2.5)))}),Me(e.sheet,r,o,n);const l=e.schedule();l&&await l}return n+o.rows.length}function be(e,t,o,n){const r=Array.isArray(t.lines)&&t.lines.length>0?t.lines.join(`
-`):t.text??"",a=e.sheet.getRow(o),i=a.getCell(1);t.richParagraphs?.length||E(r,i.address),i.value=t.richParagraphs?.length?A(t.richParagraphs,t.style):r,typeof i.value=="object"&&i.value&&"richText"in i.value&&E(i.value.richText.map(l=>l.text).join(""),i.address),i.alignment={horizontal:t.style?.align??"left",vertical:t.style?.verticalAlign??"middle",wrapText:!0};const s=y(t.style?.backgroundColor);return s&&(i.fill={type:"pattern",pattern:"solid",fgColor:{argb:s}}),I(i,t.style),n>1&&e.sheet.mergeCells(o,1,o,n),a.height=e.limits.row(t.heightMm*P),o+1}function ye(e,t,o){const n=t+o-1;e.views=[{state:"frozen",ySplit:n,xSplit:0}],e.pageSetup.printTitlesRow=`1:${n}`}async function Se(e,t,o,n){!t.grids.size&&t.textWidthMm>0&&(e.sheet.getColumn(1).width=e.limits.column(p.mmToExcelColumnWidth(t.textWidthMm)));for(const i of t.grids.values()){xe(e,i);const s=e.schedule(i.columns.length);s&&await s}let r=1,a=!1;for(const{comp:i,pageIndex:s}of t.components){const l=o&&i.table?.role==="header";if(l&&a)continue;if(r>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");const c=t.grids.get(i);if(c)l&&(ye(e.sheet,r,c.rows.length),a=!0),r=await Ee(e,i,c,r);else if(i.kind==="text")r=be(e,i,r,t.columnCount);else if(C.isImageBackedComponent(i)){const d=p.importedImageOverlay(i,o),h=n.write(e.sheet,i,d?.row??r,d);d||(r=h)}else e.warnings.push(`page ${s+1} ${i.nid??i.kind}: 组件类型 ${i.kind} 暂不支持 xlsx 导出，已跳过`)}}function ve(e){if(e.maxDataBars!==void 0&&(!Number.isSafeInteger(e.maxDataBars)||e.maxDataBars<0||e.maxDataBars>1e5))throw new Error("xlsx maxDataBars 必须是 0–100000 的整数");if(e.valueMode!==void 0&&e.valueMode!=="text"&&e.valueMode!=="raw")throw new Error("xlsx valueMode 必须是 text 或 raw");if(e.paperSize!==void 0&&e.paperSize!=="auto"&&!Object.prototype.hasOwnProperty.call(S,e.paperSize))throw new Error("xlsx paperSize 必须是 auto、a3、a4 或 a5");if(e.sheetMode!==void 0&&!["auto","pages","continuous"].includes(e.sheetMode))throw new Error("xlsx sheetMode 必须是 auto、pages 或 continuous")}async function Ce(e,t={}){ve(t),M.assertOutputActive(t.signal);const o=t.assetRegistry||t.assetRenderers?await R.resolvePlanAssets(e,{...t,format:"xlsx"}):{plan:e,diagnostics:[]};e=o.plan;const n=[...o.diagnostics,...R.reportOutputDiagnostics(e,"xlsx",t)];await q(e,t.maxDataBars??1e4,t);const r=new p.ExcelJSRuntime.Workbook,a=[],i=J(r,t,a),s=[],l=H(i,t.maxDataBars??1e4,s),c=ge(a),d=le(e,t.sheetMode,a),h=new Set,u=M.createOutputScheduler(t);for(const[f,w]of d.entries()){const b=await fe(w,u);w.continuous&&!w.flow&&de(w,b.grids);const z=w.pages[0].page,k=t.sheetName?.(f)??he(w.title,f,h);h.add(k.toLowerCase());const D=r.addWorksheet(k,ue(w,t.paperSize,a)),O=t.valueMode??(B(z)||w.continuous||w.flow?"raw":"text");M.assertOutputActive(t.signal),await Se({sheet:D,warnings:a,limits:c,valueMode:O,schedule:u,images:i,dataBars:l},b,w.continuous,i),await M.outputCheckpoint(t,f+1,d.length)}M.assertOutputActive(t.signal);const g=await r.xlsx.writeBuffer();return M.assertOutputActive(t.signal),{workbook:r,buffer:g,warnings:a,diagnostics:n,...s.length?{notes:s}:{}}}exports.importExcelTemplate=p.importExcelTemplate;exports.inspectExcelWorkbook=p.inspectExcelWorkbook;exports.openExcelWorkbook=p.openExcelWorkbook;exports.bindExcelTemplate=m.bindExcelTemplate;exports.createExcelBindingDocument=m.createExcelBindingDocument;exports.createExcelBindingSession=m.createExcelBindingSession;exports.createExcelRegionBindingDocument=m.createExcelRegionBindingDocument;exports.createExcelRegionBindingSession=m.createExcelRegionBindingSession;exports.excelBindingCellRange=m.excelBindingCellRange;exports.excelBindingRowRange=m.excelBindingRowRange;exports.getExcelSheetWindow=m.getExcelSheetWindow;exports.parseExcelBindingSession=m.parseExcelBindingSession;exports.parseExcelRegionBindingSession=m.parseExcelRegionBindingSession;exports.validateExcelBindingFields=m.validateExcelBindingFields;exports.validateExcelBindingRecipe=m.validateExcelBindingRecipe;exports.validateExcelBindingRegions=m.validateExcelBindingRegions;exports.validateExcelRegionBindings=m.validateExcelRegionBindings;exports.validateExcelRegionFields=m.validateExcelRegionFields;exports.validateExcelRegionGeometry=m.validateExcelRegionGeometry;exports.renderPlanToXlsx=Ce;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const h=require("./progress-WomPRP3B.cjs"),L=require("./index-CUNw7dL9.cjs"),j=require("./data-bar-CeZuFmYl.cjs"),p=require("./workbook-session-C6-SrnCT.cjs"),G=require("./media-B7vnpD8k.cjs"),H=require("./capabilities-DiBj4Qgl.cjs"),q=require("./assets-D2gHc4Mz.cjs"),R=require("./workbook-sheets-CaPAulQ6.cjs"),w=require("./region-binding-workflow-l7NGfagJ.cjs");function _(e){const t=L.encodePng({width:1,height:1,channels:4,depth:8,data:new Uint8Array([1,3,5].map(o=>parseInt(e.slice(o,o+2),16)).concat(89))});return`data:image/png;base64,${btoa(String.fromCharCode(...t))}`}function U(e,t,o){const r=new Map;let i=0;return(a,n,s,l)=>{const c=j.dataBarBox(n.cell.dataBar,n.widthMm,n.heightMm,l);if(!c)return;if(++i>t)throw new Error(`Excel 数据条超过 ${t} 个绘图预算，请缩小范围或调整 maxDataBars`);let d=r.get(c.color);d||(d=_(c.color),r.set(c.color,d)),i===1&&o.push("数据条为静态半透明视觉快照，保留原始单元格值；Excel 编辑不会重算条形，绘图叠加文字的混色与预览可能略有差异。"),e.write(a,{kind:"image",leftMm:0,topMm:0,widthMm:c.width,heightMm:c.height,imageData:d},s,{leftMm:n.xMm+c.x,offsetMm:c.y})}}async function X(e,t,o){const r=e.pages.flatMap(n=>n.components),i=h.createOutputScheduler(o);let a=0;for(;r.length;){const n=r.pop();for(const s of n.grid?.cells??[])for(const l of s){if(l?.dataBar&&l.dataBar.end>l.dataBar.start&&++a>t)throw new Error(`Excel 数据条超过 ${t} 个绘图预算，请缩小范围或调整 maxDataBars`);l?.children&&r.push(...l.children);const c=i();c&&await c}}}function A(e,t){return{richText:e.flatMap((o,r)=>[...r?[{text:`
+`}]:[],...o.segments.map(i=>{const a=h.mergeComponentStyles(t,i.style),n=a.color?.replace(/^#/,"");return{text:i.kind==="field"?i.field??"":i.text??"",font:{name:a.fontFamily,bold:a.bold,italic:a.italic,underline:a.underline,size:h.resolveFontSize(a).fontSizePt,.../^[a-f\d]{6}$/i.test(n??"")?{color:{argb:`FF${n.toUpperCase()}`}}:{}}}})])}}function K(e,t){const o=e.children?.filter(a=>a.kind==="text"&&!a.grid)??[];if(!e.richParagraphs?.length&&!o.length)return;const r=h.mergeComponentStyles(t,e.style),i=e.richParagraphs?.length?[...e.richParagraphs]:e.text?[{segments:[{text:e.text}]}]:[];for(const a of o){const n=h.mergeComponentStyles(r,a.style),s=a.richParagraphs?.length?a.richParagraphs:[{segments:[{text:a.lines?.join(`
+`)??a.text??""}]}];for(const l of s)i.push({...l,segments:l.segments.map(c=>({...c,style:h.mergeComponentStyles(n,c.style)}))})}return A(i,r)}function J(e,t,o){let r=o*72/25.4;if(!Number.isFinite(r)||t+Math.ceil(r/409)-1>1048576)throw new Error("Excel 图片占位超过工作表行数上限");for(;r>0;){if(t>1048576)throw new Error("Excel 图片占位超过工作表行数上限");const i=Math.min(409,r);e.getRow(t++).height=i,r-=i}return t}function V(e,t,o){let r=Math.round(t*36e3),i=0;if(!Number.isSafeInteger(r))throw new Error("Excel 图片锚点超出安全坐标范围");for(e.properties.defaultColWidth??=8.43;i<16384;){const a=e.getColumn(i+1).width??e.properties.defaultColWidth,n=Math.round(p.excelColumnWidthToMm(a)*36e3);if(!Number.isSafeInteger(n)||n<=0)throw new Error("Excel 图片锚点所在列宽无效");if(r<n)return{col:i+r/n,row:o-1,nativeCol:i,nativeColOff:r,nativeRow:o-1,nativeRowOff:0};r-=n,i++}throw new Error("Excel 图片锚点超过16384列上限")}function Q(e,t,o){let r=o*72/25.4;if(!Number.isFinite(r)||Math.abs(r)>1048576*409)throw new Error("Excel 图片纵向偏移超过工作表范围");const i=a=>{const n=e.getRow(a).height??e.properties.defaultRowHeight??15;if(!Number.isFinite(n)||n<=0)throw new Error("Excel 图片锚点所在行高无效");return n};for(;r<0&&t>1;)r+=i(--t);for(;t<=1048576&&r>=i(t);)r-=i(t++);if(t>1048576||r<0)throw new Error("Excel 图片移动到工作表边界之外");return{nativeRow:t-1,nativeRowOff:Math.round(r*25.4/72*36e3)}}function Y(e,t,o){const r=G.createImageMediaInspector(t),i=new Map;return{write(a,n,s,l){if(![n.widthMm,n.heightMm,n.leftMm].every(Number.isFinite)||n.widthMm<0||n.heightMm<0||n.leftMm<0)throw new Error("Excel 图片尺寸无效");if(!n.widthMm||!n.heightMm)return s;if(!n.imageData||!/^data:image\/(png|jpe?g);base64,/i.test(n.imageData))return o.push(`${n.nid??n.kind}: Excel 图片仅支持 PNG/JPEG data URI，已跳过`),s;const c=r(n.imageData);let d=i.get(c.dataUrl);d===void 0&&(d=e.addImage({base64:c.dataUrl,extension:c.extension}),i.set(c.dataUrl,d));const g=l?s:J(a,s,n.heightMm);return a.addImage(d,{tl:{...V(a,l?.leftMm??n.leftMm,s),...l?Q(a,s,l.offsetMm):{}},ext:{width:n.widthMm*96/25.4,height:n.heightMm*96/25.4},editAs:"oneCell"}),g}}}function P(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function T(e,t){const o=e.meta?.xlsxFlow;if(o===void 0)return;if(!P(o)||o.version!=="1.0"||!Number.isSafeInteger(o.columnStart)||Number(o.columnStart)<0)throw new Error("Excel 多区域几何标记无效，不能按列序猜测输出");if(!e.grid)throw new Error("Excel 多区域输出只接受显式网格组件");const r=o,i=e.grid.colWidthsMm;if(!i?.length||r.columnStart+i.length>t.length||i.some((a,n)=>Math.abs(a-t[r.columnStart+n])>.001))throw new Error("Excel 多区域列位置与网格列宽不一致");return r}function $(e){const t=e.meta?.xlsxFlow;if(t===void 0){if(e.components.some(r=>r.meta?.xlsxFlow!==void 0))throw new Error("Excel 多区域页面缺少完整列几何标记");return}const o=Z(t,e.meta?.reportScope);for(const r of e.components){const i=T(r,o.widths);if(!i)throw new Error("Excel 多区域页面混入没有区域几何的组件，请使用独立页面模板");const a=o.widths.slice(0,i.columnStart).reduce((s,l)=>s+l,e.marginLeftMm??0),n=r.grid.colWidthsMm.reduce((s,l)=>s+l,0);if(Math.abs(a-r.leftMm)>.01||Math.abs(n-r.widthMm)>.01)throw new Error("Excel 多区域标记与真实横向位置不一致")}return o}function Z(e,t){if(!P(e)||e.version!=="1.0"||typeof e.sheet!="string"||!e.sheet.trim()||typeof e.templateId!="string"||!e.templateId.trim())throw new Error("Excel 多区域工作表标识无效");if(!Array.isArray(e.fullWidthsMm)||!e.fullWidthsMm.length||e.fullWidthsMm.length>16384||e.fullWidthsMm.some(o=>typeof o!="number"||!Number.isFinite(o)||o<=0||o>2e3))throw new Error("Excel 多区域完整列宽无效");if(t!==void 0&&(typeof t!="string"||!t.trim()))throw new Error("Excel 多区域报表命名空间无效");return{key:JSON.stringify([t??e.templateId,e.sheet]),sheet:e.sheet,widths:e.fullWidthsMm}}function v(e){return Math.round(e*1e6)/1e6}function ee(e,t,o,r,i){return e.components.filter(a=>r?a.pageAnchor==="header"?t===0:a.pageAnchor==="footer"?t===o-1:a.table?.role!=="header"?!0:i.has(a.table.id)?!1:(i.add(a.table.id),!0):!0)}function te(e,t,o,r){const i=e.components.filter(n=>!t.includes(n)&&n.table?.role==="header"),a=t.filter(n=>!n.pageAnchor).reduce((n,s)=>Math.max(n,s.topMm+s.heightMm),e.marginTopMm??0);return t.map(n=>{let s=n.topMm;return o&&n.pageAnchor==="footer"&&(s=a),s-=i.filter(l=>l.topMm+l.heightMm<=s+.001).reduce((l,c)=>l+c.heightMm,0),{component:n,layout:h.resolveGridLayout(n.grid,n.widthMm,n.heightMm),top:s,column:T(n,r).columnStart}})}function ne(e,t,o){const r=t.length-1;if(r*o.length>1e6)throw new Error("Excel 多区域单页超过 100 万几何单元格，请减小预览分页高度或列数");const i=new Map(t.map((s,l)=>[s,l])),a=new Map,n=new Map;for(const s of e)for(const l of s.layout.cells){if(!Object.keys(l.cell).length)continue;const c=i.get(v(s.top+l.yMm)),d=i.get(v(s.top+l.yMm+l.heightMm)),g=s.column+l.ci,m=g+(l.cell.colSpan??1),u=`${c}:${g}`;for(let f=c;f<d;f++)for(let E=g;E<m;E++){const M=`${f}:${E}`;if(n.has(M))throw new Error("Excel 多区域实际单元格互相覆盖，已终止输出，未覆盖已有内容");n.set(M,u)}a.set(u,{...l.cell,style:h.mergeComponentStyles(s.component.style,l.cell.style),rowSpan:d-c,colSpan:m-g})}return Array.from({length:r},(s,l)=>{const c=[];for(let d=0;d<o.length;d++){const g=`${l}:${d}`,m=a.get(g);m?(c.push(m),d+=(m.colSpan??1)-1):n.has(g)||c.push(null)}return c})}function re(e,t){const o=new Set,r=[];let i;for(const[a,{page:n}]of e.entries()){const s=$(n);if(i&&(s.key!==i.key||s.widths.length!==i.widths.length||s.widths.some((u,f)=>Math.abs(u-i.widths[f])>.001)))throw new Error("Excel 多区域分页的工作表或列结构不一致");i??=s;const l=ee(n,a,e.length,t,o),c=te(n,l,t,s.widths);if(!c.length)continue;const d=[...new Set(c.flatMap(u=>[...u.layout.rows.map(f=>v(u.top+f.pos)),v(u.top+u.component.heightMm)]))].sort((u,f)=>u-f),g=ne(c,d,s.widths),m=d.slice(1).map((u,f)=>u-d[f]);r.push({kind:"rect",leftMm:0,topMm:0,widthMm:s.widths.reduce((u,f)=>u+f,0),heightMm:m.reduce((u,f)=>u+f,0),grid:{cells:g,colWidthsMm:s.widths,rowHeightsMm:m}})}return r}const F=72/25.4,ie=32767,oe=253;function b(e,t){if(typeof e!="string")return;if(e.length>ie)throw new Error(`Excel 单元格 ${t} 最多支持 32767 个字符，无法无损导出；内容未裁剪`);let o=0;for(let r=0;r<e.length;r++)if(e.charCodeAt(r)===10&&++o>oe)throw new Error(`Excel 单元格 ${t} 最多支持 253 个换行，无法无损导出；内容未改写`)}function y(e){if(!e)return;const t=e.replace("#","");return/^[0-9a-fA-F]{6}$/.test(t)?`FF${t.toUpperCase()}`:void 0}function I(e,t={}){e.font={name:t.fontFamily,bold:t.bold===!0,italic:t.italic===!0,underline:t.underline===!0,size:h.resolveFontSize(t).fontSizePt,color:y(t.color)?{argb:y(t.color)}:void 0}}const S={a3:{width:297,height:420,code:8},a4:{width:210,height:297,code:9},a5:{width:148,height:210,code:11}};function ae(e,t,o,r){if(t&&t!=="auto")return S[t].code;const i=Math.min(e.pageWidthMm,e.pageHeightMm),a=Math.max(e.pageWidthMm,e.pageHeightMm),n=Object.values(S).find(s=>Math.abs(i-s.width)<=1&&Math.abs(a-s.height)<=1);return n?n.code:(r.push(`page ${o+1}: 自定义纸张 ${e.pageWidthMm}×${e.pageHeightMm}mm 无对应 Excel 纸型，打印设置回退 A4；可显式配置 paperSize`),S.a4.code)}function se(e,t,o,r){const i=typeof t.text=="string"?t.text:"";if(o!=="raw"||!Object.prototype.hasOwnProperty.call(t,"value")){b(i,e.address),e.value=i;return}const a=t.value;if(a===null||typeof a=="string"||typeof a=="boolean"||typeof a=="number"&&Number.isFinite(a)){b(a,e.address),e.value=a,t.numberFormat&&(e.numFmt=t.numberFormat);return}b(i,e.address),e.value=i,r.push(`原始单元格值无效，已保留显示文本：${e.address}`)}function le(e){const t=$(e);return t?{id:`xlsx-flow:${t.key}`,title:t.sheet,wide:!0,flow:!0}:ce(e)}function ce(e){const o=e.components.filter(r=>r.table!==void 0)[0]?.table;if(!(!o||typeof o.id!="string"||!o.id.trim()||!Array.isArray(o.columnKeys)||!o.columnKeys.length)){for(const r of e.components){if(r.table){if(!r.grid||r.table.id!==o.id)return;continue}if(r.grid||r.kind!=="text"&&!h.isImageBackedComponent(r))return}return{id:o.id,title:o.title,wide:o.layout==="wide"||e.layout==="wide"}}}function de(e,t){const o=new Set;for(const[r,i]of e.pages.entries())if(!t[r])for(const a of i.components)typeof a.table?.id=="string"&&o.add(a.table.id);return o}function C(e){return e.layout==="wide"||e.components.some(t=>t.table?.layout==="wide")}function he(e,t,o){const r=[],i=e.pages.map(le),a=de(e,i);for(const[n,s]of e.pages.entries()){const l=i[n],c=l&&!a.has(l.id),d=t==="pages"||!c?void 0:l;if(t==="continuous"&&!d)throw new Error(`page ${n+1}: continuous Excel 需要完整、单一的逻辑表来源；自由布局请使用 sheetMode: 'pages'`);const g=d!==void 0&&(t==="continuous"||d.wide);!g&&t!=="pages"&&C(s)&&o.push(`page ${n+1}: 混合或缺少逻辑表来源，已保留独立 Sheet，未猜测合并内容`);const m=r[r.length-1];g&&m?.continuous&&m.tableId===d.id?m.pages.push({page:s,index:n}):r.push({pages:[{page:s,index:n}],continuous:g,...g?{tableId:d.id,title:d.title}:{},...l?.flow?{flow:!0,title:l.title}:{}})}return r}function W(e,t,o){return!e||e.length===t.length&&e.every((r,i)=>o(r,t[i]))}function ge(e,t,o,r){const i=e.table,a=t.columns.map(l=>l.size),n=W(r.keys,i.columnKeys,(l,c)=>l===c),s=W(r.widths,a,(l,c)=>Math.abs(l-c)<=.001);if(i.columnKeys.length!==a.length||!n||!s)throw new Error(`page ${o+1}: 连续 Excel 逻辑表 ${i.id} 的列结构或列宽不一致`);if(r.keys??=i.columnKeys,r.widths??=a,i.role==="header"){if(i.rowIndex!==-1)throw new Error(`page ${o+1}: 连续 Excel 表头 rowIndex 必须为 -1`);r.headerSeen=!0}else{if(!["body","group-header","subtotal","grand-total"].includes(i.role)||i.rowIndex!==r.expectedRow)throw new Error(`page ${o+1}: 连续 Excel 逻辑行来源不连续或重复（期望 ${r.expectedRow}）`);r.expectedRow+=t.rows.length}}function ue(e,t){const o={expectedRow:0,headerSeen:!1};for(const{page:r,index:i}of e.pages)for(const a of r.components){const n=t.get(a);a.table&&n&&ge(a,n,i,o)}if(!o.headerSeen)throw new Error("连续 Excel 逻辑表缺少明确表头来源")}function fe(e,t,o){let r=(e?.replace(/[\\/*?:[\]]/g," ").replace(/\s+/g," ").trim()||`Sheet${t+1}`).slice(0,31).replace(/^'+|'+$/g,"").trim()||`Sheet${t+1}`;r.toLowerCase()==="history"&&(r+=" 报表");let i=r,a=1;for(;o.has(i.toLowerCase());){const n=` (${++a})`;i=r.slice(0,31-n.length)+n}return o.add(i.toLowerCase()),i}function me(e){const t=new Set;function o(r,i,a,n){return r<=i?r:(t.has(a)||(e.push(n),t.add(a)),i)}return{column:r=>o(r,255,"column","Excel 单列宽度上限为 255 字符，超宽列已收敛至 255；单元格值完整保留，显示范围可能受限"),row:r=>o(r,409,"row","Excel 行高上限为 409pt，超高行已收敛至 409pt；单元格值完整保留，显示范围可能受限")}}async function we(e,t){const o=e.flow?re(e.pages,e.continuous).map(n=>({comp:n,pageIndex:e.pages[0].index})):e.pages.flatMap(({page:n,index:s},l)=>n.components.filter(c=>!e.continuous||(c.pageAnchor!=="header"||l===0)&&(c.pageAnchor!=="footer"||l===e.pages.length-1)).map(c=>({comp:c,pageIndex:s}))),r=new Map;let i=1,a=0;for(const{comp:n}of o)if(n.grid){const s=h.resolveGridLayout(n.grid,n.widthMm,n.heightMm);r.set(n,s),i=Math.max(i,s.columns.length);const l=t(s.cells.length);l&&await l}else n.kind==="text"&&(a=Math.max(a,n.widthMm));if(i>16384)throw new Error("Excel 最多支持 16384 列，无法无损导出此报表");return{components:o,grids:r,columnCount:i,textWidthMm:a}}function xe(e,t,o){const{page:r,index:i}=e.pages[0],a=t!==void 0&&t!=="auto";return(e.continuous||C(r))&&!a?{}:{pageSetup:{paperSize:ae(r,t,i,o),orientation:r.pageWidthMm>r.pageHeightMm?"landscape":"portrait",fitToPage:!0,...e.continuous?{fitToWidth:1,fitToHeight:0}:{}}}}function pe(e){const t=y(e.borderColor??e.lineColor),o={style:"thin",...t?{color:{argb:t}}:{}};return{...e.borderTop!==!1?{top:o}:{},...e.borderLeft!==!1?{left:o}:{},...e.borderBottom!==!1?{bottom:o}:{},...e.borderRight!==!1?{right:o}:{}}}function Me(e,t){e.alignment={horizontal:t.align??"left",vertical:t.verticalAlign??"middle",wrapText:!0};const o=y(t.backgroundColor);o&&(e.fill={type:"pattern",pattern:"solid",fgColor:{argb:o}}),e.border=pe(t),I(e,t)}function Ee(e,t){for(const[o,r]of t.columns.entries()){const i=e.sheet.getColumn(o+1),a=e.limits.column(p.mmToExcelColumnWidth(r.size));(i.width==null||i.width<a)&&(i.width=a)}}function be(e,t,o){for(const[r,i]of t.rows.entries()){const a=e.sheet.getRow(o+r),n=e.limits.row(i.size*F);(a.height==null||a.height<n)&&(a.height=n)}}function ye(e,t,o,r){const i=Math.max(1,Math.min(t.cell.colSpan??1,o.columns.length-t.ci)),a=Math.max(1,Math.min(t.cell.rowSpan??1,o.rows.length-t.ri));(i>1||a>1)&&e.mergeCells(r+t.ri,t.ci+1,r+t.ri+a-1,t.ci+i)}async function Se(e,t,o,r){if(r+o.rows.length-1>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");be(e,o,r);for(const i of o.cells){const a=e.sheet.getCell(r+i.ri,i.ci+1);se(a,i.cell,e.valueMode,e.warnings);const n=K(i.cell,t.style);n&&(b(n.richText.map(c=>c.text).join(""),a.address),a.value=n);const s=t.grid?.paddingMm??.5;e.dataBars(e.sheet,i,r+i.ri,s);for(const c of i.cell.children??[])h.isImageBackedComponent(c)&&!c.grid&&e.images.write(e.sheet,c,r+i.ri,{leftMm:i.xMm+s+(i.cell.indentMm??0)+c.leftMm,offsetMm:s+c.topMm});Me(a,h.mergeComponentStyles(t.style,i.cell.style)),i.cell.indentMm&&(a.alignment={...a.alignment,indent:Math.min(250,Math.max(1,Math.round(i.cell.indentMm/2.5)))}),ye(e.sheet,i,o,r);const l=e.schedule();l&&await l}return r+o.rows.length}function ve(e,t,o,r){const i=Array.isArray(t.lines)&&t.lines.length>0?t.lines.join(`
+`):t.text??"",a=e.sheet.getRow(o),n=a.getCell(1);t.richParagraphs?.length||b(i,n.address),n.value=t.richParagraphs?.length?A(t.richParagraphs,t.style):i,typeof n.value=="object"&&n.value&&"richText"in n.value&&b(n.value.richText.map(l=>l.text).join(""),n.address),n.alignment={horizontal:t.style?.align??"left",vertical:t.style?.verticalAlign??"middle",wrapText:!0};const s=y(t.style?.backgroundColor);return s&&(n.fill={type:"pattern",pattern:"solid",fgColor:{argb:s}}),I(n,t.style),r>1&&e.sheet.mergeCells(o,1,o,r),a.height=e.limits.row(t.heightMm*F),o+1}function Ce(e,t,o){const r=t+o-1;e.views=[{state:"frozen",ySplit:r,xSplit:0}],e.pageSetup.printTitlesRow=`1:${r}`}async function ke(e,t,o,r){!t.grids.size&&t.textWidthMm>0&&(e.sheet.getColumn(1).width=e.limits.column(p.mmToExcelColumnWidth(t.textWidthMm)));for(const n of t.grids.values()){Ee(e,n);const s=e.schedule(n.columns.length);s&&await s}let i=1,a=!1;for(const{comp:n,pageIndex:s}of t.components){const l=o&&n.table?.role==="header";if(l&&a)continue;if(i>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");const c=t.grids.get(n);if(c)l&&(Ce(e.sheet,i,c.rows.length),a=!0),i=await Se(e,n,c,i);else if(n.kind==="text")i=ve(e,n,i,t.columnCount);else if(h.isImageBackedComponent(n)){const d=p.importedImageOverlay(n,o),g=r.write(e.sheet,n,d?.row??i,d);d||(i=g)}else e.warnings.push(`page ${s+1} ${n.nid??n.kind}: 组件类型 ${n.kind} 暂不支持 xlsx 导出，已跳过`)}}function Be(e){if(e.maxDataBars!==void 0&&(!Number.isSafeInteger(e.maxDataBars)||e.maxDataBars<0||e.maxDataBars>1e5))throw new Error("xlsx maxDataBars 必须是 0–100000 的整数");if(e.valueMode!==void 0&&e.valueMode!=="text"&&e.valueMode!=="raw")throw new Error("xlsx valueMode 必须是 text 或 raw");if(e.paperSize!==void 0&&e.paperSize!=="auto"&&!Object.prototype.hasOwnProperty.call(S,e.paperSize))throw new Error("xlsx paperSize 必须是 auto、a3、a4 或 a5");if(e.sheetMode!==void 0&&!["auto","pages","continuous"].includes(e.sheetMode))throw new Error("xlsx sheetMode 必须是 auto、pages 或 continuous")}async function O(e,t={}){const o=R.snapshotAdditionalSheets(t.additionalSheets),r=R.snapshotSheetNames(t.sheetNames);Be(t),h.assertOutputActive(t.signal);const i=t.assetRegistry||t.assetRenderers?await q.resolvePlanAssets(e,{...t,format:"xlsx"}):{plan:e,diagnostics:[]};e=i.plan;const a=[...i.diagnostics,...H.reportOutputDiagnostics(e,"xlsx",t)];await X(e,t.maxDataBars??1e4,t);const n=new p.ExcelJSRuntime.Workbook,s=[],l=Y(n,t,s),c=[],d=U(l,t.maxDataBars??1e4,c),g=me(s),m=he(e,t.sheetMode,s),u=m.length+(o?.length??0),f=new Set,E=h.createOutputScheduler(t);for(const[M,x]of m.entries()){const k=await we(x,E);x.continuous&&!x.flow&&ue(x,k.grids);const z=x.pages[0].page,B=r?.[M]??t.sheetName?.(M)??fe(x.title,M,f);f.add(B.toLowerCase());const D=n.addWorksheet(B,xe(x,t.paperSize,s)),N=t.valueMode??(C(z)||x.continuous||x.flow?"raw":"text");h.assertOutputActive(t.signal),await ke({sheet:D,warnings:s,limits:g,valueMode:N,schedule:E,images:l,dataBars:d},k,x.continuous,l),await h.outputCheckpoint(t,M+1,u)}return await Re(n,o,t,m.length,u),{workbook:n,warnings:s,diagnostics:a,...c.length?{notes:c}:{}}}async function Re(e,t=[],o,r,i){const a=h.createOutputScheduler(o);for(const n of t){if(h.assertOutputActive(o.signal),e.worksheets.some(l=>l.name.toLowerCase()===n.name.toLowerCase()))throw new TypeError(`附加工作表名称已被报表使用 ${n.name}`);const s=e.addWorksheet(n.name);n.columnWidths&&(s.columns=n.columnWidths.map(l=>({width:l})));for(const l of n.rows){const c=s.addRow([...l]);c.alignment={vertical:"top",wrapText:!0};const d=a(l.length);d&&await d}await h.outputCheckpoint(o,++r,i)}h.assertOutputActive(o.signal)}async function We(e,t={}){let o=1;const r=t.onProgress?(n,s)=>{o=s+1,h.notifyOutputProgress(t,n,o)}:void 0,i=await O(e,{...t,onProgress:r});h.assertOutputActive(t.signal);const a=await i.workbook.xlsx.writeBuffer();return h.assertOutputActive(t.signal),h.notifyOutputProgress(t,o,o),{...i,buffer:a}}exports.importExcelTemplate=p.importExcelTemplate;exports.inspectExcelWorkbook=p.inspectExcelWorkbook;exports.openExcelWorkbook=p.openExcelWorkbook;exports.bindExcelTemplate=w.bindExcelTemplate;exports.createExcelBindingDocument=w.createExcelBindingDocument;exports.createExcelBindingSession=w.createExcelBindingSession;exports.createExcelRegionBindingDocument=w.createExcelRegionBindingDocument;exports.createExcelRegionBindingSession=w.createExcelRegionBindingSession;exports.excelBindingCellRange=w.excelBindingCellRange;exports.excelBindingRowRange=w.excelBindingRowRange;exports.getExcelSheetWindow=w.getExcelSheetWindow;exports.parseExcelBindingSession=w.parseExcelBindingSession;exports.parseExcelRegionBindingSession=w.parseExcelRegionBindingSession;exports.validateExcelBindingFields=w.validateExcelBindingFields;exports.validateExcelBindingRecipe=w.validateExcelBindingRecipe;exports.validateExcelBindingRegions=w.validateExcelBindingRegions;exports.validateExcelRegionBindings=w.validateExcelRegionBindings;exports.validateExcelRegionFields=w.validateExcelRegionFields;exports.validateExcelRegionGeometry=w.validateExcelRegionGeometry;exports.renderPlanToWorkbook=O;exports.renderPlanToXlsx=We;

package/dist/xlsx.d.cts

@@ -1909,6 +1909,10 @@ declare interface RenderPlan {
     pages: PlanPage[];
 }
 
+/** 构建可修改工作簿，调用方需要追加内容时自行完成唯一一次编码。 */
+export declare function renderPlanToWorkbook(plan: RenderPlan, options?: XlsxRenderOptions): Promise<XlsxWorkbookResult>;
+
+/** 默认出口保持原契约，全部工作表完成后只执行一次 ZIP 编码。 */
 export declare function renderPlanToXlsx(plan: RenderPlan, options?: XlsxRenderOptions): Promise<XlsxRenderResult>;
 
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
@@ -2083,6 +2087,8 @@ declare type ReportPredicateScalar = string | number | boolean | null;
 
 declare interface ReportTemplate {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -2090,6 +2096,14 @@ declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+declare interface ReportTemplateDataContract {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding[];
+    }>>;
+}
+
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 declare interface ReportTemplateDocument {
     schemaVersion: "1.0";
@@ -2101,6 +2115,15 @@ declare interface ReportTemplateDocument {
     template: ReportTemplate;
 }
 
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract["type"];
+    unit?: string;
+}
+
 /** Every record emits its copies, each containing all template pages in their original order. */
 declare interface ReportTemplateRepeat {
     dataset: string;
@@ -3236,6 +3259,13 @@ declare interface Xlsx {
     	write(stream: Stream, options?: Partial<XlsxWriteOptions>): Promise<void>;
 }
 
+/** 可序列化的附加工作表在编码前写入，浏览器与 Worker 共用同一声明。 */
+export declare interface XlsxAdditionalSheet {
+    name: string;
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+    columnWidths?: readonly number[];
+}
+
 declare type XlsxImageOptions = ImageMediaOptions;
 
 declare interface XlsxReadOptions {
@@ -3256,6 +3286,8 @@ declare interface XlsxReadOptions {
 export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
+    /** 可序列化命名，用于 Worker；未提供的项沿用默认名称。 */
+    sheetNames?: readonly string[];
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
@@ -3264,11 +3296,16 @@ export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImage
     maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
+    /** 在最终编码前追加说明、审计等标量工作表，可直接交给 Worker。 */
+    additionalSheets?: readonly XlsxAdditionalSheet[];
 }
 
-export declare interface XlsxRenderResult {
-    workbook: ExcelJS.Workbook;
+export declare interface XlsxRenderResult extends XlsxWorkbookResult {
     buffer: ExcelJS.Buffer;
+}
+
+export declare interface XlsxWorkbookResult {
+    workbook: ExcelJS.Workbook;
     warnings: string[];
     diagnostics?: OutputDiagnostic[];
     /** Informational output semantics; these do not indicate missing content. */

package/dist/xlsx.d.ts

@@ -1909,6 +1909,10 @@ declare interface RenderPlan {
     pages: PlanPage[];
 }
 
+/** 构建可修改工作簿，调用方需要追加内容时自行完成唯一一次编码。 */
+export declare function renderPlanToWorkbook(plan: RenderPlan, options?: XlsxRenderOptions): Promise<XlsxWorkbookResult>;
+
+/** 默认出口保持原契约，全部工作表完成后只执行一次 ZIP 编码。 */
 export declare function renderPlanToXlsx(plan: RenderPlan, options?: XlsxRenderOptions): Promise<XlsxRenderResult>;
 
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
@@ -2083,6 +2087,8 @@ declare type ReportPredicateScalar = string | number | boolean | null;
 
 declare interface ReportTemplate {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -2090,6 +2096,14 @@ declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+declare interface ReportTemplateDataContract {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding[];
+    }>>;
+}
+
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 declare interface ReportTemplateDocument {
     schemaVersion: "1.0";
@@ -2101,6 +2115,15 @@ declare interface ReportTemplateDocument {
     template: ReportTemplate;
 }
 
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract["type"];
+    unit?: string;
+}
+
 /** Every record emits its copies, each containing all template pages in their original order. */
 declare interface ReportTemplateRepeat {
     dataset: string;
@@ -3236,6 +3259,13 @@ declare interface Xlsx {
     	write(stream: Stream, options?: Partial<XlsxWriteOptions>): Promise<void>;
 }
 
+/** 可序列化的附加工作表在编码前写入，浏览器与 Worker 共用同一声明。 */
+export declare interface XlsxAdditionalSheet {
+    name: string;
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+    columnWidths?: readonly number[];
+}
+
 declare type XlsxImageOptions = ImageMediaOptions;
 
 declare interface XlsxReadOptions {
@@ -3256,6 +3286,8 @@ declare interface XlsxReadOptions {
 export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
+    /** 可序列化命名，用于 Worker；未提供的项沿用默认名称。 */
+    sheetNames?: readonly string[];
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
@@ -3264,11 +3296,16 @@ export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImage
     maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
+    /** 在最终编码前追加说明、审计等标量工作表，可直接交给 Worker。 */
+    additionalSheets?: readonly XlsxAdditionalSheet[];
 }
 
-export declare interface XlsxRenderResult {
-    workbook: ExcelJS.Workbook;
+export declare interface XlsxRenderResult extends XlsxWorkbookResult {
     buffer: ExcelJS.Buffer;
+}
+
+export declare interface XlsxWorkbookResult {
+    workbook: ExcelJS.Workbook;
     warnings: string[];
     diagnostics?: OutputDiagnostic[];
     /** Informational output semantics; these do not indicate missing content. */