@agile-team/mach-report 2.16.0 → 2.18.0

package/dist/runtime-CEMvybO7.js

@@ -0,0 +1,170 @@
+import { R as y, Q as R, S as W, T as B, J as O, q as X, L as z, U as G, c as H, P as K, b as Y, r as Z } from "./json-snapshot-By4ZVVUt.js";
+import { g as M } from "./report-params-D9tBuM9B.js";
+import { l as $, r as ee, R as te } from "./param-validation-CnDEd2l-.js";
+import { t as P, b as w, D as se, v as ae, c as D, R as F } from "./sha256-BDQ1Qk7A.js";
+import { b as re } from "./template-registry-BIhIHOab.js";
+import { T as oe } from "./column-visual-BpgQVWwT.js";
+import { a as j } from "./assets-2eC3mOcV.js";
+import { s as S, a as J, d as ne, e as ce, r as ie } from "./prepared-BE-4jfX5.js";
+function k(e = []) {
+  return e.map(({ code: t, message: r, severity: n, pageIndex: s, componentIndex: a }) => ({ code: t, message: r, severity: n, path: a < 0 ? `$.pages.${s}` : `$.pages.${s}.components.${a}` }));
+}
+async function _(e, t, r = Date.now()) {
+  const n = e.prepared;
+  if (e.fidelity === "strict" && n.diagnostics.some((g) => g.code === "asset-render-failed" || g.code === "asset-budget-exceeded")) throw new y("validate", "严格输出拒绝已有资产渲染降级，请修复组件后重新准备报表。");
+  const s = e.format === "pdf" ? await import("@agile-team/mach-report/pdf") : void 0;
+  P(e.signal);
+  const a = e.pdf?.customFontFaces ?? (e.pdf?.customFontBytes ? { regular: e.pdf.customFontBytes } : void 0), l = s && a ? s.createFontBytesMeasurer(a) : void 0, m = R(e), p = await m.run("encode", async () => {
+    let g;
+    if (e.format === "pdf") {
+      P(e.signal);
+      const c = await s.renderPlanToPdf(n.plan, { ...e.pdf, ...l ? { measurer: l } : {}, fidelity: e.fidelity, signal: e.signal, onProgress: (f, i) => m.progress("encode", f, i) });
+      g = c.bytes, n.diagnostics.push(...k(c.diagnostics)), n.diagnostics.push(...c.fidelityWarnings.map((f) => ({ code: "pdf-fidelity", message: f, severity: "warning" })), ...c.pageErrors.map((f) => ({ code: "pdf-page", message: f, severity: "error" }))), c.unsupportedTextCount && n.diagnostics.push({ code: "pdf-font", message: `${c.unsupportedTextCount} 段文本包含当前字体不支持的字符`, severity: "warning" });
+    } else {
+      const { renderPlanToXlsx: c } = await import("@agile-team/mach-report/xlsx");
+      P(e.signal);
+      const f = await c(n.plan, { ...e.xlsx, fidelity: e.fidelity, signal: e.signal, onProgress: (i, v) => m.progress("encode", i, v) });
+      g = new Uint8Array(f.buffer), n.diagnostics.push(...k(f.diagnostics)), n.diagnostics.push(...f.warnings.map((i) => ({ code: "xlsx-fidelity", message: i, severity: "warning" }))), n.diagnostics.push(...(f.notes ?? []).map((i) => ({ code: "xlsx-snapshot", message: i, severity: "info" })));
+    }
+    return P(e.signal), g;
+  });
+  w(t, "maxOutputBytes", p.byteLength);
+  const { plan: o, ...x } = n;
+  return { ...x, bytes: p, format: e.format, contentType: e.format === "pdf" ? "application/pdf" : "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", stats: { ...x.stats, durationMs: Date.now() - r, outputBytes: p.byteLength } };
+}
+function q(e) {
+  return { ...e, reportIds: [...e.reportIds], ...e.params ? { params: { ...e.params } } : {} };
+}
+function V(e, t) {
+  if (t.length === 0) throw new y("config", "缺少报表 ID");
+  return t.map((r) => {
+    if (!Object.prototype.hasOwnProperty.call(e, r)) throw new y("config", `未注册报表 ${r}`);
+    return e[r];
+  });
+}
+function I(e) {
+  return e.grid?.cells.reduce((t, r) => t + r.reduce((n, s) => n + (s ? 1 + (s.children?.reduce((a, l) => a + I(l), 0) ?? 0) : 0), 0), 0) ?? 0;
+}
+function de(e, t, r) {
+  return e.pages.reduce((n, s) => n + s.components.reduce((a, l) => l.kind !== "list" ? a + I(l) : a + Z(l, t, r), 0), 0);
+}
+function pe(e, t = Object.keys(e)) {
+  return V(e, t).map((r, n) => {
+    const s = t[n], a = M(e, [s]);
+    return {
+      id: s,
+      params: JSON.parse(JSON.stringify(a)),
+      paramsSchema: ee(a),
+      datasetsSchema: Object.fromEntries(Object.entries(r.dataSchema ?? {}).map(([l, m]) => [l, W(typeof r.template == "function" ? void 0 : r.template, l, m)])),
+      capabilities: {
+        save: !!r.provider?.save,
+        export: !!r.provider?.export,
+        templates: !!r.provider?.templates
+      }
+    };
+  });
+}
+function A(e, t) {
+  V(e, t.reportIds);
+  const r = $(M(e, t.reportIds), t.params), n = t.reportIds.flatMap((a) => $(M(e, [a]), t.params).issues), s = new Map(n.map((a) => [JSON.stringify(a), a]));
+  return { ...r, ok: s.size === 0, issues: [...s.values()] };
+}
+function N(e, t) {
+  const r = re(e.plan);
+  if (!r.ok) throw new y("validate", `执行器返回无效计划：${r.errors[0]?.path}`);
+  const n = e.plan.pages.length, s = e.plan.pages.reduce((a, l) => a + l.components.reduce((m, p) => m + I(p), 0), 0);
+  return w(t, "maxRows", e.stats.rows), w(t, "maxPages", n), w(t, "maxCells", s), { ...e, stats: { ...e.stats, pages: n, cells: s } };
+}
+function U(e, t) {
+  const r = A(e.reports, t);
+  if (!r.ok) throw new te(r.issues);
+}
+function ve(e) {
+  const t = { ...se, ...e.budget };
+  ae(t);
+  const r = async (s, a) => {
+    const l = Date.now();
+    let m = 0, p = 0;
+    const o = [], x = {}, g = [], c = Object.fromEntries(Object.entries(e.reports).map(([d, u]) => [d, {
+      ...u,
+      pagination: { ...e.pagination, ...u.pagination, ...a ? { measurer: a } : {} },
+      dataValidation: {
+        ...u.dataValidation,
+        maxRows: Math.min(t.maxRows ?? 1e5, u.dataValidation?.maxRows ?? 1 / 0),
+        maxCells: Math.min(t.maxCells ?? 2e6, u.dataValidation?.maxCells ?? 1 / 0)
+      }
+    }])), i = await X(c, { maxPages: t.maxPages, maxCells: t.maxCells, maxChartComponents: t.maxChartComponents, onDatasets: (d, u, h) => {
+      try {
+        m += z(h, u, { maxRows: t.maxRows, signal: s.signal });
+      } catch (b) {
+        throw b instanceof oe ? new F("budget", b.message, "$.budget.maxRows") : b;
+      }
+      w(t, "maxRows", m), p += de(h, u, c[d]?.pagination), w(t, "maxCells", p);
+    } })({ ...s, params: s.params ?? {}, onWarning: (d) => o.push({ code: "layout", message: d, severity: "warning" }), onQueryResult: (d, u, h = 0) => {
+      const b = G(h, d);
+      Object.defineProperty(x, d, { value: { revision: u.revision, sourceToken: u.sourceToken }, enumerable: !0, writable: !0 }), g.push({ reportId: d, reportIndex: h, reportScope: b, ...u.revision === void 0 ? {} : { revision: u.revision }, ...u.sourceToken === void 0 ? {} : { sourceToken: u.sourceToken } }), o.push(...(u.diagnostics ?? []).map((C) => ({ ...C, ...C.target ? { target: {
+        ...C.target,
+        reportScope: b,
+        ...C.target.tableId ? { tableId: JSON.stringify([h, d, C.target.tableId]) } : {}
+      } } : {} })));
+    } }).catch((d) => {
+      throw d instanceof y && d.cause instanceof H ? new F("budget", d.cause.message, "$.budget.maxPages") : d instanceof y && d.cause instanceof K ? new F("budget", d.cause.message, "$.budget.maxCells") : d instanceof y && d.cause instanceof Y ? new F("budget", d.cause.message, "$.budget.maxChartComponents") : d;
+    });
+    P(s.signal);
+    const v = e.assets ? await R(s).run("assets", () => j(i, { ...e.assets, signal: s.signal })) : { plan: i, diagnostics: [] }, E = v.plan;
+    o.push(...k(v.diagnostics));
+    const L = E.pages.reduce((d, u) => d + u.components.reduce((h, b) => h + I(b), 0), 0);
+    w(t, "maxPages", E.pages.length), w(t, "maxCells", L);
+    const T = ie(s.pdf), Q = e.pagination?.measurer || Object.values(e.reports).some((d) => d.pagination?.measurer);
+    return { plan: E, diagnostics: o, revisions: x, sources: g, layout: { textMetrics: T ? "font-bytes" : Q ? "provided" : "heuristic", ...T ? { fontFingerprint: T } : {} }, stats: { rows: m, pages: E.pages.length, cells: L, durationMs: Date.now() - l } };
+  }, n = async (s) => {
+    const a = Date.now();
+    if (s.format !== "pdf" && s.format !== "xlsx") throw new y("config", "不支持的报表导出格式");
+    const l = s.format === "pdf" ? await import("@agile-team/mach-report/pdf") : void 0;
+    P(s.signal);
+    const m = s.pdf?.customFontFaces ?? (s.pdf?.customFontBytes ? { regular: s.pdf.customFontBytes } : void 0), p = l && m ? l.createFontBytesMeasurer(m) : void 0, o = await r(s, p);
+    return P(s.signal), _({ ...s, prepared: o }, t, a);
+  };
+  return {
+    describe: (s) => pe(e.reports, s),
+    validate: (s) => A(e.reports, s),
+    prepare: (s) => D(s.signal, t.maxDurationMs, async (a) => {
+      const { signal: l, onEvent: m, ...p } = q(s), o = { ...p, ...p.pdf ? { pdf: S(p.pdf) } : {}, taskId: p.taskId ?? B() }, x = m ? (v) => O(m, v, a) : void 0, g = { ...o, signal: a, onEvent: x };
+      R(g).runSync("validate", () => U(e, o));
+      let c;
+      const f = o.pdf?.customFontFaces ?? (o.pdf?.customFontBytes ? { regular: o.pdf.customFontBytes } : void 0);
+      if (!e.executor && f) {
+        const v = await import("@agile-team/mach-report/pdf");
+        P(a), c = v.createFontBytesMeasurer(f);
+      }
+      const i = e.executor ? await e.executor.prepare(o, a, x) : await r(g, c);
+      return N(i, t);
+    }),
+    exportPrepared: (s) => D(s.signal, t.maxDurationMs, async (a) => {
+      const l = Date.now(), { signal: m, onEvent: p, ...o } = s, x = N(ne(s.prepared, t.maxPreparedBytes ?? 64e6, a), t), g = { ...o, xlsx: J(o.xlsx), prepared: x, ...o.pdf ? { pdf: S(o.pdf) } : {}, taskId: o.taskId ?? B() };
+      if (g.format !== "pdf" && g.format !== "xlsx") throw new y("config", "不支持的报表导出格式");
+      const c = p ? (i) => O(p, i, a) : void 0;
+      if (e.executor) {
+        if (!e.executor.exportPrepared) throw new y("config", "执行器未实现 exportPrepared；请升级执行器或显式使用本地运行时");
+        const i = await e.executor.exportPrepared(g, a, c);
+        return w(t, "maxRows", i.stats.rows), w(t, "maxPages", i.stats.pages), w(t, "maxCells", i.stats.cells), w(t, "maxOutputBytes", i.bytes.byteLength), { ...i, stats: { ...i.stats, outputBytes: i.bytes.byteLength } };
+      }
+      const f = { ...g, signal: a, onEvent: c };
+      if (R(f).runSync("validate", () => ce(f)), e.assets) {
+        const i = await R(f).run("assets", () => j(x.plan, { ...e.assets, signal: a }));
+        x.plan = i.plan, x.diagnostics.push(...k(i.diagnostics));
+      }
+      return _(f, t, l);
+    }),
+    export: (s) => D(s.signal, t.maxDurationMs, async (a) => {
+      const { signal: l, onEvent: m, ...p } = q(s), o = { ...p, xlsx: J(p.xlsx), ...p.pdf ? { pdf: S(p.pdf) } : {}, taskId: p.taskId ?? B() }, x = m ? (f) => O(m, f, a) : void 0, g = { ...o, signal: a, onEvent: x };
+      if (R(g).runSync("validate", () => U(e, o)), o.format !== "pdf" && o.format !== "xlsx") throw new y("config", "不支持的报表导出格式");
+      const c = e.executor ? await e.executor.export(o, a, x) : await n(g);
+      return w(t, "maxRows", c.stats.rows), w(t, "maxPages", c.stats.pages), w(t, "maxCells", c.stats.cells), w(t, "maxOutputBytes", c.bytes.byteLength), { ...c, stats: { ...c.stats, outputBytes: c.bytes.byteLength } };
+    })
+  };
+}
+export {
+  ve as c,
+  N as e
+};

package/dist/sbom.cdx.json

@@ -6,7 +6,7 @@
     "component": {
       "type": "library",
       "name": "@agile-team/mach-report",
-      "version": "2.16.0"
+      "version": "2.18.0"
     },
     "properties": [
       {

package/dist/server/node.d.cts

@@ -2,6 +2,16 @@
 
 import { WorkerOptions as WorkerOptions_2 } from 'node:worker_threads';
 
+declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+
+declare interface AggregateRequest {
+    op: AggregateOperation;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
 declare interface BrowserReportWorker {
     postMessage(value: unknown, transfer?: Transferable[]): void;
     terminate(): void;
@@ -87,6 +97,14 @@ export declare function createNodeAutoReportExporter(options?: Omit<ReportExport
 /** 独立 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>;
 }
@@ -97,6 +115,12 @@ export declare interface FileReportJobStoreOptions extends ReportJobStoreBudgetO
 }
 
 declare interface GridCell {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph[];
     text?: string;
@@ -141,10 +165,15 @@ export declare interface NodeReportExecutorOptions extends ReportWorkerOptions {
     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>;
 
 declare interface PlanComponent {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding;
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions;
     /** Template-only binding; resolved and removed before constructing the output plan. */
@@ -261,6 +290,42 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+
+declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+
+declare interface ReportChartOptions {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+
+declare interface ReportChartSeries {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+
 declare interface ReportDataTarget {
     datasetId: string;
     field: string;
@@ -294,6 +359,41 @@ 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;
@@ -409,18 +509,17 @@ declare interface ReportJobTombstone {
 
 declare type ReportLocalExport = (input: ReportRuntimePreparedExportInput) => Promise<ReportRuntimeExportResult>;
 
+declare type ReportNumberRange = readonly [number, number];
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select" | "multiSelect" | "cascader" | "numberRange";
     /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ReportParamTreeOption[];
     /** 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. */
@@ -433,6 +532,9 @@ declare interface ReportParamDef {
     max?: number | string;
     minLength?: number;
     maxLength?: number;
+    /** multiSelect item count (maximum 100). Cascader paths are bounded to 16 levels. */
+    minItems?: number;
+    maxItems?: number;
 }
 
 declare interface ReportParamIssue {
@@ -442,14 +544,23 @@ declare interface ReportParamIssue {
     message: string;
 }
 
-declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength" | "minItems" | "maxItems";
+
+/** Cascader values are unique within each sibling list. */
+declare interface ReportParamTreeOption {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption[];
+}
+
+declare type ReportParamTypedValue = string | number | string[] | ReportNumberRange;
 
 declare interface ReportParamValidation {
     ok: boolean;
     /** 保留历史取数契约的字符串形式；未知参数保留，不能代替接口权限白名单。 */
     values: Record<string, string>;
     /** JSON Schema 对应的规范值：number 参数转换为有限数字。 */
-    typedValues: Record<string, string | number>;
+    typedValues: Record<string, ReportParamTypedValue>;
     issues: ReportParamIssue[];
 }
 
@@ -477,6 +588,8 @@ declare interface ReportRuntimeBudget {
     maxRows?: number;
     maxPages?: number;
     maxCells?: number;
+    /** Aggregate bound-chart primitives per prepare, before expansion; default 50000, hard maximum 1000000. */
+    maxChartComponents?: number;
     maxOutputBytes?: number;
     /** Bound the plain JSON snapshot accepted by exportPrepared (default 64 MB). */
     maxPreparedBytes?: number;
@@ -499,6 +612,7 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
         sheetMode?: "auto" | "pages" | "continuous";
         valueMode?: "text" | "raw";
         paperSize?: "auto" | "a3" | "a4" | "a5";
+        maxDataBars?: number;
         sheetName?: (sheetIndex: number) => string;
     };
 }

package/dist/server/node.d.ts

@@ -2,6 +2,16 @@
 
 import { WorkerOptions as WorkerOptions_2 } from 'node:worker_threads';
 
+declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+
+declare interface AggregateRequest {
+    op: AggregateOperation;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
 declare interface BrowserReportWorker {
     postMessage(value: unknown, transfer?: Transferable[]): void;
     terminate(): void;
@@ -87,6 +97,14 @@ export declare function createNodeAutoReportExporter(options?: Omit<ReportExport
 /** 独立 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>;
 }
@@ -97,6 +115,12 @@ export declare interface FileReportJobStoreOptions extends ReportJobStoreBudgetO
 }
 
 declare interface GridCell {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph[];
     text?: string;
@@ -141,10 +165,15 @@ export declare interface NodeReportExecutorOptions extends ReportWorkerOptions {
     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>;
 
 declare interface PlanComponent {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding;
     /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
     code?: CodeOptions;
     /** Template-only binding; resolved and removed before constructing the output plan. */
@@ -261,6 +290,42 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+
+declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+
+declare interface ReportChartOptions {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+
+declare interface ReportChartSeries {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+
 declare interface ReportDataTarget {
     datasetId: string;
     field: string;
@@ -294,6 +359,41 @@ 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;
@@ -409,18 +509,17 @@ declare interface ReportJobTombstone {
 
 declare type ReportLocalExport = (input: ReportRuntimePreparedExportInput) => Promise<ReportRuntimeExportResult>;
 
+declare type ReportNumberRange = readonly [number, number];
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select" | "multiSelect" | "cascader" | "numberRange";
     /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ReportParamTreeOption[];
     /** 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. */
@@ -433,6 +532,9 @@ declare interface ReportParamDef {
     max?: number | string;
     minLength?: number;
     maxLength?: number;
+    /** multiSelect item count (maximum 100). Cascader paths are bounded to 16 levels. */
+    minItems?: number;
+    maxItems?: number;
 }
 
 declare interface ReportParamIssue {
@@ -442,14 +544,23 @@ declare interface ReportParamIssue {
     message: string;
 }
 
-declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
+declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength" | "minItems" | "maxItems";
+
+/** Cascader values are unique within each sibling list. */
+declare interface ReportParamTreeOption {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption[];
+}
+
+declare type ReportParamTypedValue = string | number | string[] | ReportNumberRange;
 
 declare interface ReportParamValidation {
     ok: boolean;
     /** 保留历史取数契约的字符串形式；未知参数保留，不能代替接口权限白名单。 */
     values: Record<string, string>;
     /** JSON Schema 对应的规范值：number 参数转换为有限数字。 */
-    typedValues: Record<string, string | number>;
+    typedValues: Record<string, ReportParamTypedValue>;
     issues: ReportParamIssue[];
 }
 
@@ -477,6 +588,8 @@ declare interface ReportRuntimeBudget {
     maxRows?: number;
     maxPages?: number;
     maxCells?: number;
+    /** Aggregate bound-chart primitives per prepare, before expansion; default 50000, hard maximum 1000000. */
+    maxChartComponents?: number;
     maxOutputBytes?: number;
     /** Bound the plain JSON snapshot accepted by exportPrepared (default 64 MB). */
     maxPreparedBytes?: number;
@@ -499,6 +612,7 @@ declare interface ReportRuntimeExportInput extends ReportRuntimeInput {
         sheetMode?: "auto" | "pages" | "continuous";
         valueMode?: "text" | "raw";
         paperSize?: "auto" | "a3" | "a4" | "a5";
+        maxDataBars?: number;
         sheetName?: (sheetIndex: number) => string;
     };
 }