@worm-vue3-print/core 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+import { T as TemplateData, C as CodeRenderer, P as PageLayout, I as MeasuredElement, J as TemplateElement, W as WatermarkOptions, K as PaperMm, L as ViewportPx, N as HeightSource, O as MarginsMm, Q as PdfTargetSpec, X as ScreenshotTargetSpec, R as RawMeasurement, a as CodeSpec, Y as CodeRenderOptions, D as DriverFactory, Z as ExecutorBundle, _ as TileLayout, $ as PrintJob, a0 as PreparedDocument, a1 as RenderPdfResult, M as MultiPageTemplateData, a2 as PrintFontDeclaration } from './driver-CsWkGK4a.js';
+export { a3 as ContinuousPaperSize, a4 as EXECUTOR_TARGETS, a5 as ExecutorMethod, a6 as ExecutorTargetKind, a7 as FALLBACK_FONT_STACK, a8 as MAX_BATCH_COPIES, a9 as NormalizedPrintData, aa as PAPER_DIMENSIONS, ab as PageDriver, ac as PageSection, ad as PaperSize, ae as PrintDataInput, af as PrintFontFile, ag as RenderCell, ah as RenderRequest, ai as RenderRow, aj as SheetPaperSize, ak as TILE_DEFAULTS, G as TextFit, al as TilingError, am as TilingIssue, an as TilingIssueCode, ao as TilingOptions, ap as TilingResolveOptions, aq as TilingTemplateInput, ar as buildFontFaceCss, as as computeMaxColumns, at as computeTileLayout, au as escapeInlineStyleValue, av as getPaperDimensions, aw as isContinuousPaper, ax as isContinuousPaperSize, ay as normalizePrintData, az as normalizeTilingOptions, aA as resolveSheetMm, aB as roundMm, aC as tilePosition, aD as toFontFamilyStack, aE as validateTiling } from './driver-CsWkGK4a.js';
+import { F as FitFontSize, P as PrintRuntime } from './ports-B63x7kCX.js';
+export { C as CellFitRowKind, h as DEFAULT_READINESS_MS, D as DEFAULT_SHRINK_MIN_FONT_SIZE_PT, i as DEFAULT_TIMEOUT_MS, M as MIN_SHRINK_FONT_SIZE_PT, j as MeasureResult, k as PrintSession, S as SessionBudget, c as cellFitCapMm, a as cellFitKey, f as floorFontSize, p as parseCellFitKey, r as resolveCellTextFit, d as resolveElementTextFit, e as resolveShrinkMinFontSize, g as roundFontSize } from './ports-B63x7kCX.js';
+
 type TokenType = 'num' | 'str' | 'bool' | 'ident' | 'punc';
 interface Token {
     type: TokenType;
@@ -126,201 +131,42 @@ declare const systemVars: {
     printTime: () => number;
 };
 
-type PaperSize = 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'CUSTOM';
-/** 纸张尺寸映射（mm） */
-declare const PAPER_DIMENSIONS: Record<PaperSize, {
-    width: number;
-    height: number;
-}>;
-interface TemplateData {
-    paperSize: PaperSize;
-    orientation: 'portrait' | 'landscape';
-    /** 自定义纸张宽度（mm），仅 paperSize='CUSTOM' 时生效 */
-    customWidth?: number;
-    /** 自定义纸张高度（mm），仅 paperSize='CUSTOM' 时生效 */
-    customHeight?: number;
-    /** 页面（纸张）背景色；未设置时默认白色 */
-    pageBackground?: string;
-    margins: {
-        top: number;
-        right: number;
-        bottom: number;
-        left: number;
-    };
-    header: {
-        height: number;
-        elements: TemplateElement[];
-    };
-    footer: {
-        height: number;
-        elements: TemplateElement[];
-    };
-    firstPageOverlay: {
-        height: number;
-        elements: TemplateElement[];
-    };
-    elements: TemplateElement[];
-}
-/** 元素分页属性（非表格元素） */
-interface PaginationConfig {
-    pageable: boolean;
-    keepWithNext: boolean;
-}
-/** 表格分页配置 */
-interface TablePaginationConfig {
-    enabled: boolean;
-}
 /**
- * 模板元素 — print-render 侧的简化视图。
- * 兼容前端 PrintElementData 的 options 嵌套结构，
- * 同时提供扁平访问器方便分页引擎使用。
- */
-interface TemplateElement {
-    id: string;
-    type: string;
-    /** 元素选项（与前端 ElementOptions 对齐） */
-    options: Record<string, any>;
-    /** 元素类型元数据（与前端 PrintElementTypeMeta 对齐） */
-    printElementType?: {
-        type: string;
-        title?: string;
-        [key: string]: any;
-    };
-    /** 分页属性（非表格元素） */
-    pagination?: PaginationConfig;
-    /** 表格分页配置（表格元素） */
-    tablePagination?: TablePaginationConfig;
-}
-type RenderRowType = 'header' | 'data' | 'summary' | 'subtotal' | 'static';
-interface RenderCellBorder {
-    width: number;
-    style: string;
-    color: string;
-}
-interface RenderCellBorders {
-    top?: RenderCellBorder;
-    right?: RenderCellBorder;
-    bottom?: RenderCellBorder;
-    left?: RenderCellBorder;
-}
-/** 绑定后的单元格：content 已是最终文本（小计行 content 为占位值，真实值按每页数据渲染时求值） */
-interface RenderCell {
-    content: string;
-    /** 小计行专用：单元格原始 formatter 表达式，渲染阶段以当前页数据行上下文求值 */
-    rawFormatter?: string;
-    /** 内容类型：text（默认）/ barcode / qrcode / image，非 text 时 content 为码值或图片 URL */
-    cellType?: string;
-    /** 条形码码制（jsbarcode 格式名），仅 cellType='barcode' 时生效 */
-    barcodeType?: string;
-    /** 二维码纠错级别 L/M/Q/H，仅 cellType='qrcode' 时生效 */
-    qrCodeLevel?: string;
-    /** 条形码下方是否显示文本，仅 cellType='barcode' 时生效 */
-    showBarcodeText?: boolean;
-    /** 图片缩放模式，仅 cellType='image' 时生效 */
-    fit?: string;
-    /** 图片最大宽度（mm），仅 cellType='image' 时生效 */
-    maxWidth?: number;
-    /** 图片最大高度（mm），仅 cellType='image' 时生效 */
-    maxHeight?: number;
-    rowspan: number;
-    colspan: number;
-    merged: boolean;
-    align?: string;
-    valign?: string;
-    fontSize?: number;
-    fontWeight?: string;
-    color?: string;
-    backgroundColor?: string;
-    borders?: RenderCellBorders;
-    padding?: number;
-    wordWrap?: boolean;
-}
-/** 绑定后的渲染行，存入 options._renderRows */
-interface RenderRow {
-    type: RenderRowType;
-    height: number;
-    cells: RenderCell[];
-}
-interface CodeRenderOptions {
-    /** 条形码码制（jsbarcode 格式名），仅 barcode 类型使用 */
-    barcodeType?: string;
-    /** 二维码纠错级别 L/M/Q/H，仅 qrcode 类型使用 */
-    qrCodeLevel?: string;
-    /** 条形码下方是否显示文本 */
-    showText?: boolean;
-    /** 条码模块宽度倍率 */
-    barWidth?: number;
-    /** 条码下方文本字号（pt） */
-    fontSize?: number;
-}
-/**
- * 码值 → SVG 字符串渲染器。
- * 服务端由 print-render 用 bwip-js 实现；浏览器由 print-canvas 用 jsbarcode/qrcode 实现。
- * 码值非法时抛出异常，由调用方降级为文本占位。
+ * 将模板中元素的 formatter 表达式求值为实际值。
+ * 返回新的模板对象（深拷贝），不修改原始模板。
+ *
+ * @param baseUrl 相对路径**图片**基址（如 `/n/...`）
+ * @param fontBaseUrl 相对路径**字体**基址；缺省回落到 `baseUrl`（图片与字体同域时无需单独配置），
+ *   显式传空串表示不拼接——相对字体 URL 交由文档自身 origin 解析（浏览器端语义）。
+ *   字体与图片不在同一域（图片走业务 OSS、字体走前端站点/CDN）时必须显式指定。
  */
-interface CodeRenderer {
-    render(value: string, cellType: 'barcode' | 'qrcode', opts?: CodeRenderOptions): string;
-}
-interface RenderRequest {
-    templateJson: TemplateData;
-    printData?: Record<string, any>;
-    /** 服务端对外访问 base URL，用于把 /docfiles/... 等相对路径图片拼接为完整地址 */
-    baseUrl?: string;
-}
-interface MeasuredElement {
-    id: string;
-    measuredHeight: number;
-    /** 表格每行实际高度（mm），仅表格元素有值 */
-    measuredRowHeights?: number[];
-    /** 重复表头段实际高度（mm）= 前 _repeatHeaderCount 个渲染行高之和，仅表格元素有值 */
-    repeatHeaderHeight?: number;
-}
-interface PageLayout {
+declare function bindData(template: TemplateData, printData?: Record<string, any>, baseUrl?: string, fontBaseUrl?: string): TemplateData;
+/** 系统变量上下文（表达式 ctx 与 HTML 占位符替换共用，保证取值一致） */
+interface SystemVariableContext {
+    /** 打印日期 YYYY-MM-DD */
+    printDate: string;
+    /** 打印时间 HH:mm:ss */
+    printTime: string;
     pageIndex: number;
-    sections: PageSection[];
-}
-interface PageSection {
-    elementId: string;
-    type: 'element' | 'table-slice' | 'flow-group';
-    /** table-slice 专用：渲染行起始索引（含表头行） */
-    startRow?: number;
-    /** table-slice 专用：渲染行结束索引（不含） */
-    endRow?: number;
-    /** table-slice 专用：非首片时在切片前重复表头段 */
-    repeatHeader?: boolean;
-    /** table-slice 专用：本片末尾是否渲染小计行（当前页数据小计，每页重复） */
-    subtotal?: boolean;
-    /** table-slice 专用：本片末尾是否渲染整表汇总行（总计，仅最后一页） */
-    summary?: boolean;
-    /** 本节在本页内容区内的实际 top（mm）。发生换页后的内容为 0；缺省回退元素设计 top */
-    renderTop?: number;
-    /**
-     * flow-group 专用：相对容器在本页的实际 top（mm），覆盖元素设计 top。
-     * 同页时 = 表格设计 top（容器顶部对齐表格 slice 顶部）；
-     * 跟随区整体移页时 = 新页内容区顶部（0）。
-     */
-    groupTop?: number;
-    /** flow-group 专用：跟随区成员元素 id（容器内按文档流渲染） */
-    followElementIds?: string[];
+    totalPages: number;
 }
-/** 获取纸张物理尺寸（考虑方向） */
-declare function getPaperDimensions(template: TemplateData): {
-    width: number;
-    height: number;
-};
-
 /**
- * 将模板中元素的 formatter 表达式求值为实际值。
- * 返回新的模板对象（深拷贝），不修改原始模板。
+ * 生成系统变量取值；水印表达式求值与最终 HTML 占位符替换共用同一实现，
+ * 避免「设计器预览看到的打印时间」与「实际打印出来的」不一致。
  */
-declare function bindData(template: TemplateData, printData?: Record<string, any> | Record<string, any>[], baseUrl?: string): TemplateData;
-declare function injectSystemVariables(html: string): string;
+declare function resolveSystemVariables(now?: Date, page?: {
+    pageIndex?: number;
+    totalPages?: number;
+}): SystemVariableContext;
+declare function injectSystemVariables(html: string, now?: Date): string;
 
 interface GenerateOptions {
     /** 第一遍测量模式：所有元素在一个连续区域，不分页 */
     isMeasurementPass?: boolean;
     /** 条码/二维码 SVG 渲染器；缺省或渲染抛错时降级为文本占位 */
     codeRenderer?: CodeRenderer;
+    /** 连续纸探针推导出的最终纸高（mm）；仅最终生成时传入，使 @page/.print-page/footer 对齐 */
+    pageHeightMm?: number;
 }
 /**
  * 生成完整 HTML 字符串。
@@ -329,14 +175,36 @@ interface GenerateOptions {
  * - 第二遍：按分页结果生成多页 HTML，填充 {pageIndex}/{totalPages}
  */
 declare function generateHtml(template: TemplateData, pageLayouts: PageLayout[], printData?: Record<string, any>, options?: GenerateOptions): string;
+/** renderFinalPages 的扩展选项（多页面模板：全局页码 + 页面作用域类） */
+interface RenderFinalPagesOptions {
+    /** 全局页码偏移：模板在整份文档中的起始页号（0 基页号偏移）；缺省 0（单模板） */
+    pageOffset?: number;
+    /** 整份文档总页数（多页面模板）；缺省 = 本模板页数（单模板） */
+    totalPages?: number;
+    /** 追加到每个 .print-page 的类名（多页面模板 CSS 作用域，如 'mt-1'）；缺省空 */
+    pageClass?: string;
+}
 
 /** mm 值转 CSS 字符串 */
 declare function mm(value: number): string;
+/** 模板无关的基础 CSS（多页文档外壳用；不含 @page，@page 由首模板单独输出） */
+declare function buildBasePageCss(): string;
+/** @page 规则 CSS（纸张尺寸，含连续纸推导纸高）。@page 无法作用域化，多页文档由首个模板输出一份 */
+declare function buildPageRuleCss(template: TemplateData, pageHeightMm?: number): string;
+/**
+ * 模板相关几何 CSS，可按作用域前缀输出（多页时每页模板一份）。
+ * @param scope 页面作用域类选择器（如 '.mt-3'）；缺省输出原始选择器
+ * @param pageHeightMm 连续纸推导纸高（mm）；普通纸不传
+ */
+declare function buildPageGeometryCss(template: TemplateData, scope?: string, pageHeightMm?: number): string;
 /**
  * 生成完整的打印页面 CSS。
  * 包含纸张尺寸、边距、页眉页脚、内容区、首页叠加区域等样式。
+ * 出纸旋转角度非 0（固定纸）时，额外输出 .print-page-rotor / .print-page-rotor-${angle} 转子规则完成整页旋转。
+ * @param pageHeightMm 连续纸由浏览器探针推导出的最终纸高（mm）；传入时替换模板纸张高度，
+ *                     使 @page/.print-page/footer 全部对齐该高度。普通纸不传。
  */
-declare function buildPageCss(template: TemplateData): string;
+declare function buildPageCss(template: TemplateData, pageHeightMm?: number): string;
 /**
  * 生成内联样式：元素绝对定位（mm 单位）。
  * 可选 z-index：与设计器「层级」一致，未设置（undefined）时不输出（层叠回退 DOM 顺序）。
@@ -374,6 +242,307 @@ declare function safeEval(expr: string, context: Record<string, any>): any;
  */
 declare function evaluateTemplate(text: string, ctx: Record<string, any>): string;
 
+/** 连续纸推导高度下限：1 英寸（25.4mm），避免过矮被打印驱动拒绝 */
+declare const MIN_CONTINUOUS_HEIGHT_MM = 25.4;
+declare function composeContinuousHeight(template: TemplateData, contentBottomMm: number): number;
+
+/** 96dpi 下 1mm 对应的 CSS px 数（瓦片尺寸仍以 px 配置，落纸时换算为 mm） */
+declare const PX_PER_MM: number;
+/** 1 CSS px 对应的 mm 数 */
+declare const MM_PER_PX: number;
+/** 水印默认值（与设计器 CanvasPaper 历史行为一致） */
+declare const WATERMARK_DEFAULTS: {
+    readonly color: "#cccccc";
+    readonly opacity: 0.15;
+    readonly rotate: -30;
+    /** 瓦片默认尺寸（px）：决定平铺疏密，默认 260×180 */
+    readonly tileWidth: 260;
+    readonly tileHeight: 180;
+    /** 瓦片下限（px），防止文字裁剪/异常平铺 */
+    readonly minTileWidth: 140;
+    readonly minTileHeight: 100;
+    /** 瓦片字号固定 16px：密度只改变平铺疏密，不改字体大小 */
+    readonly fontSize: 16;
+};
+/** 密度预设：调大瓦片 → 更疏；调小 → 更密 */
+declare const WATERMARK_DENSITY_PRESETS: Record<string, {
+    width: number;
+    height: number;
+    label: string;
+}>;
+/** 水印是否可见（向后兼容：无 mode 时按 fixed，content 非空即显示） */
+declare function isWatermarkVisible(wm?: WatermarkOptions | null): boolean;
+/**
+ * 解析水印文本。
+ * - fixed：取 content；
+ * - binding：支持字段路径（order.no）、花括号表达式（{order.no}、CONCAT/DATE(...)），
+ *   取不到值时依次回退 testData → [binding]；
+ * - 表达式可直接使用系统变量（{printDate} 打印日期、{printTime} 打印时间、
+ *   {pageIndex} 当前页码、{totalPages} 总页数）——即表达式弹框「变量」里的选项；
+ * - timestamp 开启时追加时间（format 指定格式，缺省 YYYY-MM-DD HH:mm），
+ *   为存量模板保留，配置面板已不再提供该开关（改用 {printDate}/{printTime}）。
+ */
+declare function resolveWatermarkText(wm: WatermarkOptions | undefined, printData?: Record<string, any> | Record<string, any>[], systemVars?: Partial<SystemVariableContext>): string;
+/** 时间格式化：token 支持 YYYY/MM/DD/HH/mm/ss，缺省 YYYY-MM-DD HH:mm */
+declare function formatTimestamp(format?: string): string;
+/** 纸张尺寸（mm） */
+interface WatermarkPaper {
+    width: number;
+    height: number;
+}
+/** 单块瓦片在纸面坐标系中的位置与尺寸（mm，左上角原点） */
+interface WatermarkTile {
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+}
+/** 水印解析结果：文本 + 视觉参数 + 完整瓦片网格（HTML 与设计器画布共用同一份几何） */
+interface ResolvedWatermark {
+    text: string;
+    color: string;
+    rotate: number;
+    opacity: number;
+    /** 瓦片内字号（px，viewBox 用户单位；不随密度变化） */
+    fontSizePx: number;
+    /** 瓦片尺寸（px，viewBox 用户单位；密度配置的原值） */
+    tileWidthPx: number;
+    tileHeightPx: number;
+    tileWidthMm: number;
+    tileHeightMm: number;
+    columns: number;
+    rows: number;
+    tiles: WatermarkTile[];
+}
+/**
+ * 解析水印并生成瓦片网格。
+ * - 不可见（未配置/文本为空）返回 null；
+ * - 网格覆盖整张纸：列数 = ceil(纸宽/瓦片宽)，行数 = ceil(纸高/瓦片高)，
+ *   末列/末行超出部分由 .watermark-layer 的 overflow:hidden 裁掉（与背景平铺语义一致）。
+ *
+ * @param paperMm 最终纸张尺寸（mm）；连续纸须传探针推导后的纸高，保证网格与 @page 同源。
+ */
+declare function resolveWatermarkLayout(wm: WatermarkOptions | undefined, printData: Record<string, any> | Record<string, any>[] | undefined, paperMm: WatermarkPaper, systemVars?: Partial<SystemVariableContext>): ResolvedWatermark | null;
+/**
+ * 生成单块瓦片的 `<svg>` 标记。
+ * viewBox 用瓦片 px 坐标（字号 16px 等视觉参数不变），width/height 用 mm 落纸，
+ * 因此瓦片在纸面上的物理尺寸恰好等于密度配置值。
+ */
+declare function renderWatermarkTileSvg(layout: ResolvedWatermark, tile: WatermarkTile): string;
+/**
+ * 生成单页水印层 HTML（放在 .print-page 内、所有内容之下的最底层）。
+ * 不可见/文本为空时返回空串。
+ */
+declare function renderWatermarkLayerHtml(wm: WatermarkOptions | undefined, printData: Record<string, any> | Record<string, any>[] | undefined, paperMm: WatermarkPaper, systemVars?: Partial<SystemVariableContext>): string;
+
+/** 1mm = 1000µm（协议与任务记录使用微米） */
+declare const MICROMETERS_PER_MM = 1000;
+/** 1in = 25.4mm = 25400µm（Electron printToPDF 的 pageSize 使用英寸） */
+declare const MM_PER_INCH = 25.4;
+declare const MICROMETERS_PER_INCH = 25400;
+declare function pxToMm(px: number): number;
+declare function mmToPx(mm: number): number;
+declare function millimetersToMicrometers(mm: number): number;
+declare function micrometersToMillimeters(um: number): number;
+declare function millimetersToInches(mm: number): number;
+
+/** core 统一失败分类；各端只做映射，不新增协议码 */
+type PrintFailureCode = 'INVALID_PAPER' | 'MEASURE_FAILED' | 'RENDER_TIMEOUT' | 'PDF_FAILED' | 'SCREENSHOT_FAILED' | 'UNSUPPORTED_RUNTIME' | 'INTERNAL';
+declare class PrintFailure extends Error {
+    readonly code: PrintFailureCode;
+    readonly cause?: unknown;
+    constructor(code: PrintFailureCode, message: string, cause?: unknown);
+}
+declare function toPrintFailure(err: unknown, fallbackCode: PrintFailureCode, context: string): PrintFailure;
+declare function withTimeout<T>(task: Promise<T>, ms: number, code: PrintFailureCode, message: string): Promise<T>;
+
+/** 宿主纸张覆盖（mm）；字段为 0 或负数视为未提供 */
+interface PaperOverride {
+    width?: number;
+    height?: number;
+}
+interface ResolvePaperInput {
+    /** core 计算出的纸尺寸：连续纸为探针推导高度，其余为模板纸张 */
+    paperMm: PaperMm;
+    continuous: boolean;
+    override?: PaperOverride;
+}
+/** 连续纸 HTML 纸高逃生门：显式 paperHeightMm 优先于协议覆盖高度 */
+declare function escapeHeightMm(input: {
+    paperHeightMm?: number;
+    override?: PaperOverride;
+}): number | undefined;
+/**
+ * 应用宿主覆盖并给出纸高来源。
+ * 连续纸仅覆盖宽度时，高度仍取推导值且来源保持 derived（不可降级为 config）。
+ */
+declare function resolvePaperMm(input: ResolvePaperInput): {
+    paperMm: PaperMm;
+    heightSource: HeightSource;
+};
+/** 测量容器尺寸（CSS px）；三端必须使用同一结果 */
+declare function paperViewportPx(paper: PaperMm): ViewportPx;
+
+/** 边距恒为零：边距由 core 生成的 HTML padding 控制，避免两层边距叠加 */
+declare function buildPdfTargetSpec(paperMm: PaperMm): PdfTargetSpec;
+/** Electron.PrintToPDFOptions 的最小结构（pageSize/margins 单位均为英寸） */
+interface ElectronPrintToPdfOptions {
+    margins: MarginsMm;
+    pageSize: {
+        width: number;
+        height: number;
+    };
+    printBackground: boolean;
+    scale: number;
+    preferCSSPageSize: boolean;
+}
+declare function toElectronPrintToPdfOptions(spec: PdfTargetSpec): ElectronPrintToPdfOptions;
+/** Playwright page.pdf 的最小结构（宽高与边距使用 mm 字符串） */
+interface PlaywrightPdfOptions {
+    width: string;
+    height: string;
+    margin: {
+        top: string;
+        right: string;
+        bottom: string;
+        left: string;
+    };
+    printBackground: boolean;
+    preferCSSPageSize: boolean;
+}
+declare function toPlaywrightPdfOptions(spec: PdfTargetSpec): PlaywrightPdfOptions;
+/** Playwright page.screenshot 的最小结构 */
+declare function buildScreenshotTargetSpec(): ScreenshotTargetSpec;
+
+/**
+ * 原始测量 → 分页输入。三端共用：px→mm、表格行高、重复表头段高度。
+ * repeatHeaderHeight = 前 `options._repeatHeaderCount` 个渲染行高之和。
+ */
+declare function normalizeMeasurements(raw: RawMeasurement[], template: TemplateData): Map<string, MeasuredElement>;
+
+/**
+ * 把自动缩小结果写回模板（原地修改）。
+ * 元素级 key 命中元素 options._fitFontSize；单元格 key 命中渲染行单元格 fittedFontSize。
+ * 未命中的 key 静默跳过：元素可能属于未参与测量的区域，不影响其余结果。
+ */
+declare function applyTextFitSizes(template: TemplateData, fits: FitFontSize[] | undefined): void;
+
+/** 码值 + 码制 + 影响产物几何的选项 → 稳定键（顺序固定，跨进程可比对） */
+declare function codeSpecKey(value: string, cellType: 'barcode' | 'qrcode', opts?: CodeRenderOptions): string;
+/** 映射渲染器：未命中抛错，由 html-generator 的既有降级逻辑输出文本占位 */
+declare function createMapCodeRenderer(map: Map<string, string>): CodeRenderer;
+interface CollectingCodeRenderer {
+    /** 传入 generateHtml 的渲染器：命中基映射则返回，否则记录规格并抛错 */
+    renderer: CodeRenderer;
+    /** 取走本趟收集到的规格并清空 */
+    takeSpecs(): CodeSpec[];
+}
+declare function createCollectingCodeRenderer(base?: Map<string, string>): CollectingCodeRenderer;
+/** 合并多趟码值映射；后者覆盖同键，入参不被修改 */
+declare function mergeCodeMaps(...maps: Array<Map<string, string>>): Map<string, string>;
+
+/**
+ * 共享 DOM 宿主 runtime：把「载入 → 注入 → 等就绪 → 执行 → 释放」的时序、
+ * 超时预算与错误分类集中实现一次。三端只提供 driver。
+ */
+declare function createDomHostRuntime(factory: DriverFactory, bundle?: ExecutorBundle): PrintRuntime;
+
+interface BatchCopyInput {
+    /** 该份数据绑定后的模板 */
+    bound: TemplateData;
+    pageLayouts: PageLayout[];
+    /** 该份原始数据（水印层使用） */
+    data: Record<string, any>;
+    codeRenderer?: CodeRenderer;
+    /** 连续纸探针推导出的纸高（mm）；固定纸为 undefined */
+    derivedHeightMm?: number;
+    paperMm: PaperMm;
+    /** 纸高来源（透传，合并器不使用） */
+    heightSource: HeightSource;
+}
+/**
+ * 将多份单份产物合并为一个 HTML 文档；份间强制分页。
+ * 同模板各份纸张宽度/边距一致，固定纸共用单一 @page；连续纸走命名页。
+ */
+declare function composeBatchHtml(copies: BatchCopyInput[]): {
+    html: string;
+    pageCount: number;
+    copyPaperMm: PaperMm[];
+};
+
+interface TileInput {
+    /** 该份数据绑定后的模板 */
+    bound: TemplateData;
+    /** 该份的分页结果；拼版要求恰好 1 页（由管线在调用前校验） */
+    pageLayouts: PageLayout[];
+    /** 该份原始数据（水印层使用） */
+    data: Record<string, any>;
+    codeRenderer?: CodeRenderer;
+}
+/**
+ * 把各份标签页按行优先铺进目标纸。
+ * 每张固定容纳 layout.perSheet 格；放不满的最后一张留白（空位不输出任何内容）。
+ */
+declare function composeTiledHtml(input: {
+    copies: TileInput[];
+    layout: TileLayout;
+}): {
+    html: string;
+    sheetCount: number;
+    perSheet: number;
+};
+
+/** 阶段 1–6：绑定 → 码值收集/渲染 → 测量 → 分页 → 连续纸 → 最终 HTML */
+declare function prepareDocument(job: PrintJob, runtime: PrintRuntime): Promise<PreparedDocument>;
+/** 阶段 1–7：prepared + HTML→PDF，且与准备阶段共用同一个 driver 会话 */
+declare function renderPdf(job: PrintJob, runtime: PrintRuntime): Promise<RenderPdfResult>;
+/** 截图：不分页，用测量模式 HTML 单页完整渲染；数组数据仅渲染首条。不参与拼版（仍是标签纸单页快照） */
+declare function renderScreenshot(job: PrintJob, runtime: PrintRuntime): Promise<Uint8Array>;
+
+/**
+ * 归一化模板为页面模板数组：
+ * - 单模板（TemplateData）→ `[t]`，路径不变；
+ * - 多页面模板（{ pages }）→ 展开 pages，执行多模板校验；
+ * - `pages` 恰好 1 页时按单模板语义返回（保持一致性）。
+ *
+ * 校验在 pipeline 入口统一抛出，render 服务与设计器预览共用。
+ */
+declare function normalizeTemplate(templateJson: TemplateData | MultiPageTemplateData): TemplateData[];
+/** 是否多页面模板 wrapper（含 pages 数组）；与 normalizeTemplate 的判据一致 */
+declare function isMultiPageTemplate(templateJson: TemplateData | MultiPageTemplateData): templateJson is MultiPageTemplateData;
+/**
+ * 合并各页模板的字体声明：按 font-family 名去重，保留首个。
+ * 三端据此生成同一份 @font-face，不依赖各端系统字体。
+ */
+declare function mergeFontDeclarations(pages: TemplateData[]): PrintFontDeclaration[];
+/** 多页面模板单份产物（对应一份业务数据） */
+interface MultiPageCopyInput {
+    /** 该份数据绑定后的页面模板（顺序与模板一致；formatter 已求值） */
+    boundPages: TemplateData[];
+    /** 各页面模板的分页结果（顺序与模板一致） */
+    layoutsPerPage: PageLayout[][];
+    /** 该份原始数据（水印层使用） */
+    data: Record<string, any>;
+    /** 各页面模板的码值渲染器（顺序与模板一致）；缺省降级文本占位 */
+    codeRenderers?: Array<CodeRenderer | undefined>;
+}
+interface MultiPageDocument {
+    html: string;
+    pageCount: number;
+    /** 展平的全局页码 PageLayout（调试用；pageIndex 份内全局连续） */
+    pageLayouts: PageLayout[];
+}
+/**
+ * 组合多页面模板整份文档（单份或多份批量）。
+ *
+ * 语义：
+ * - 每份数据 = 一份完整多页文档（封面+内容+条款），页码份内全局连续；
+ * - 每个页面模板产出整页 .print-page 序列，模板间即整页边界（下一模板必然新开一页）；
+ * - 各页模板的字体声明合并、几何 CSS 按 .mt-N 作用域化；
+ * - CSS 按模板集合计算一次（各份模板结构相同），份间仅拼接片段。
+ */
+declare function composeMultiPageDocument(copies: MultiPageCopyInput[]): MultiPageDocument;
+
 declare class TemplateEngine {
     private functions;
     constructor(options?: EngineOptions);
@@ -382,4 +551,4 @@ declare class TemplateEngine {
     render(template: string, context: Record<string, any>): string;
 }
 
-export { type ASTNode, type CodeRenderOptions, type CodeRenderer, type EngineOptions, type ExprFunction, type GenerateOptions, type MeasuredElement, PAPER_DIMENSIONS, type PageLayout, type PageSection, type PaperSize, type TemplateData as PrintTemplateData, type TemplateElement as PrintTemplateElement, type RenderCell, type RenderRequest, type RenderRow, type TemplateAST, TemplateEngine, avg, bindData, buildPageCss, compileTemplate, count, elementPositionStyle, evaluate, evaluateTemplate, formatDate, formatMoney, generateHtml, getByPath, getPaperDimensions, ifFn, injectSystemVariables, max, min, mm, paginate, parse, parseTemplate, renderTemplate, safeEval, setPageIndex, setTotalPages, sum, systemVars, tableDesignBottom, toUpperCaseAmount, tokenize };
+export { type ASTNode, type BatchCopyInput, CodeRenderOptions, CodeRenderer, CodeSpec, type CollectingCodeRenderer, DriverFactory, type ElectronPrintToPdfOptions, type EngineOptions, ExecutorBundle, type ExprFunction, FitFontSize, type GenerateOptions, HeightSource, MICROMETERS_PER_INCH, MICROMETERS_PER_MM, MIN_CONTINUOUS_HEIGHT_MM, MM_PER_INCH, MM_PER_PX, MarginsMm, MeasuredElement, type MultiPageCopyInput, type MultiPageDocument, MultiPageTemplateData, PX_PER_MM, PageLayout, PaperMm, type PaperOverride, PdfTargetSpec, type PlaywrightPdfOptions, PreparedDocument, PrintFailure, type PrintFailureCode, PrintFontDeclaration, PrintJob, PrintRuntime, TemplateData as PrintTemplateData, TemplateElement as PrintTemplateElement, RawMeasurement, type RenderFinalPagesOptions, RenderPdfResult, type ResolvePaperInput, type ResolvedWatermark, ScreenshotTargetSpec, type SystemVariableContext, type TemplateAST, TemplateEngine, type TileInput, TileLayout, ViewportPx, WATERMARK_DEFAULTS, WATERMARK_DENSITY_PRESETS, WatermarkOptions, type WatermarkPaper, type WatermarkTile, applyTextFitSizes, avg, bindData, buildBasePageCss, buildPageCss, buildPageGeometryCss, buildPageRuleCss, buildPdfTargetSpec, buildScreenshotTargetSpec, codeSpecKey, compileTemplate, composeBatchHtml, composeContinuousHeight, composeMultiPageDocument, composeTiledHtml, count, createCollectingCodeRenderer, createDomHostRuntime, createMapCodeRenderer, elementPositionStyle, escapeHeightMm, evaluate, evaluateTemplate, formatDate, formatMoney, formatTimestamp, generateHtml, getByPath, ifFn, injectSystemVariables, isMultiPageTemplate, isWatermarkVisible, max, mergeCodeMaps, mergeFontDeclarations, micrometersToMillimeters, millimetersToInches, millimetersToMicrometers, min, mm, mmToPx, normalizeMeasurements, normalizeTemplate, paginate, paperViewportPx, parse, parseTemplate, prepareDocument, pxToMm, renderPdf, renderScreenshot, renderTemplate, renderWatermarkLayerHtml, renderWatermarkTileSvg, resolvePaperMm, resolveSystemVariables, resolveWatermarkLayout, resolveWatermarkText, safeEval, setPageIndex, setTotalPages, sum, systemVars, tableDesignBottom, toElectronPrintToPdfOptions, toPlaywrightPdfOptions, toPrintFailure, toUpperCaseAmount, tokenize, withTimeout };