@k-table/sheet-core 0.0.1 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2076 @@
+import { SheetTemplateState, TextRun, CellData as CellData$1, BaseTemplateCellBinding, PageSettings as PageSettings$1, PageMarginsCm, SheetPaperKind, SheetOrientation, MergeRange } from './sheet-template-model.js';
+import { T as TemplateFieldRegistry, A as AggregateEmptyAs, W as WorkbookScripts, a as WorkbookMeta, b as WorkbookNamedRange, K as KtTemplateRoot, M as MergeRect, B as BorderWidth, c as BorderPattern, S as Sheet, C as CellData, P as PageSettings, d as SheetItem, e as Workbook, F as FormulaCatalogTarget, f as FormulaCatalogEntry, g as TemplateFieldDef, h as TemplateSubFieldDef } from './types-9rRrxBdg.js';
+export { i as BusinessSheetProfile, j as BusinessSheetProfiles, k as CREATION_MODE, l as CellBorderSide, m as CellBorders, n as CellStyle, o as CreationMode, D as DEFAULT_COMPUTE_POLICY, p as DRAFT_KIND, q as DerivedFieldRule, r as DraftDbSpliceMeta, s as DraftKind, t as FormulaCatalog, H as HorizontalAlign, u as KtTemplateBinding, v as KtTemplateFlexibleRowSegment, w as KtTemplateMainField, x as KtTemplateSlotRect, y as KtTemplateSpliceSpec, z as KtTemplateSubTable, E as KtTemplateSubTableColumn, G as PaperSizeName, R as RichRun, I as SNAPSHOT_KIND, J as SPLICE_COLUMN_MODE, L as SnapshotKind, N as SpliceComposeCacheV1, O as SubTableSlotConfig, Q as SubTableSlotConfigEntry, U as TEMPLATE_FIELD_REGISTRY_VERSION, V as VerticalAlign, X as WORKBOOK_META_BUSINESS_SHEET_PROFILES, Y as WORKBOOK_META_INHERIT_SOURCE_BASE_SNAPSHOT_ROW_ID, Z as WorkbookComputePolicy, _ as WorkbookReportBandDef, $ as WorkbookReportMeta, a0 as WorkbookScriptBlock, a1 as WorkbookScriptHook, a2 as emptyFormulaCatalog, a3 as getAggregateEmptyAs, a4 as getFormulaCatalogFromMeta, a5 as getWorkbookComputePolicy, a6 as getWorkbookDerivedRules, a7 as newDerivedRuleId, a8 as normalizeComputePolicy, a9 as normalizeDerivedRules, aa as normalizeFormulaCatalog } from './types-9rRrxBdg.js';
+import { SignatureKind, SignatureResult, SignatureSpec } from '@k-table/sheet-host';
+export { SignatureKind, SignaturePort, SignatureResult, SignatureSpec } from '@k-table/sheet-host';
+
+/** 画布缩放限制（与旧 sheetEngineStore 行为一致）。 */
+declare function clampZoom(z: number): number;
+
+/** 引擎可调参数（与实现计划 A0-2 对齐）。 */
+declare const SHEET_ENGINE_CONFIG: {
+    readonly DEFAULT_ROW_COUNT: 200;
+    readonly DEFAULT_COL_COUNT: 50;
+    readonly MAX_ROWS: 1048576;
+    readonly MAX_COLS: 16384;
+    readonly DEFAULT_ROW_HEIGHT: 24;
+    readonly DEFAULT_COL_WIDTH: 80;
+    readonly HEADER_ROW_HEIGHT: 24;
+    readonly HEADER_COL_WIDTH: 48;
+    readonly MIN_FONT_SIZE_PT: 6;
+    readonly DEFAULT_FONT_SIZE_PT: 11;
+};
+
+/**
+ * 用户可见坐标（1-based 行、A.. 列）与内部 0-based `r,c` 的**唯一**转换层。
+ * 见实现计划核心引擎A §3.0 / A6-4。
+ */
+declare function colIndexToLetters(c: number): string;
+declare function lettersToColIndex(letters: string): number;
+/** 内部 `r,c` → `A1`（行 1-based 展示）。 */
+declare function toA1(r: number, c: number): string;
+/** `A1` / `b2` → 内部 0-based。 */
+declare function parseA1(a1: string): {
+    r: number;
+    c: number;
+};
+
+interface Rect {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}
+declare function normalizeRect(r1: number, c1: number, r2: number, c2: number): Rect;
+declare function rectContains(rect: Rect, r: number, c: number): boolean;
+/** 两轴对齐矩形是否相交（角点可不预先规范化）。 */
+declare function rectsOverlap(a: Rect, b: Rect): boolean;
+
+/** 选区矩形（规范化后的行列范围）。 */
+interface SelectionRect {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}
+/** 行高：显式 0 表示隐藏；>0 生效；否则回退默认。 */
+declare function getRowHeight(sheet: SheetTemplateState, r: number): number;
+/** 列宽：第 0 列允许为 0（隐藏行号列）；其余 >0 生效，否则回退默认。 */
+declare function getColWidth(sheet: SheetTemplateState, c: number): number;
+
+type FillExtension = {
+    dir: "down";
+    n: number;
+} | {
+    dir: "up";
+    n: number;
+} | {
+    dir: "right";
+    n: number;
+} | {
+    dir: "left";
+    n: number;
+};
+/** 选区规范化（与 geometry.normalizeRect 一致，保留 SelectionRect 命名） */
+declare function normSelectionRect(sel: SelectionRect): Rect;
+/** 由源选区与目标外接矩形推断单向延伸（与画布轴锁定一致） */
+declare function detectFillExtension(source: SelectionRect, target: SelectionRect): FillExtension | null;
+declare function extensionStripRect(s: Rect, ext: FillExtension): SelectionRect;
+declare function targetRectFromExtension(s: Rect, ext: FillExtension): SelectionRect;
+/** 根据拖拽命中格与锁定轴向计算预览选区（未延伸则返回源选区） */
+declare function computeFillPreviewSelection(sourceSel: SelectionRect, axis: "row" | "col", hitR: number, hitC: number): SelectionRect;
+/** 从首次移动偏差锁定轴向（仿 Excel：以较大位移为准） */
+declare function lockFillAxis(dRow: number, dCol: number): "row" | "col";
+
+declare function cellKey(r: number, c: number): string;
+declare function parseCellKey(key: string): {
+    r: number;
+    c: number;
+};
+
+/**
+ * 工作簿嵌入层 SSOT 类型（逻辑 normalizeWorkbookEmbeds 等保留在 kt-web embed/embedTypes.ts）。
+ */
+type EmbedAnchorRect = {
+    sheetId: string;
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+};
+type EmbedAnchorCell = {
+    sheetId: string;
+    r: number;
+    c: number;
+};
+/** 相对锚点格左上，单位 pt */
+type EmbedBoxPt = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type EmbedBase = {
+    embedId: string;
+    kind: "chart" | "asset";
+    name?: string;
+    zIndex?: number;
+    visibleWhen?: "always" | "hasData" | "expression";
+};
+type ChartDataSource = {
+    mode: "mainFields";
+    fields: string[];
+} | {
+    mode: "subTable";
+    subSchemaId: number;
+    rowScope: "all" | "currentPage" | "slotRange";
+    slotRange?: {
+        from: number;
+        to: number;
+    };
+    columns: string[];
+} | {
+    mode: "namedRange";
+    name: string;
+} | {
+    mode: "gridRange";
+    sheetId: string;
+    a1: string;
+} | {
+    mode: "script";
+    scriptBlockKey: string;
+};
+type ChartEmbedDef = EmbedBase & {
+    kind: "chart";
+    anchorRect: EmbedAnchorRect;
+    chart: {
+        type: "line" | "bar" | "column" | "pie" | "scatter" | "combo";
+        title?: string;
+        legend?: "none" | "bottom" | "right";
+        dataSource: ChartDataSource;
+        palette?: string[];
+        comboSeriesTypes?: Array<"line" | "bar">;
+        /** JS 模板：return ECharts option；占位符见 chartOptionTemplate.ts */
+        optionTemplate?: string;
+    };
+};
+type AssetKind = "image" | "signature" | "qrcode" | "stamp" | "barcode";
+type AssetEmbedDef = EmbedBase & {
+    kind: "asset";
+    assetKind: AssetKind;
+    anchorCell: EmbedAnchorCell;
+    box: EmbedBoxPt;
+    slotId: string;
+    defaultFileId?: string;
+    signature?: {
+        required?: boolean;
+        allowedRoles?: string[];
+    };
+    qrcode?: {
+        payloadTemplate: string;
+        errorCorrection?: "L" | "M" | "Q" | "H";
+        fgColor?: string;
+    };
+    barcode?: {
+        payloadTemplate: string;
+        /** 缺省 Code128 */
+        symbology?: "code128";
+    };
+    runtimeMovable?: boolean;
+};
+type WorkbookEmbedDef = ChartEmbedDef | AssetEmbedDef;
+/** 实例动态态（field pack v2 embedStates） */
+type EmbedInstanceState = {
+    fileId?: string;
+    qrPayload?: string;
+    signedBy?: string;
+    signedAt?: string;
+    frozenImageFileId?: string;
+    frozenAt?: string;
+};
+
+/** pt 与屏显 px 换算（96dpi 默认） */
+declare function ptToCssPx(pt: number, dpi?: number): number;
+declare function cssPxToPt(px: number, dpi?: number): number;
+
+/** 受限 JS 表达式运行时：表达式求值 + 语句解释 + 白名单沙箱 */
+type SjsValue = number | string | boolean | null | undefined | SjsValue[] | SjsObject;
+interface SjsObject {
+    [k: string]: SjsValue | SjsFn;
+}
+type SjsFn = (...args: SjsValue[]) => SjsValue;
+declare class SjsError extends Error {
+    constructor(msg: string);
+}
+declare class SjsCycleError extends SjsError {
+    constructor();
+}
+/** 用给定上下文执行 source，返回 return 值或最后表达式值 */
+declare function runSjs(source: string, context: Record<string, SjsValue | SjsFn>): SjsValue;
+/** 执行单一表达式（field 公式 :=expr 专用） */
+declare function runSjsExpr(source: string, context: Record<string, SjsValue | SjsFn>): SjsValue;
+/** 静态扫描表达式引用到的标识符（顶层 Ident 与 Member 的根） */
+declare function collectReferencedRoots(source: string, isExpr: boolean): Set<string>;
+
+/** Inspector / tableSystem.cellMeta 侧约定（与 workbook JSON 共存）。纯类型 + 复合键工具。 */
+type CellBindingKind = "none" | "text" | "basicField" | "dict" | "mainField" | "subField" | "systemParam";
+type SystemParamId = "templateName" | "sheetCount" | "sheetIndex" | "sheetName" | "pageNumber" | "totalPageNumber" | "currentDate" | "currentDateTime" | "tenantName" | "userDisplayName" | "userLoginName" | "subSchemaCount" | (string & {});
+type CellBindingMeta = {
+    bindingKind?: CellBindingKind;
+    paramId?: SystemParamId;
+    instanceFillable?: boolean;
+    fieldCode?: string;
+    subSchemaId?: number;
+    subRowIndex?: number;
+    subRowSlot?: number;
+    dictCode?: string;
+    remark?: string;
+    dictAllowCustom?: boolean;
+    dataType?: string;
+    imageStorage?: "base64" | "fileId" | "url";
+};
+type CellLayoutHint = {
+    layoutElement?: "none" | "signature" | "qrcode" | "chart" | "image";
+};
+type CellRoundingMeta = {
+    roundMode?: "half_up" | "half_even" | "truncate" | "ceiling" | "floor" | "to_interval" | "significant";
+    interval?: number;
+    scale?: number;
+    sigDigits?: number;
+    triggers?: Array<"onCommit" | "onCompute">;
+};
+type CellFormulaBindingMeta = {
+    formulaKind?: "grid" | "field" | "script";
+    source?: string;
+    scriptBlockKey?: string;
+    writeBack?: "value" | "display";
+    roundAfter?: boolean;
+    errorText?: string;
+    fieldScope?: "main" | "subRow";
+    subSchemaId?: number;
+    writeToFieldCode?: string;
+    inputWhen?: "always" | "anyPresent" | "allPresent";
+    inputFields?: string[];
+    runWhen?: "auto" | "manualOnly";
+};
+type SubTableRegionConfig = {
+    id: string;
+    subSchemaId?: number;
+    anchor: string;
+    direction: "vertical" | "horizontal";
+    rowsPerPage: number;
+};
+declare function cellMetaCompoundKey(sheetId: string, cellKey: string): string;
+declare function parseCellMetaCompoundKey(key: string): {
+    sheetId: string;
+    cellKey: string;
+} | null;
+
+/**
+ * 实例 data JSON 的 `logicalState`：用于"逻辑页"扩容子表行数。
+ *
+ * - `data.subTables[N].rows` 始终是全量数组；`logicalPageIndex` 只是显示窗口
+ * - 一页行容量 = `region.rows`；总可填行数 = `region.rows * logicalPageCount`
+ * - 切页只更新 `logicalPageIndex`，不改 rows，不卸载编辑器
+ */
+interface LogicalState {
+    /** 全局当前逻辑页（默认 0） */
+    logicalPageIndex?: number;
+    /** 全局逻辑页总数（最少 1） */
+    logicalPageCount?: number;
+    /**
+     * 多 sheet 模板时每个 sheet 独立逻辑页（缺省回退到全局）
+     *  key = sheetId
+     */
+    perSheet?: Record<string, {
+        logicalPageIndex: number;
+        logicalPageCount: number;
+    }>;
+    /**
+     * 不参与打印预览的逻辑页 slot（`${sheetId}::${logicalPageIndex}`）。
+     * 隐藏页仍可编辑；页脚 pageNumber/totalPageNumber 留空。
+     */
+    hiddenPageSlots?: string[];
+}
+/** 从实例 data JSON 字符串读 logicalState；缺失/非法返回空对象 */
+declare function parseLogicalState(dataJson: string | null | undefined): LogicalState;
+/** 从已解析的 root 对象读 logicalState（无副作用） */
+declare function pickLogicalStateFromRoot(root: unknown): LogicalState;
+/** 取某个 sheet 当前应当用的 (logicalPageIndex, logicalPageCount)：优先 perSheet[sheetId]，回退全局，再回退 (0,1) */
+declare function resolveSheetLogicalPage(ls: LogicalState | null | undefined, sheetId: string): {
+    logicalPageIndex: number;
+    logicalPageCount: number;
+};
+/** 把 logicalState 合并写回实例 data JSON（不动 cells/cellsBySheet 等其它字段） */
+declare function mergeInstanceDataJsonWithLogicalState(priorDataJson: string, patch: Partial<LogicalState> | LogicalState | null | undefined): string;
+/**
+ * 子表全量数据（acc）持久化在 instance data JSON 的 `subTables` 字段：
+ *   data.subTables[N] = { rows: Array<Record<col,val>> }
+ * 与 docs/sheet-system/03 §2 的"伪结构示例"一致；缺失视为空 acc。
+ */
+type InstanceSubTablesData = Record<string, {
+    rows: Array<Record<string, unknown>>;
+}>;
+/** 从 instance data JSON 读 subTables.rows → 转成 acc 格式（以 number 子表序号为键） */
+declare function parseInstanceSubTables(dataJson: string | null | undefined): Record<number, Array<Record<string, unknown>>>;
+/** 把 acc（按 number sid 索引）合并写回 data.subTables（用 "1"/"2" 作为 key 与文档一致） */
+declare function mergeInstanceDataJsonWithSubTables(priorDataJson: string, acc: Record<number, Array<Record<string, unknown>>> | null | undefined): string;
+
+/**
+ * 模板包内嵌字典目录（设计态 workbook.meta.dictCatalog）纯类型与常量。
+ * 逻辑（规范化 / 快照 / overlay 合并）保留在 kt-web templateDictCatalog.ts。
+ */
+declare const TEMPLATE_DICT_CATALOG_VERSION: 1;
+declare const DICT_CATALOG_META_KEY = "dictCatalog";
+declare const DICT_OVERLAYS_BY_USER_KEY = "dictOverlaysByUser";
+type TemplateDictKind = "fixed" | "editable";
+/** 设计器/表格展示用 dictKind 中文标签 */
+declare function describeDictKind(kind: TemplateDictKind): string;
+type TemplateDictItem = {
+    value: string;
+    label: string;
+    sortOrder?: number;
+    enabled?: boolean;
+};
+type TemplateDictDef = {
+    code: string;
+    name: string;
+    dictKind: TemplateDictKind;
+    items: TemplateDictItem[];
+    enabled?: boolean;
+};
+type TemplateDictCatalog = {
+    v: typeof TEMPLATE_DICT_CATALOG_VERSION;
+    updatedAt?: string;
+    dicts: TemplateDictDef[];
+};
+type DictSnapshotEntry = {
+    dictKind: TemplateDictKind;
+    name?: string;
+    items: TemplateDictItem[];
+};
+type DictSnapshotsMap = Record<string, DictSnapshotEntry>;
+/** userId → dictCode → overlay items */
+type InstanceDictOverlaysByUser = Record<string, Record<string, TemplateDictItem[]>>;
+
+/**
+ * 实例 data JSON schema v2（字段包 SSOT）
+ */
+
+declare const INSTANCE_DATA_SCHEMA_V2: 2;
+declare const INSTANCE_DATA_SCHEMA_V3: 3;
+type RefreshPolicy = "manual" | "onOpen" | "onSourceSave";
+type PullContextSource = {
+    alias: string;
+    sourceInstanceId?: string;
+    sourceProductCode?: string;
+    fromPolicy?: boolean;
+    adhocRules?: FieldPullRuleDef[];
+};
+type PullContext = {
+    sources: PullContextSource[];
+    refreshPolicy?: RefreshPolicy;
+    lastPulledAt?: string;
+    lastPullSignature?: string;
+};
+type FieldPullRuleDef = {
+    targetPath: string;
+    mode: "direct" | "aggregate" | "filter" | "expr";
+    sourceAlias?: string;
+    sourcePath?: string;
+    aggregateFn?: "sum" | "avg" | "min" | "max" | "count";
+    filterJson?: Record<string, unknown>;
+    exprSource?: string;
+    enabled?: boolean;
+};
+type RoundingOverrideEntry = {
+    roundMode?: "decimal" | "interval" | "sigDigits";
+    scale?: number;
+    interval?: number;
+    sigDigits?: number;
+    triggers?: Array<"onCommit" | "onCompute">;
+};
+type ComboSharedContext = {
+    sharedSeed?: Record<string, unknown>;
+    uiLayout?: {
+        slotOrder?: string[];
+        hiddenSlotKeys?: string[];
+    };
+    refreshPolicyDefault?: RefreshPolicy;
+};
+type ComboInstanceDataV3 = {
+    schemaVersion: typeof INSTANCE_DATA_SCHEMA_V3;
+    kind: "combo";
+    comboSnapshotId: string;
+    sharedContext: ComboSharedContext;
+    slots: Record<string, InstanceFieldPackV2Ext>;
+};
+type InstanceSubTablePack = {
+    rows: Array<Record<string, unknown>>;
+    logicalState?: {
+        logicalPageIndex?: number;
+        logicalPageCount?: number;
+    };
+};
+type InstanceFieldPackV2 = {
+    schemaVersion: typeof INSTANCE_DATA_SCHEMA_V2;
+    base: Record<string, unknown>;
+    /** 分页专用基本项：scopeId → 字段键值（含 table_name） */
+    baseScoped?: Record<string, Record<string, unknown>>;
+    main: Record<string, unknown>;
+    subTables: Record<string, InstanceSubTablePack>;
+    params: Record<string, unknown>;
+    logicalState: LogicalState;
+    orphanCellsBySheet: Record<string, Record<string, unknown>>;
+    /** 嵌入资产实例态：签章 fileId、QR 覆盖等，key = slotId */
+    embedStates?: Record<string, EmbedInstanceState>;
+    upgradeLog?: Array<Record<string, unknown>>;
+    /** 一次性 legacy 备份（运维可清理） */
+    _legacyBackup?: unknown;
+    /** editable 模板字典增量（按用户，不回写模板） */
+    dictOverlaysByUser?: InstanceDictOverlaysByUser;
+};
+/** v2 字段包扩展：报告拉取上下文与修约覆盖 */
+type InstanceFieldPackV2Ext = InstanceFieldPackV2 & {
+    pullContext?: PullContext;
+    roundingOverrides?: Record<string, RoundingOverrideEntry>;
+};
+type InstanceDataRoot = Record<string, unknown>;
+/** 判别是否为 v3 组合实例 */
+declare function isComboInstanceDataV3(data: unknown): data is ComboInstanceDataV3;
+/** 从 root 提取 v3 组合包 */
+declare function comboDataFromRoot(root: InstanceDataRoot): ComboInstanceDataV3 | null;
+/** 判别是否为 v2 字段包 */
+declare function isInstanceFieldPackV2(data: unknown): data is InstanceFieldPackV2;
+/** 从 JSON 字符串解析 root */
+declare function parseInstanceDataRoot(dataJson: string | null | undefined): InstanceDataRoot;
+/** 是否 legacy v1（cells/cellsBySheet 为主，无 schemaVersion=2） */
+declare function isLegacyInstanceDataV1(root: InstanceDataRoot): boolean;
+/** 创建空 v2 字段包 */
+declare function emptyFieldPackV2(): InstanceFieldPackV2;
+/** 序列化 v2 字段包为 JSON 字符串 */
+declare function serializeFieldPackV2(pack: InstanceFieldPackV2): string;
+/** 从 root 提取 v2 字段包（已是 v2 时）；否则 null */
+declare function fieldPackFromRoot(root: InstanceDataRoot): InstanceFieldPackV2 | null;
+
+/**
+ * 字段修约规则解析与运行时应用（field 公式写回 / roundByField）
+ */
+
+/** 从 rounding_json 字符串解析修约元数据 */
+declare function parseRoundingJson(raw: string | null | undefined): CellRoundingMeta | undefined;
+/** 计算阶段是否应用修约（与 compute.ts getRoundingForCompute 一致） */
+declare function roundingForCompute(meta: CellRoundingMeta | undefined): CellRoundingMeta | undefined;
+type FieldRoundingTarget = {
+    scope: "main" | "base" | "sub";
+    key: string;
+    subSchemaId?: number;
+};
+/** 按目标字段从 fieldRegistry 查 rounding_json；实例 override 优先于 registry */
+declare function resolveRoundingForTarget(registry: TemplateFieldRegistry | null | undefined, target: FieldRoundingTarget, overrides?: Record<string, RoundingOverrideEntry> | null): CellRoundingMeta | undefined;
+/** 与修约 override 键一致：main.kyqd / base.xxx / sub:1.strength */
+declare function targetToOverrideKey(target: FieldRoundingTarget): string;
+type ParsedFieldPath = {
+    scope: "main";
+    key: string;
+} | {
+    scope: "base";
+    key: string;
+} | {
+    scope: "sub";
+    subSchemaId: number;
+    key: string;
+} | {
+    scope: "row";
+    key: string;
+};
+/**
+ * 解析字段路径字符串，如 m2 / m.m2 / s1.qdqz / row.qd1 / b.xxx
+ */
+declare function parseFieldPath(raw: string): ParsedFieldPath | null;
+declare function resolveRoundingFromFieldPath(registry: TemplateFieldRegistry | null | undefined, path: string, ctx: {
+    currentTarget?: FieldRoundingTarget;
+    subSchemaId?: number;
+}): CellRoundingMeta | undefined;
+/** 将数值按修约元数据修约；null/''/非数值原样返回 */
+declare function applyNumericRounding(value: SjsValue, meta: CellRoundingMeta | undefined): SjsValue;
+type ComputeFieldLhs = {
+    kind: "main";
+    key: string;
+} | {
+    kind: "base";
+    key: string;
+} | {
+    kind: "subRow";
+    subSchemaId: number;
+    col: string;
+    rowIndex: number;
+};
+declare function lhsToRoundingTarget(lhs: ComputeFieldLhs): FieldRoundingTarget;
+/** field 公式写回 fieldData 前：按目标字段 onCompute 修约 */
+declare function applyFieldRoundingForStore(value: SjsValue, registry: TemplateFieldRegistry | null | undefined, lhs: ComputeFieldLhs, opts?: {
+    roundAfter?: boolean;
+}): SjsValue;
+
+/** field 公式：`:= <expr>` 解析 + 字段上下文构造 + 聚合函数注入 */
+
+/** 若源码以 ':=' 起头则返回去前缀后的表达式；否则返回 null */
+declare function stripFieldPrefix(src: string): string | null;
+/** LHS 推导：从绑定与作用域决定字段公式作用于 main/subRow */
+type FieldLhs = {
+    kind: "main";
+    key: string;
+} | {
+    kind: "sub";
+    subSchemaId: number;
+    col: string;
+};
+interface FieldDataCtx {
+    base: Record<string, unknown>;
+    main: Record<string, unknown>;
+    sub: Record<number, Array<Record<string, unknown>>>;
+    params: Record<string, unknown>;
+}
+/**
+ * 构造表达式运行时上下文：包含 b/m/sN/p + row（subRow 作用域）+ 聚合/数学函数。
+ *
+ * `mutable=true`（脚本块场景）时额外注入 `assign / setMain / setBase / setSub` 一组 setter，
+ * 让脚本能主动写回字段数据（典型用例：`fxStat` 一个脚本算多个统计指标分别赋给 m11/m12/m13）。
+ * field 公式只能返回单值不应使用，故默认 false。
+ */
+type FieldRunContextOptions = {
+    mutable?: boolean;
+    fieldRegistry?: TemplateFieldRegistry | null;
+    /** 当前公式目标，roundByField 默认规则来源 */
+    currentTarget?: FieldRoundingTarget;
+    aggregateEmptyAs?: AggregateEmptyAs;
+};
+declare function buildFieldRunContext(data: FieldDataCtx, scope: {
+    kind: "main";
+} | {
+    kind: "sub";
+    subSchemaId: number;
+    rowIndex: number;
+}, options?: FieldRunContextOptions): Record<string, SjsValue | SjsFn>;
+type FormulaStdLibOptions = {
+    fieldRegistry?: TemplateFieldRegistry | null;
+    currentTarget?: FieldRoundingTarget;
+    subSchemaId?: number;
+    aggregateEmptyAs?: AggregateEmptyAs;
+};
+/** 纯函数标准库：sum/avg/min/max/count/first/last + round/roundToInterval/roundSig + abs/ceil/floor + ifEmpty/formatDate */
+declare function buildFormulaStdLib(opts?: FormulaStdLibOptions): Record<string, SjsFn>;
+
+/** 打印/预览叠图 embed 上下文 */
+type EmbedPrintContext = {
+    embeds: WorkbookEmbedDef[];
+    embedStates?: Record<string, EmbedInstanceState>;
+    qrPayloadBySlot?: Record<string, string>;
+    /** 图表 live 栅格数据源 */
+    fieldData?: FieldDataCtx;
+    /** 图表 script 数据源 */
+    scripts?: WorkbookScripts | null;
+};
+declare function hasEmbedsToPaint(ctx: EmbedPrintContext | null | undefined): boolean;
+
+/** 与 `SheetTemplateState` 对齐的工作簿页（SSOT）。 */
+type TemplateSheetItem = {
+    id: string;
+    name: string;
+    sheet: SheetTemplateState;
+};
+/** 持久化/工具链使用的模板工作簿根对象（取代旧 `Workbook` + 桥接）。 */
+type TemplateWorkbookState = {
+    workbookVersion: number;
+    activeSheetId: string;
+    sheets: TemplateSheetItem[];
+    meta?: WorkbookMeta;
+    /** M3：工作簿级 CALC_* 脚本块（与旧 Workbook.scripts 对齐） */
+    scripts?: WorkbookScripts | null;
+    /** M3+：命名区域 */
+    namedRanges?: WorkbookNamedRange[] | null;
+    /** 嵌入层：图表区 + 签章/图片/QR 槽（设计态 SSOT） */
+    embeds?: WorkbookEmbedDef[] | null;
+    /** 域 02：拼接/可变行等元数据；持久化于内层工作簿根 */
+    ktTemplate?: KtTemplateRoot;
+};
+declare const TEMPLATE_WORKBOOK_JSON_VERSION: 1;
+
+interface MasterCell {
+    masterR: number;
+    masterC: number;
+    rect: MergeRect;
+}
+/** 合并区快速查询：O(1) 命中主格（初始化 O(格数)）。 */
+declare class MergeIndex {
+    private readonly map;
+    constructor(merges: MergeRect[]);
+    getMaster(r: number, c: number): MasterCell | undefined;
+    /** 若 (r,c) 为合并块左上角则为主格。 */
+    isMaster(r: number, c: number): boolean;
+    static overlaps(a: MergeRect, b: MergeRect): boolean;
+    static normalize(rect: MergeRect): MergeRect;
+}
+
+type BorderPreset = "none" | "all" | "outer" | "top" | "bottom" | "left" | "right" | "innerHorizontal" | "innerVertical";
+interface BorderApplySpec {
+    width: Exclude<BorderWidth, "none">;
+    color: string;
+    pattern: BorderPattern;
+}
+
+/** 选区内每个主格是否都是独立单格（无合并）。 */
+declare function selectionIsUnmergedRectangle(idx: MergeIndex, rect: {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}): boolean;
+declare function applyBorderPresetToSheet(sheet: Sheet, mergeIdx: MergeIndex, rect: {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}, preset: BorderPreset, spec: BorderApplySpec): Record<string, CellData>;
+
+declare function matrixToTsv(rows: string[][]): string;
+declare function tsvToMatrix(tsv: string): string[][];
+declare function readSelectionAsTsv(sheet: Sheet, r1: number, c1: number, r2: number, c2: number): string;
+interface PasteCellPatch {
+    key: string;
+    before: CellData | undefined;
+    after: CellData | undefined;
+}
+/** 自 (startR,startC) 粘贴矩阵；返回 cell 级 patch（用于撤销）。 */
+declare function buildPastePatches(sheet: Sheet, startR: number, startC: number, matrix: string[][]): PasteCellPatch[];
+
+declare function createDefaultPage(): PageSettings;
+declare function createEmptySheet(name: string, rowCount?: 200, colCount?: 50): SheetItem;
+declare function createEmptyWorkbook(): Workbook;
+/** 稀疏填充用于压力 / dev 基线（showcase）。 */
+declare function fillSparseDemoCells(sheet: Sheet, rows: number, cols: number): void;
+
+declare function serializeWorkbook(workbook: Workbook): string;
+declare function parseWorkbookJson(text: string): Workbook;
+
+/** 公式引擎统一类型：AST 节点、值域、错误、计算上下文 */
+type FormulaValueKind = "num" | "str" | "bool" | "null" | "err";
+type FormulaError = {
+    code: "#ERR" | "#DIV0" | "#REF" | "#NAME" | "#VALUE" | "#CYCLE" | "#NUM";
+    message?: string;
+};
+type FormulaValue = {
+    k: "num";
+    v: number;
+} | {
+    k: "str";
+    v: string;
+} | {
+    k: "bool";
+    v: boolean;
+} | {
+    k: "null";
+} | {
+    k: "err";
+    v: FormulaError;
+};
+/** 数组（区域）值：二维矩阵；行主序 */
+type FormulaArray = {
+    k: "arr";
+    rows: FormulaValue[][];
+};
+type FormulaAny = FormulaValue | FormulaArray;
+declare function vNum(v: number): FormulaValue;
+declare function vStr(v: string): FormulaValue;
+declare function vBool(v: boolean): FormulaValue;
+declare const V_NULL: FormulaValue;
+declare function vErr(code: FormulaError["code"], message?: string): FormulaValue;
+declare function isErr(v: FormulaAny): v is {
+    k: "err";
+    v: FormulaError;
+};
+declare function coerceNum(v: FormulaValue): number | null;
+declare function coerceStr(v: FormulaValue): string;
+declare function coerceBool(v: FormulaValue): boolean | null;
+/** 迭代区域内每个值（按行主序） */
+declare function forEachArrayValue(arr: FormulaArray, fn: (v: FormulaValue) => void): void;
+/** AST */
+type AstNode = {
+    type: "num";
+    value: number;
+} | {
+    type: "str";
+    value: string;
+} | {
+    type: "bool";
+    value: boolean;
+} | {
+    type: "ref";
+    sheet?: string;
+    r: number;
+    c: number;
+    absR?: boolean;
+    absC?: boolean;
+} | {
+    type: "range";
+    sheet?: string;
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+} | {
+    type: "name";
+    name: string;
+} | {
+    type: "unary";
+    op: "+" | "-";
+    expr: AstNode;
+} | {
+    type: "binary";
+    op: BinOp;
+    left: AstNode;
+    right: AstNode;
+} | {
+    type: "call";
+    name: string;
+    args: AstNode[];
+} | {
+    type: "percent";
+    expr: AstNode;
+};
+type BinOp = "+" | "-" | "*" | "/" | "^" | "&" | "=" | "<>" | "<" | "<=" | ">" | ">=";
+/** 计算上下文：由 compute.ts 构造后传给 evaluator */
+interface EvalContext {
+    activeSheetId: string;
+    getCell: (sheetId: string, r: number, c: number) => FormulaValue;
+    getNamed?: (name: string) => {
+        sheet: string;
+        r1: number;
+        c1: number;
+        r2: number;
+        c2: number;
+    } | null;
+    here?: {
+        sheetId: string;
+        r: number;
+        c: number;
+    };
+    fieldCtx?: FieldEvalContext;
+}
+/** 字段公式 / 脚本专用：主/子表数据读取 */
+interface FieldEvalContext {
+    base: Record<string, unknown>;
+    main: Record<string, unknown>;
+    sub: Record<number, Array<Record<string, unknown>>>;
+    params: Record<string, unknown>;
+    rowIndex?: number;
+    currentSubSchemaId?: number;
+}
+
+/**
+ * A1 寻址工具：列字母与 0-based 下标互转；解析 A1 / A1:B10 / Sheet2!A1 引用。
+ * 内部下标全部 0-based（与引擎一致）；对外展示（公式栏）使用 1-based A1。
+ */
+declare function columnLettersToIndex(letters: string): number;
+declare function columnIndexToLetters(index0: number): string;
+type A1SingleRef = {
+    kind: "single";
+    sheet?: string;
+    /** 0-based 行 */
+    r: number;
+    /** 0-based 列 */
+    c: number;
+    /** 绝对行 $1 */
+    absR?: boolean;
+    /** 绝对列 $A */
+    absC?: boolean;
+};
+type A1RangeRef = {
+    kind: "range";
+    sheet?: string;
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+};
+type A1Ref = A1SingleRef | A1RangeRef;
+/** 解析 sheetId.r11c1：1-based 行列（与画布 cell 坐标一致），sheet 为工作表 id / 快照 id。 */
+declare function parseInternalR1C1Ref(input: string): A1SingleRef | null;
+/** 解析单点 A1，不含 sheet 时返回 sheet=undefined */
+declare function parseA1Single(input: string): A1SingleRef | null;
+/** 解析 A1 或 A1:B10（含可选 sheet!） */
+declare function parseA1Ref(input: string): A1Ref | null;
+declare function formatA1Single(r0: number, c0: number, sheet?: string): string;
+declare function formatA1Range(r1: number, c1: number, r2: number, c2: number, sheet?: string): string;
+
+/** 网格公式词法：把 =SUM(A1:B2, 3*4) 切成 token 流 */
+type TokenType = "num" | "str" | "ident" | "ref" | "range" | "op" | "lparen" | "rparen" | "comma" | "semi" | "eof";
+interface Token {
+    type: TokenType;
+    text: string;
+    /** 起始偏移 */
+    pos: number;
+}
+declare function tokenize(src: string): Token[];
+
+/** 网格公式语法分析：Pratt 优先级 */
+
+declare class Parser {
+    private toks;
+    private i;
+    constructor(src: string);
+    parse(): AstNode;
+    private peek;
+    private eat;
+    private parseExpr;
+    private parseUnary;
+    private parsePostfix;
+    private parsePrimary;
+}
+declare function parseFormula(src: string): AstNode;
+
+/** 依赖图：节点 id 规则
+ * - 网格格：grid:<sheetId>!r,c
+ * - 字段：field:m.<key>、field:s<N>.<col>#<rowIdx>
+ * - 脚本：script:<key>（scope=main）或 script:<key>#<rowIdx>（subRow）
+ */
+type NodeId = string;
+declare function gridNodeId(sheetId: string, r: number, c: number): NodeId;
+declare function mainFieldNodeId(key: string): NodeId;
+declare function subFieldNodeId(subSchemaId: number, key: string, rowIdx: number): NodeId;
+declare function scriptNodeId(key: string, rowIdx?: number, subSchemaId?: number): NodeId;
+declare class DepGraph {
+    /** 出边：a → {b} 表示 b 依赖 a（a 变 b 需要重算） */
+    private outEdges;
+    /** 入边：a → {b} 表示 a 依赖 b */
+    private inEdges;
+    private allNodes;
+    addNode(id: NodeId): void;
+    /** self 依赖 dep：dep 变则 self 重算 */
+    addEdge(self: NodeId, dep: NodeId): void;
+    hasNode(id: NodeId): boolean;
+    dependenciesOf(id: NodeId): NodeId[];
+    dependentsOf(id: NodeId): NodeId[];
+    allIds(): NodeId[];
+    /**
+     * 拓扑排序；若存在环路，将环上所有节点标记为 cyclic（以数组二元组返回）。
+     * 返回 { order, cyclic }：order 为无环部分的求值顺序（先 dep 后 self）。
+     */
+    topoSort(): {
+        order: NodeId[];
+        cyclic: Set<NodeId>;
+    };
+    /** 增量：找出所有需要重算的节点（dirty 的所有下游） */
+    dirtyClosure(roots: Iterable<NodeId>): Set<NodeId>;
+    clear(): void;
+}
+
+/** 网格公式内置函数（M3 最小集 + 少量常用）：求值器调用 */
+
+type FnImpl = (args: FormulaAny[]) => FormulaValue;
+declare const FUNCTIONS: Record<string, FnImpl>;
+
+/** 受限 JS 表达式引擎（field 公式 `:= expr` 与 script 共享）
+ *
+ * 支持：字面量（数字/字符串/布尔/null/数组/对象）、变量、成员访问（可选链）、
+ * 索引、一元 +/-/!、二元算术与比较、&&/||、三元、函数调用；let/const 声明、
+ * if/else、for…of、return；模板字符串（无嵌入式表达式）。
+ *
+ * 禁止：function 声明、class、new、this、import/require、regex 字面量、try/catch、
+ * 赋值给非本地变量、访问全局对象（window/document/globalThis/eval/Function 等）。
+ */
+type SjsNode = {
+    t: "Num";
+    v: number;
+} | {
+    t: "Str";
+    v: string;
+} | {
+    t: "Bool";
+    v: boolean;
+} | {
+    t: "Null";
+} | {
+    t: "Ident";
+    name: string;
+} | {
+    t: "Arr";
+    items: SjsNode[];
+} | {
+    t: "Obj";
+    props: Array<{
+        key: string;
+        value: SjsNode;
+    }>;
+} | {
+    t: "Member";
+    obj: SjsNode;
+    prop: string;
+    optional?: boolean;
+} | {
+    t: "Index";
+    obj: SjsNode;
+    idx: SjsNode;
+    optional?: boolean;
+} | {
+    t: "Call";
+    callee: SjsNode;
+    args: SjsNode[];
+    optional?: boolean;
+} | {
+    t: "Unary";
+    op: "+" | "-" | "!";
+    expr: SjsNode;
+} | {
+    t: "Bin";
+    op: SjsBinOp;
+    l: SjsNode;
+    r: SjsNode;
+} | {
+    t: "Tern";
+    c: SjsNode;
+    a: SjsNode;
+    b: SjsNode;
+} | {
+    t: "Assign";
+    op: "=" | "+=" | "-=" | "*=" | "/=" | "**=";
+    name: string;
+    value: SjsNode;
+};
+type SjsBinOp = "+" | "-" | "*" | "/" | "%" | "**" | "==" | "!=" | "===" | "!==" | "<" | "<=" | ">" | ">=" | "&&" | "||" | "??";
+type SjsStmt = {
+    t: "ExprStmt";
+    expr: SjsNode;
+} | {
+    t: "VarDecl";
+    kind: "let" | "const";
+    name: string;
+    init?: SjsNode;
+} | {
+    t: "If";
+    cond: SjsNode;
+    then: SjsStmt[];
+    else?: SjsStmt[];
+} | {
+    t: "ForOf";
+    name: string;
+    iter: SjsNode;
+    body: SjsStmt[];
+} | {
+    t: "Return";
+    arg?: SjsNode;
+} | {
+    t: "Block";
+    body: SjsStmt[];
+};
+interface SjsProgram {
+    body: SjsStmt[];
+}
+type TT = "num" | "str" | "tpl" | "ident" | "punct" | "kw" | "eof";
+interface Tok {
+    t: TT;
+    v: string;
+    pos: number;
+}
+declare function sjsTokenize(src: string): Tok[];
+declare function parseSjsProgram(src: string): SjsProgram;
+declare function parseSjsExpr(src: string): SjsNode;
+
+/**
+ * 内置参数编码 SSOT（与后端 BuiltinParamCatalog 对齐）。
+ */
+/** 后端目录预置、租户可开关 */
+declare const BUILTIN_PARAM_CATALOG_CODES: readonly ["pageNumber", "totalPageNumber", "currentDate", "currentDateTime", "tenantName", "userDisplayName", "userLoginName"];
+/** 不进目录表、由运行态按工作簿/渲染上下文求值 */
+declare const RUNTIME_ONLY_SYSTEM_PARAM_CODES: readonly ["sheetIndex", "sheetName", "sheetCount", "templateName", "subSchemaCount"];
+type BuiltinParamCatalogCode = (typeof BUILTIN_PARAM_CATALOG_CODES)[number];
+type RuntimeOnlySystemParamCode = (typeof RUNTIME_ONLY_SYSTEM_PARAM_CODES)[number];
+declare const LEGACY_SYSTEM_PARAM_TEMPLATE_TOKENS: Record<string, string>;
+declare function normalizeSystemParamId(id: string): string;
+declare function isKnownSystemParamId(id: string): boolean;
+declare const RUNTIME_COMPUTED_SYSTEM_PARAM_CODES: readonly ["pageNumber", "totalPageNumber", "currentDate", "currentDateTime", "tenantName", "userDisplayName", "userLoginName", "sheetIndex", "sheetName", "sheetCount", "templateName", "subSchemaCount"];
+declare function isRuntimeComputedSystemParam(id: string): boolean;
+declare function listKnownSystemParamIdsForTemplate(): string[];
+declare function listTemplateSystemParamTokenEntries(): Array<{
+    token: string;
+    canonical: string;
+}>;
+
+/** 字段修约 triggers 预设：UI 单选 ↔ rounding_json.triggers */
+
+type RoundingWhenPreset = "both" | "commitOnly" | "computeOnly" | "none";
+type RoundingTriggerFlags = {
+    onCommit: boolean;
+    onCompute: boolean;
+};
+/** 解析 triggers；缺省视为录入+计算都修约 */
+declare function normalizeRoundingTriggers(raw?: Array<"onCommit" | "onCompute"> | null): RoundingTriggerFlags;
+declare function presetToTriggers(preset: RoundingWhenPreset): Array<"onCommit" | "onCompute">;
+declare function triggersToPreset(raw?: Array<"onCommit" | "onCompute"> | null): RoundingWhenPreset;
+declare const ROUNDING_WHEN_LABELS: Record<RoundingWhenPreset, string>;
+declare function describeRoundingWhenPreset(preset: RoundingWhenPreset): string;
+/** 录入提交路径：是否应用修约 */
+declare function getRoundingForCommit(meta: CellRoundingMeta | undefined): CellRoundingMeta | undefined;
+/** 计算/绑定刷新路径：是否应用修约 */
+declare function getRoundingForComputeMeta(meta: CellRoundingMeta | undefined): CellRoundingMeta | undefined;
+
+/**
+ * 从发布态单元格 meta 条目解析修约配置：支持顶层 roundMode/scale 等，或嵌套 rounding 对象。
+ */
+declare function getRoundingMetaFromCellMetaEntry(entry: unknown): CellRoundingMeta | undefined;
+declare function tryParseNumericString(raw: string): number | null;
+/** 将数字按 CellRoundingMeta 修约并格式化为字符串；raw 不是合法数字时原样返回 */
+declare function formatNumericByMeta(raw: string, meta: CellRoundingMeta | undefined): string;
+declare function applyRoundingForInstancePlain(plain: string, cellMeta: Record<string, unknown> | null | undefined, sheetId: string, mr: number, mc: number): string;
+/** 对数字 n 按 meta 执行修约（不格式化，仅返回 number） */
+declare function applyRounding(n: number, meta: CellRoundingMeta | undefined): number;
+/** 支持负 scale：-1 保留到十位，-2 到百位，0 到个位，1 到 1 位小数 */
+declare function roundFinite(n: number, scale: number, mode: NonNullable<Exclude<CellRoundingMeta["roundMode"], "to_interval" | "significant">>): number;
+/** 修约到 N 的倍数（默认 half_up，符合工程修约直觉：17 → 18；13 → 15） */
+declare function roundToInterval(n: number, interval: number, mode?: "half_even" | "half_up"): number;
+/** 保留 k 位有效数字（正整数 k） */
+declare function roundToSignificant(n: number, k: number): number;
+
+/**
+ * 子表有效行数：统计键非空的 globalIndex 个数（any_filled，不要求连续）。
+ */
+
+/** 解析 subSchema 的统计键字段 code；标记优先，否则 sortOrder 最小 */
+declare function resolveSubRowStatKey(registry: TemplateFieldRegistry | null | undefined, subSchemaId: number): string;
+/** 统计键非空行数 */
+declare function countActiveSubRows(rows: Array<Record<string, unknown>>, statKey: string): number;
+/** 返回统计键非空的 rowIndex 列表（供 subRow 脚本迭代） */
+declare function activeSubRowIndices(rows: Array<Record<string, unknown>>, statKey: string): number[];
+/** 各 subSchemaId → 有效行数 */
+declare function buildActiveSubRowCounts(fieldDataSub: Record<number, Array<Record<string, unknown>>>, registry: TemplateFieldRegistry | null | undefined): Record<number, number>;
+
+/**
+ * 子表 fieldData / acc 槽位：公式与序列化用标量；用户富文本用 `{ value, runs }`。
+ * 供公式/runtime 读取时先规范化。
+ */
+declare function normalizeSubFieldSlotForFormula(v: unknown): unknown;
+/** 从画布 CellData 写入 fieldData.sub / acc：无 runs 时与原先一致（数字会 tryParse）。 */
+declare function subFieldPersistValueFromCell(cd: CellData$1 | undefined): unknown;
+declare function isSubFieldRichPersist(v: unknown): v is {
+    value: string;
+    runs: TextRun[];
+};
+/** 切页 / 打印 swap：用 acc 槽位还原格（支持富文本）。 */
+declare function mergeSubFieldCellFromAccValue(prev: CellData$1 | undefined, accVal: unknown): {
+    cell: CellData$1;
+    changed: boolean;
+};
+
+/**
+ * 多层修约覆盖合并（UI-06 终端用户修约中心的 core 支撑，P0）。
+ *
+ * 优先级（低→高，就近覆盖优先，见 UI-06 §6）：
+ *   模版默认(设计态, 由 fieldRegistry.rounding_json 提供，不在本层)
+ *     < 组合策略覆盖(comboProfile) < 我的默认(userDefault) < 该模版覆盖(templateScoped) < 本实例(instance)
+ *
+ * 合并产出一个 `RoundingOverrideMap`（键 = targetToOverrideKey：main.xxx / base.xxx / sub:1.xxx），
+ * 再交给 `resolveRoundingForTarget(registry, target, mergedOverrides)` 与模版默认叠加得到最终生效修约。
+ *
+ * 锁定字段（模版标「禁止用户改」）：忽略所有用户层覆盖，仅保留设计态(comboProfile)。
+ */
+
+type RoundingOverrideMap = Record<string, RoundingOverrideEntry>;
+/** 覆盖层作用域（按优先级低→高）。comboProfile 属设计态；其余为用户层。 */
+type RoundingLayerScope = "comboProfile" | "userDefault" | "templateScoped" | "instance";
+declare const ROUNDING_LAYER_ORDER: readonly RoundingLayerScope[];
+interface RoundingLayer {
+    scope: RoundingLayerScope;
+    /** 键 = targetToOverrideKey（main.xxx / base.xxx / sub:{id}.xxx） */
+    overrides: RoundingOverrideMap;
+}
+/**
+ * 按优先级低→高合并多层覆盖为单一 map。
+ * @param layers 任意顺序均可；内部按 ROUNDING_LAYER_ORDER 归一排序后合并。
+ * @param lockedKeys 锁定字段（overrideKey），用户层对其覆盖被忽略。
+ */
+declare function mergeRoundingOverrideLayers(layers: readonly RoundingLayer[], lockedKeys?: ReadonlySet<string>): RoundingOverrideMap;
+/** 便捷：从「作用域→覆盖 map」记录构建 layers（缺省作用域跳过）。 */
+declare function buildRoundingLayers(byScope: Partial<Record<RoundingLayerScope, RoundingOverrideMap | null | undefined>>): RoundingLayer[];
+
+/**
+ * 拼接诊断聚合（UI-04 §5「拼接冲突/错位诊断面板」的 core 规则，P1）。
+ *
+ * 「发布前质量门」大脑：把编辑器算出的各类信号（对齐错位 / 可打印宽超出 / 槽位未绑定）
+ * 聚合为统一诊断列表 + 定级，并给出 canPublish（有 error 即禁止发布）。
+ *
+ * 纯函数：入参为原语信号（由 host 用 compose/* 算法算出），不直依赖 Sheet/DOM，便于 core 单测与消费系统复用。
+ */
+type SpliceDiagnosticLevel = "error" | "warning";
+/** 可执行修复动作（UI 侧「一键吸附/去绑定/调整」）。 */
+type SpliceDiagnosticFix = "snap" | "unbind" | "adjust";
+interface SpliceDiagnostic {
+    level: SpliceDiagnosticLevel;
+    /** 稳定 code，便于 UI 定位与 i18n */
+    code: string;
+    /** 人读位置，如「中区 C 列」「表尾」「中区 R8」 */
+    location: string;
+    message: string;
+    fix?: SpliceDiagnosticFix;
+    /** 关联槽位（未绑定类） */
+    slotKey?: string;
+}
+interface SpliceMisalignSignal {
+    location: string;
+    /** 列宽超出母版像素（>0 视为 error；未知可省略仅标错位 warning） */
+    colOverflowPx?: number;
+    /** 行高不足等（true → warning） */
+    rowUnderfilled?: boolean;
+}
+interface SpliceUnboundSlotSignal {
+    slotKey: string;
+    location: string;
+}
+interface SpliceDiagnosticsSignals {
+    /** 中区各段对齐错位信号 */
+    misaligned?: SpliceMisalignSignal[];
+    /** 合成后可打印宽超出（px）；>0 → error（发布拦截） */
+    printableOverflowPx?: number;
+    /** @槽位存在但未绑定字段 → warning */
+    unboundSlots?: SpliceUnboundSlotSignal[];
+    /** 额外自定义诊断（宿主注入） */
+    extra?: SpliceDiagnostic[];
+}
+interface SpliceDiagnosticsReport {
+    diagnostics: SpliceDiagnostic[];
+    errorCount: number;
+    warningCount: number;
+    /** 无 error 才允许发布 */
+    canPublish: boolean;
+}
+declare function buildSpliceDiagnostics(signals: SpliceDiagnosticsSignals): SpliceDiagnosticsReport;
+
+/**
+ * 签名/签章工作流聚合（UI-05，SignaturePort 的 core 支撑）。
+ *
+ * 给定设计态签名位 SignatureSpec[] 与已采集 SignatureResult[]，聚合每位状态 + 完成门
+ * （所有 required 已签才 canComplete）。纯函数，采集/证书/时间戳由宿主 SignaturePort 实现。
+ */
+
+type SignatureSlotStatus = "signed" | "pending" | "missingRequired";
+interface SignatureSlotState {
+    slotId: string;
+    name: string;
+    kind: SignatureKind;
+    role?: string;
+    required: boolean;
+    status: SignatureSlotStatus;
+    result?: SignatureResult;
+}
+interface SignatureWorkflowReport {
+    slots: SignatureSlotState[];
+    signedCount: number;
+    requiredCount: number;
+    missingRequiredCount: number;
+    /** 所有 required 均已签 → 可完成/发布 */
+    canComplete: boolean;
+}
+declare function buildSignatureWorkflow(specs: readonly SignatureSpec[], results: readonly SignatureResult[]): SignatureWorkflowReport;
+/** 下一个待签（required 优先）；无则 null。供「去签名」引导。 */
+declare function nextPendingSignature(report: SignatureWorkflowReport): SignatureSlotState | null;
+
+/**
+ * 签名工作流 ↔ embed 资产模型桥接（UI-05）。
+ *
+ * 设计态签名位 = `assetKind: "signature" | "stamp"` 的 AssetEmbedDef；
+ * 运行态结果 = `EmbedInstanceState`（fileId + signedBy + signedAt）。
+ * 本桥把两者映射为 SignatureSpec / SignatureResult，供 buildSignatureWorkflow 与签署工作台使用。纯函数。
+ */
+
+/** 从 workbook.embeds 提取签名位 → SignatureSpec[]（signature→手写、stamp→图片印章）。 */
+declare function signatureSpecsFromEmbeds(embeds: readonly WorkbookEmbedDef[] | null | undefined): SignatureSpec[];
+/** 从实例 embedStates 还原已落章的 SignatureResult[]（有 fileId 视为已签）。 */
+declare function signatureResultsFromEmbedStates(embedStates: Record<string, EmbedInstanceState> | null | undefined): SignatureResult[];
+/** 把签署/作废后的结果并回 embedStates（供持久化到实例 data）。 */
+declare function applySignatureResultsToEmbedStates(prev: Record<string, EmbedInstanceState> | null | undefined, results: readonly SignatureResult[], removedSlotIds?: readonly string[]): Record<string, EmbedInstanceState>;
+
+/**
+ * 内置参数（systemParam）运行态——纯函数子集（无 store / window 依赖）。
+ *
+ * host 相关的 buildSystemParams* / readClientBrandingParams / applyCatalogSessionParams
+ * 因依赖 ShellBranding store、workbookPrintPlan、businessSheetProfile 仍留在 kt-web。
+ */
+type SystemParamMap = Record<string, unknown>;
+type SystemParamBranding = {
+    tenantName?: string;
+    userDisplayName?: string;
+    userLoginName?: string;
+};
+/** 按 sheet 渲染内置参数时：剔除运行态求值项，避免 activeSheet 注入的页码污染其它 Tab */
+declare function stripRuntimeComputedUserParams(params: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/** displayText / remark 中是否含已知内置参数 token（含废弃别名 pageCurrent 等） */
+declare function templateContainsSystemParamTokens(template: string): boolean;
+/**
+ * field 公式 p.xxx 成员访问：在规范 params 上镜像废弃别名键，便于 `p.pageCurrent` 等旧写法。
+ */
+declare function enrichParamsForFieldRuntime(params: Record<string, unknown> | null | undefined): Record<string, unknown>;
+declare function expandSystemParamTemplate(template: string, params: Record<string, unknown> | null | undefined): string;
+/**
+ * 把系统参数与现有实例参数合并：
+ * - 系统参数为兜底，被用户/实例数据中的同名非空值覆盖（systemParam 格也可能手填校稿）。
+ * - 运行态专有项（pageNumber/totalPageNumber 等）不接受非数值占位覆盖。
+ * - 实例 params 键名归一为规范编码（兼容历史别名如 pageCurrent）。
+ */
+declare function mergeSystemAndUserParams(system: SystemParamMap, existingParams: Record<string, unknown> | null | undefined): SystemParamMap;
+
+type CompileResult = {
+    ok: true;
+    target: FormulaCatalogTarget;
+    source: string;
+    assignment: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** 用户赋值式 → 编译为 field formula `:= rhs` */
+declare function compileFormulaAssignment(input: string): CompileResult;
+/** 从编译 source 提取依赖字段 id（简化：m.xxx / sN.xxx / b.xxx） */
+declare function extractFormulaDeps(source: string): string[];
+declare function catalogEntryNodeId(entry: {
+    id: string;
+    target?: FormulaCatalogTarget;
+}): string;
+
+/** 网格公式求值器：AST → FormulaValue */
+
+declare function evaluate(ast: AstNode, ctx: EvalContext): FormulaAny;
+
+/**
+ * 公式何时执行：UI runWhen ↔ formulaJson / catalog
+ */
+
+type FormulaRunWhen = "auto" | "manualOnly";
+type ComputePass = "incremental" | "full";
+declare const FORMULA_RUN_WHEN_LABELS: Record<FormulaRunWhen, string>;
+type RunWhenSource = {
+    runWhen?: FormulaRunWhen;
+    triggers?: Array<"onCommit" | "onCompute">;
+};
+/** 从 runWhen 或旧 triggers 推导执行模式；默认 auto */
+declare function normalizeFormulaRunWhen(src?: RunWhenSource | null): FormulaRunWhen;
+declare function runWhenToStorage(runWhen: FormulaRunWhen): {
+    runWhen: FormulaRunWhen;
+    triggers: Array<"onCompute">;
+};
+declare function shouldRunFieldFormula(meta: CellFormulaBindingMeta | null | undefined, pass: ComputePass): boolean;
+declare function shouldRunScriptBlock(meta: CellFormulaBindingMeta | null | undefined, pass: ComputePass): boolean;
+declare function catalogEntryRunWhen(entry: Pick<FormulaCatalogEntry, "runWhen" | "triggers">): FormulaRunWhen;
+
+/**
+ * field 公式 inputWhen 门禁：输入满足条件时才计算
+ */
+
+type FieldInputWhen = "always" | "anyPresent" | "allPresent";
+type FormulaInputTarget = {
+    kind: "main";
+    key: string;
+} | {
+    kind: "base";
+    key: string;
+} | {
+    kind: "subRow";
+    subSchemaId: number;
+    col: string;
+};
+type InputDep = {
+    kind: "main";
+    key: string;
+} | {
+    kind: "base";
+    key: string;
+} | {
+    kind: "row";
+    key: string;
+} | {
+    kind: "subCol";
+    subSchemaId: number;
+    key: string;
+};
+/** 从公式体自动提取 row.xxx 字段名 */
+declare function extractRowInputFields(source: string): string[];
+/** 合并 m/b/sN + row.* 依赖，排除公式目标自身 */
+declare function resolveInputDeps(source: string, target?: FormulaInputTarget | null): InputDep[];
+declare function isSubColumnPresent(data: FieldDataCtx, subSchemaId: number, colKey: string): boolean;
+/**
+ * 判断是否应执行 field 公式。
+ * 不满足 inputWhen 时返回 false（调用方应写 null，不记错误）。
+ */
+declare function shouldComputeFieldByInput(meta: CellFormulaBindingMeta, source: string, data: FieldDataCtx, scope: {
+    kind: "main";
+} | {
+    kind: "sub";
+    subSchemaId: number;
+    rowIndex: number;
+}, target?: FormulaInputTarget | null): boolean;
+
+/**
+ * 模板包内嵌字段注册表——纯逻辑（规范化 / 深拷贝 / 索引 / meta 读写 / 校验 / 信封解析）。
+ *
+ * host 相关（upsert/remove/replace 依赖 agent subSchemaId 归一、knownFieldKeysStore 同步）
+ * 仍留在 kt-web templateFieldRegistry.ts。
+ */
+
+type FieldRegistryIndex = {
+    baseByKey: Map<string, TemplateFieldDef>;
+    mainByKey: Map<string, TemplateFieldDef>;
+    subBySchema: Map<number, Map<string, TemplateSubFieldDef>>;
+};
+type UpsertFieldDefInput = {
+    bindingKey: string;
+    displayName?: string;
+    dataType?: string;
+    roundingJson?: string | null;
+    formulaJson?: string | null;
+    dictCode?: string | null;
+    requiredDefault?: boolean;
+    defaultValue?: string | null;
+    runtimeEditable?: boolean;
+    writebackTarget?: string | null;
+    description?: string | null;
+    sortOrder?: number;
+    enabled?: boolean;
+};
+declare function isFieldRegistryRecord(x: unknown): x is Record<string, unknown>;
+declare function normalizeFieldKey(k: string | null | undefined): string;
+declare function normalizeFieldDef(raw: unknown): TemplateFieldDef | null;
+declare function normalizeSubFieldDef(raw: unknown): TemplateSubFieldDef | null;
+/** 空注册表 */
+declare function emptyFieldRegistry(): TemplateFieldRegistry;
+/** 解析/规范化 meta 或 capabilities 中的 fieldRegistry */
+declare function normalizeFieldRegistry(raw: unknown): TemplateFieldRegistry;
+/** 深拷贝 */
+declare function cloneFieldRegistry(reg: TemplateFieldRegistry): TemplateFieldRegistry;
+/** 从 workbook.meta 取 registry，缺省返回空 */
+declare function getFieldRegistryFromMeta(meta: {
+    fieldRegistry?: unknown;
+} | null | undefined): TemplateFieldRegistry;
+/** 写入 meta（返回新 meta 对象） */
+declare function setFieldRegistryOnMeta(meta: Record<string, unknown> | undefined, reg: TemplateFieldRegistry): Record<string, unknown>;
+/** 建索引（仅 enabled 字段） */
+declare function indexFieldRegistry(reg: TemplateFieldRegistry | null | undefined): FieldRegistryIndex;
+type FieldDefRegisterMode = "upsert" | "bindingOnly" | "reject";
+/** 业务模板 b.* 仅写 binding；基础模板 main/sub 拒绝 */
+declare function resolveFieldDefRegisterMode(isBaseDraft: boolean, kind: BaseTemplateCellBinding["kind"]): FieldDefRegisterMode;
+declare function fieldPartitionKey(kind: BaseTemplateCellBinding["kind"]): "base" | "main" | "sub" | null;
+/** 合并 base 段（继承初始化：以母版为准整段替换） */
+declare function mergeBaseFieldPartition(reg: TemplateFieldRegistry, baseFromSource: TemplateFieldDef[]): TemplateFieldRegistry;
+/** 合并 base（来自基础快照）+ main/sub（来自业务草案）供 bake */
+declare function mergeBakedFieldRegistry(baseFromSnapshot: TemplateFieldDef[], draftReg: TemplateFieldRegistry, usedBaseKeys: Set<string>, usedMainKeys: Set<string>, usedSubKeys: Map<number, Set<string>>): TemplateFieldRegistry;
+/** 从 capabilities JSON 解析 fieldRegistry */
+declare function parseFieldRegistryFromCapabilities(capabilities: string | Record<string, unknown> | null | undefined): TemplateFieldRegistry | null;
+/** 从 workbook 信封 JSON 读取 meta.fieldRegistry.base（继承初始化 fallback） */
+declare function extractBaseFieldDefsFromWorkbookEnvelope(workbookJson: string): TemplateFieldDef[];
+/** 将 base 段写入 workbook 信封 JSON 的 meta.fieldRegistry */
+declare function injectBaseFieldRegistryIntoWorkbookEnvelope(workbookJson: string, baseDefs: TemplateFieldDef[]): string;
+/** 从基础快照 capabilities 或 workbook 解析 base 段（capabilities 优先） */
+declare function resolveBaseFieldDefsFromBaseSource(input: {
+    capabilities?: string | null;
+    workbookJson: string;
+}): TemplateFieldDef[];
+
+/**
+ * 设计态字段行 `#类型[:小数位[:修约简码]]` 简写解析（方案 B）。
+ * 格内绑定仅存前缀+键名；类型与修约写入字段注册表。
+ */
+
+type DesignFieldMetaFromShorthand = {
+    dataType: string;
+    roundingJson?: string;
+    /** image 字段存储方式 */
+    imageStorage?: "base64" | "fileId" | "url";
+};
+/** 修约简码 → roundMode（与 cellMeta / FieldRoundingForm 一致） */
+declare const ROUND_MODE_LETTER_MAP: Record<string, CellRoundingMeta['roundMode']>;
+/** 将第一个 `#` 拆为绑定段与类型简写段 */
+declare function splitBindingAndTypeSuffix(raw: string): {
+    bindingPart: string;
+    typeSpec?: string;
+};
+/**
+ * 解析 `#` 后的类型简写段。
+ * 格式：`{类型}[:{小数位}[:{修约简码}]]`
+ */
+declare function parseFieldTypeSpec(spec: string): DesignFieldMetaFromShorthand | null;
+/** 由字段 meta 反显简写段（不含 `#` 与前缀） */
+declare function formatFieldTypeShorthand(meta: DesignFieldMetaFromShorthand): string;
+/** Agent / 技能注入用：字段行类型修约简写说明 */
+declare const DESIGN_FIELD_SHORTHAND_SKILLS = "### \u5B57\u6BB5\u884C\u7C7B\u578B/\u4FEE\u7EA6\u7B80\u5199\uFF08registerSelectionToFields \u81EA\u52A8\u843D\u5E93\uFF09\n\u683C\u5F0F\uFF1A`{\u524D\u7F00}{\u5B57\u6BB5\u952E}#{\u7C7B\u578B}[:{\u5C0F\u6570\u4F4D}[:{\u4FEE\u7EA6\u7B80\u7801}]]`\n- \u524D\u7F00\uFF1A`b.` / `m.` / `sN.` / `d.` / `p.`\uFF08\u6CE8\u518C\u987B\u663E\u5F0F\u524D\u7F00\uFF09\n- \u7C7B\u578B\uFF1A`n` number\u3001`i` integer\u3001`s` string\u3001`d` date\u3001`dt` datetime\u3001`b` boolean\n- \u6570\u503C\uFF1A`#n` \u6216 `#n:1` \u9ED8\u8BA4 scale=1\u3001\u4FEE\u7EA6 half_even\uFF08\u6B63\u5E38\u4FDD\u7559\uFF09\uFF1B\u7B2C\u4E09\u6BB5\u4FEE\u7EA6\u7B80\u7801\u53EF\u9009\n- \u4FEE\u7EA6\u7B80\u7801\uFF1A\u7701\u7565\u6216 `a`/`e`=half_even\uFF08\u6B63\u5E38\u4FDD\u7559\uFF09\u3001`u`=\u56DB\u820D\u4E94\u5165\u3001`t`=\u622A\u65AD\u3001`c`=\u5411\u4E0A\u3001`f`=\u5411\u4E0B\n- \u793A\u4F8B\uFF1A`s1.lq#n:1`\u3001`m.wt#n:2:u`\u3001`m.remark#s`\u3001`m.test_date#d`\u3001`s1.cnt#i`\n- \u6CE8\u518C\u540E\u683C\u5185 value \u89C4\u8303\u4E3A `s1.lq`\uFF08\u65E0 # \u6BB5\uFF09\uFF1B\u7C7B\u578B/\u4FEE\u7EA6\u4EC5\u5B58\u5B57\u6BB5\u8868\n- \u65E0 `#` \u65F6\u4ECD\u9ED8\u8BA4 string\uFF08\u5411\u540E\u517C\u5BB9\uFF09\uFF1B\u5DF2\u5B58\u5728\u5B57\u6BB5\u4EC5\u5728\u5E26 `#` \u7B80\u5199\u65F6\u66F4\u65B0 dataType/\u4FEE\u7EA6";
+/** 子表 @槽位绑定（替代 subTableRegions） */
+declare const SUBTABLE_SLOT_BINDING_SKILLS = "### \u5B50\u8868 @\u69FD\u4F4D\u7ED1\u5B9A\uFF08\u5FC5\u5B88\uFF0C\u5DF2\u66FF\u4EE3 subTableRegions\uFF09\n- \u8BED\u6CD5\uFF1A`s{N}.{fieldKey}[#{typeSpec}]@{slot}` \u2014 **@ \u5FC5\u987B\u5728\u6700\u540E**\uFF0C\u4F8B `s1.sq#n:2@1`\n- **subField \u5FC5\u987B\u5E26 @slot**\uFF1B\u540C\u7EC4\u591A\u683C\uFF08sjcc1@1 / sjcc2@1\uFF09\u5171\u4EAB `subTables[\"N\"].rows[globalIndex]`\n- globalIndex = logicalPageIndex \u00D7 slotsPerPage + (slot - 1)\uFF1B\u6301\u4E45\u5316 `subTables[\"1\"].rows[7]` \u800C\u975E\u5750\u6807\u586B\u683C\n- \u6BCF sheet\u00D7subSchema \u914D\u7F6E `meta.subTableSlotConfig` \u6BCF\u9875\u7EC4\u6570\uFF1B\u7F3A\u7701 = \u8BE5 sheet \u6700\u5927 @ \u69FD\u4F4D\n- \u7981\u6B62\u521B\u5EFA subTableRegions\uFF1BlistValidationErrors \u7F3A @ \u4E3A error\n- Agent \u586B\u6570\uFF1AfillInstanceFields \u2192 `subTables[\"1\"].rows[i].fieldKey`\uFF0C\u52FF\u7528 fillInstanceBatch \u586B\u5DF2\u7ED1\u5B9A\u5B50\u8868\u5B57\u6BB5";
+
+/**
+ * 工作簿打印计划纯类型（RenderContext 等），驱动 systemParam 页码/表序求值。
+ * 逻辑（buildWorkbookPrintPlan / buildRenderContext* 依赖 businessSheetProfile、instancePageTabs）留 kt-web。
+ */
+interface PrintPageSlot {
+    sheetId: string;
+    /** 该 sheet 内第几逻辑页（0-based） */
+    sheetLogicalPageIndex: number;
+    /** 工作簿全局第几页（0-based） */
+    globalPageIndex: number;
+}
+interface WorkbookPrintPlan {
+    slots: PrintPageSlot[];
+    globalPageCount: number;
+}
+/** 单次渲染/预览/打印页的上下文，驱动系统参数求值 */
+interface RenderContext {
+    sheetId: string;
+    sheetLogicalPageIndex: number;
+    globalPageIndex: number;
+    globalPageCount: number;
+    /** sheets[] 中位置（1-based） */
+    sheetIndex: number;
+    /** profile.displayName ?? sheet.name */
+    sheetName: string;
+    /** false：隐藏页，pageNumber/totalPageNumber 留空（缺省 true） */
+    includeInPageNumber?: boolean;
+}
+
+interface LayoutLinesResult {
+    lines: string[];
+    fontSizePt: number;
+}
+/** shrinkToFit 字号下限（pt）。1pt 几乎能缩尽，避免触底后折行把行撑开。 */
+declare const MIN_SHRINK_FONT_PT = 1;
+/**
+ * 换行 / shrink 测量用字重斜体。须与渲染侧一致，否则加粗会低估宽度。
+ * 字重用 CSS `bold`（与 sheet-report `fontWeight: "bold"` 对齐）。
+ */
+type LayoutFontStyleOpts = {
+    bold?: boolean;
+    italic?: boolean;
+};
+/** 拼 canvas/CSS 可用的 font 串：`[style] [weight] [size]px [family]`。 */
+declare function layoutFontCss(fontPx: number, fontFamily: string, style?: LayoutFontStyleOpts): string;
+/**
+ * 文本测量抽象（去 UI 化 M1.1）。
+ * core 不得直依赖 `CanvasRenderingContext2D`；换行/shrink 算法只依赖本接口。
+ * 与 `@k-table/sheet-host` 的 `TextMeasurePort` 对齐；由宿主注入具体实现（如 canvas adapter）。
+ */
+interface TextMeasurer {
+    /** 测量给定 css font（如 "normal bold 10.5px sans-serif"）下文本宽度（px）。 */
+    measure(text: string, font: string): number;
+}
+/** 软换行（measurer 版，纯逻辑，无 DOM 依赖）。 */
+declare function wrapTextToWidthM(measurer: TextMeasurer, font: string, text: string, maxWidth: number): string[];
+/** shrinkToFit（measurer 版）：先按 wrapText 折行，仍超格再缩字；仅 shrink 只压宽不自动折。 */
+declare function layoutLinesForCellM(measurer: TextMeasurer, text: string, cellInnerWidth: number, cellInnerHeight: number, baseFontSizePt: number, wrapText: boolean, shrinkToFit: boolean, fontFamily?: string, fontStyle?: LayoutFontStyleOpts): LayoutLinesResult;
+
+/** CSS px/inch，与画布及 Excel 导出换算一致 */
+declare const CSS_PX_PER_INCH = 96;
+declare const MM_PER_INCH = 25.4;
+declare function mmToCssPx(mm: number): number;
+/** 与打印假定的逻辑 CSS 像素下物理长度（用于状态栏等） */
+declare function cssPxToCm(px: number): number;
+/**
+ * 在 96 CSS px/英寸 假定下，1 cm 对应多少 CSS px（`cssPxToCm` 的标度：约 37.8 px/cm）。
+ */
+declare function cssOneCmToCssPx(): number;
+/** 页边距 cm → mm（与存库/打印数学一致） */
+declare function marginsCmToMm(m: PageMarginsCm): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** 纸张外廓（mm），不含方向 */
+declare function paperSizeMmRaw(paper: SheetPaperKind): {
+    widthMm: number;
+    heightMm: number;
+};
+/** 应用横纵向后的纸张宽高（mm） */
+declare function paperSizeMm(paper: SheetPaperKind, orientation: SheetOrientation): {
+    widthMm: number;
+    heightMm: number;
+};
+/**
+ * 按整份 PageSettings 求纸张宽高（mm）。
+ * `paper === "Custom"` 时取 `widthMm/heightMm` 原值（orientation 不参与换算；缺失回落 A4）。
+ */
+declare function paperSizeMmFromPage(page: PageSettings$1): {
+    widthMm: number;
+    heightMm: number;
+};
+/**
+ * 输出物理纸张宽高（mm）：`outputRotation` 90/270 时交换设计宽高。
+ * 版式/可印区域仍按设计坐标系（`paperSizeMmFromPage`）计算，仅输出（@page、PDF 页）用物理尺寸。
+ */
+declare function physicalPaperSizeMmFromPage(page: PageSettings$1): {
+    widthMm: number;
+    heightMm: number;
+};
+/** 可印区域 = 纸张 − 边距（边距为 cm，内部换算为 mm） */
+declare function printableSizeMm(page: PageSettings$1): {
+    widthMm: number;
+    heightMm: number;
+};
+declare function printableSizeCssPx(page: PageSettings$1): {
+    widthPx: number;
+    heightPx: number;
+};
+/** `@page` 用：具名纸张 + 四边距（cm 存库，写 CSS 为 mm） */
+declare function pageAtRuleCss(page: PageSettings$1): string;
+/** jsPDF format 名（与纸张对应） */
+declare function jsPdfFormat(page: PageSettings$1): "a4" | "a3" | "letter";
+declare function jsPdfOrientation(page: PageSettings$1): "p" | "l";
+/** 内容区切片（逻辑像素，与导出画布同一坐标系） */
+declare function sliceRectangles(contentWidth: number, contentHeight: number, sliceWidth: number, sliceHeight: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}[];
+/** 将 cm 边距转为 jsPDF 用的 pt（72pt/inch，经 mm） */
+declare function marginsCmToPt(m: PageMarginsCm): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+
+/**
+ * 报表按行分页 — 页眉/页脚行区间每物理页重复，正文行按可用高度切页。
+ *
+ * 与 `print/pageGeometry.sliceRectangles`（像素矩形切片）不同：报表分页以「行」为
+ * 最小单位，保证行不被腰斩，且 `PageSettings.pageHeaderRows/pageFooterRows`
+ * 指定的行区间在每一物理页重复渲染。
+ */
+
+/** 1-based 含端点的连续行区间 */
+type ReportRowSegment = {
+    startRow: number;
+    endRow: number;
+};
+type ReportPhysicalPage = {
+    /** 0-based 物理页序号 */
+    pageIndex: number;
+    /** 每页重复的页眉行区间（无则 null） */
+    headerRows: ReportRowSegment | null;
+    /** 本页正文行（连续段列表；正文行剔除页眉页脚行后可能不连续） */
+    bodySegments: ReportRowSegment[];
+    /** 每页重复的页脚行区间（无则 null） */
+    footerRows: ReportRowSegment | null;
+};
+type PaginateReportRowsArgs = {
+    rowCount: number;
+    /** index 0 = 第 1 行；缺省行用 defaultRowHeight */
+    rowHeights?: number[] | null;
+    defaultRowHeight: number;
+    page: PageSettings$1;
+};
+type ReportPaginationResult = {
+    pages: ReportPhysicalPage[];
+    /** 可印区域高度（CSS px，96dpi） */
+    printableHeightPx: number;
+    headerHeightPx: number;
+    footerHeightPx: number;
+    /** 每页正文可用高度 = printable − header − footer */
+    bodyAvailPx: number;
+};
+/**
+ * 报表按行分页。页眉/页脚行高从正文可用高度中扣除；
+ * 单行高度超过可用高度时独占一页（内容溢出交由渲染端裁剪/缩放）。
+ */
+declare function paginateReportRows(args: PaginateReportRowsArgs): ReportPaginationResult;
+
+/**
+ * 报表无状态灌数 — 快照 workbook + 字段数据 → 已填值 workbook。
+ *
+ * 面向报表渲染（@k-table/sheet-report）与服务端 PDF 的最小灌数管线：
+ * - `baseTemplateBinding` 绑定格：basicField / mainField / subField / systemParam
+ * - 纯文本格：`{b.x}` `{m.x}` `{p.x}` `{sN.x}` 占位符展开
+ * - 未命中数据的绑定格默认清空（避免打印出设计占位文本）
+ *
+ * 遗留（LIMS `[#M2].value` 等）绑定不在本模块处理，宿主应先行转换。
+ */
+
+/** 报表字段数据包（键大小写不敏感；子表 s 按 subSchemaId 分组、数组序 = 行序） */
+type ReportFieldData = {
+    /** 基础字段 b.* */
+    b?: Record<string, unknown>;
+    /** 主表字段 m.* */
+    m?: Record<string, unknown>;
+    /** 子表：subSchemaId → 行数组（每行为 key→value） */
+    s?: Record<string | number, Array<Record<string, unknown>>>;
+    /** 用户/系统参数 p.*（与 systemParams 合并，systemParams 优先） */
+    params?: Record<string, unknown>;
+};
+type HydrateFieldDataOptions = {
+    /** 页码等系统参数（通常由打印编排注入） */
+    systemParams?: Record<string, unknown>;
+    /** 绑定格无数据时清空显示（默认 true） */
+    clearUnresolvedBindings?: boolean;
+};
+/** 展开纯文本中的 `{b.x}` `{m.x}` `{p.x}` `{sN.x}` 占位符；未命中保持原样 */
+declare function expandFieldTokens(text: string, data: ReportFieldData, systemParams?: Record<string, unknown>): string;
+/** 对单个 sheet 灌数（纯函数，返回新对象） */
+declare function hydrateSheetFieldData(sheet: SheetTemplateState, data: ReportFieldData, options?: HydrateFieldDataOptions): SheetTemplateState;
+/** 对整个 workbook 灌数（纯函数，返回新对象） */
+declare function hydrateWorkbookFieldData(workbook: TemplateWorkbookState, data: ReportFieldData, options?: HydrateFieldDataOptions): TemplateWorkbookState;
+
+/**
+ * 报表共用表头表尾 — 模板条带提取与设计时合成（纯函数）。
+ *
+ * 「表头表尾模板」是一个普通报表 workbook：单 sheet，用
+ * `page.pageHeaderRows` / `page.pageFooterRows` 标出表头/表尾行区间。
+ * 应用时把模板条带合成进目标报表（顶部插入表头、底部追加表尾；
+ * 目标已有区间则整段替换），合成结果自包含、无运行时依赖。
+ */
+
+/** 单条带：行号以条带内 1-based 相对坐标表示 */
+type HeaderFooterStrip = {
+    rowCount: number;
+    /** index 0 = 条带第 1 行 */
+    rowHeights: number[];
+    cells: Record<string, CellData$1>;
+    merges: MergeRange[];
+};
+type ReportHeaderFooterStrips = {
+    header: HeaderFooterStrip | null;
+    footer: HeaderFooterStrip | null;
+    colCount: number;
+    colWidths?: number[];
+    defaultRowHeight: number;
+};
+/**
+ * 从模板 workbook 提取表头/表尾条带。
+ * 取 sheetId 指定的 sheet（缺省首个）；两个区间均缺失时返回 null。
+ */
+declare function extractHeaderFooterStrips(tpl: TemplateWorkbookState, sheetId?: string): ReportHeaderFooterStrips | null;
+type ApplyHeaderFooterOptions = {
+    /** 仅应用到指定 sheet；缺省全部 sheet */
+    sheetIds?: string[];
+};
+/**
+ * 把模板条带合成进目标报表（返回新 workbook，不修改入参）。
+ * - 模板含表头：移除目标旧 pageHeaderRows 区间行，条带插到顶部并重标区间；
+ * - 模板含表尾：移除目标旧 pageFooterRows 区间行，条带接到底部并重标区间；
+ * - 模板缺某一部分时，目标对应部分保持不变；
+ * - 正文 cells / merges / meta.report.bands 行坐标随位移平移。
+ */
+declare function applyReportHeaderFooterTemplate(target: TemplateWorkbookState, strips: ReportHeaderFooterStrips, options?: ApplyHeaderFooterOptions): TemplateWorkbookState;
+/**
+ * 从当前报表切出表头表尾，落成独立的模板 workbook（用于导出 .ktl 模板文件）。
+ * 结构：表头条带 + 1 行空正文 + 表尾条带，并标好 pageHeaderRows/pageFooterRows。
+ */
+declare function buildHeaderFooterTemplateWorkbook(source: TemplateWorkbookState, sheetId?: string): TemplateWorkbookState | null;
+
+/**
+ * 报表槽位翻页展开 — 与业务模版「每页子表槽位」同思路的固定版式自动翻页。
+ *
+ * 模板 sheet 用 `subField + subRowSlot`（0-based 页内槽位）绑定子表字段，
+ * 每页槽位数取 `meta.subTableSlotConfig` 配置，缺省按最大槽位号 + 1 推断。
+ * 展开时按数据行数把 sheet 复制为多个逻辑页副本，副本内重写
+ * `subRowSlot = 页序 × slotsPerPage + 槽位`，交由 hydrate 直接按行号取数。
+ *
+ * 典型场景：针式样品标签小卡（每页 1 张卡 = 1 个样品，N 个样品 N 页）。
+ */
+
+/**
+ * 按子表数据行数展开槽位逻辑页（纯函数，返回新 workbook）。
+ * - 无槽位绑定的 sheet 原样保留；
+ * - 数据为空时保留 1 页（绑定格由 hydrate 清空）；
+ * - 多个子表并存时页数取各子表所需页数的最大值，各自按窗口推进。
+ */
+declare function expandReportSlotPages(workbook: TemplateWorkbookState, fieldData: ReportFieldData | undefined): TemplateWorkbookState;
+
+/**
+ * 报表/标签智能缩放 — 把版式从原纸张适配到新纸张尺寸。
+ *
+ * 不是无脑等比：按新旧「可打印区域」分别缩放列宽（横向）与行高（纵向），
+ * 并施加最小尺寸约束（标签行高/列宽/字号有可读下限）；因下限被挡住导致
+ * 内容放不下时返回警告，交由界面提示用户手动微调。
+ */
+
+type RescaleTargetSize = {
+    widthMm: number;
+    heightMm: number;
+};
+type RescaleOptions = {
+    /** 行高下限（CSS px），默认 14 */
+    minRowHeightPx?: number;
+    /** 列宽下限（CSS px），默认 24 */
+    minColWidthPx?: number;
+    /** 字号下限（pt），默认 6 */
+    minFontSizePt?: number;
+    /** 是否缩放字号（默认 true；仅缩小、不放大） */
+    scaleFontSize?: boolean;
+};
+type RescaleSheetResult = {
+    sheet: SheetTemplateState;
+    warnings: string[];
+};
+/**
+ * 把 sheet 版式从当前纸张缩放到 `target`（mm）。纯函数：
+ * - 列宽按可打印宽度比缩放、行高按可打印高度比缩放（各自 clamp 下限）；
+ * - 字号按 min(sx, sy) 只缩不放（clamp 下限）；
+ * - page 置为 Custom + 新宽高；
+ * - 因 clamp 导致内容超出新可打印区域时输出警告。
+ */
+declare function rescaleReportSheet(sheet: SheetTemplateState, target: RescaleTargetSize, options?: RescaleOptions): RescaleSheetResult;
+/** workbook 级便捷封装：所有 sheet 应用同一目标尺寸 */
+declare function rescaleReportWorkbook(workbook: TemplateWorkbookState, target: RescaleTargetSize, options?: RescaleOptions): {
+    workbook: TemplateWorkbookState;
+    warnings: string[];
+};
+
+/**
+ * 网格 ↔ 纸张 ↔ Excel 尺寸的统一换算（CSS px @ 96dpi）。
+ * 显示、导入、导出、打印预览共用本模块，保证列宽/行高比例一致。
+ */
+
+/** Excel 默认行高（pt）与列宽（字符数） */
+declare const EXCEL_DEFAULT_ROW_HEIGHT_PT = 15;
+declare const EXCEL_DEFAULT_COL_WIDTH_CHAR = 8.43;
+/** OOXML 近似：pixel = round(charWidth × 7 + 5)（Calibri 11pt） */
+declare const EXCEL_COL_DIGIT_WIDTH_PX = 7;
+declare const EXCEL_COL_PADDING_PX = 5;
+/** Canvas 导入表 row=0/col=0 索引 gutter 的典型尺寸（px） */
+declare const CHROME_GUTTER_COL_WIDTH_PX = 40;
+declare const CHROME_GUTTER_ROW_HEIGHT_PX = 24;
+type GridLayoutMode = "compact" | "chrome";
+type SheetDataRegion = {
+    r1: number;
+    r2: number;
+    c1: number;
+    c2: number;
+};
+/** Excel 列宽（字符）→ CSS px */
+declare function excelColWidthToPx(charW: number): number;
+/** CSS px → Excel 列宽（字符），与 excelColWidthToPx 互逆 */
+declare function pxToExcelColWidth(px: number): number;
+/** Excel 行高（pt）→ CSS px */
+declare function excelRowHeightPtToPx(pt: number): number;
+/** CSS px → Excel 行高（pt） */
+declare function pxToExcelRowHeightPt(px: number): number;
+/**
+ * compact：KTL/报表模板，rowCount/colCount 即数据区，colWidths[i] = 第 i+1 列（px）
+ * chrome：Canvas/Excel 导入，含 row0/col0 索引 gutter
+ */
+declare function detectGridLayoutMode(sheet: SheetTemplateState): GridLayoutMode;
+/** 数据区 1-based 行列边界（不含 gutter） */
+declare function sheetDataRegion(sheet: SheetTemplateState): SheetDataRegion;
+/** 第 col 列（1-based）宽 px */
+declare function sheetDataColWidthPx(sheet: SheetTemplateState, col1Based: number): number;
+/** 第 row 行（1-based）高 px */
+declare function sheetDataRowHeightPx(sheet: SheetTemplateState, row1Based: number): number;
+/** 数据区总宽/总高（px） */
+declare function sheetDataGridWidthPx(sheet: SheetTemplateState): number;
+declare function sheetDataGridHeightPx(sheet: SheetTemplateState): number;
+/** 内容宽超出可印宽时的等比缩放系数（只缩不放） */
+declare function computeFitScale(contentWidthPx: number, printableWidthPx: number): number;
+/** 按目标总宽等比缩放列宽数组，保持比例；可选单列下限 */
+declare function scaleWidthsProportional(widths: number[], targetTotalPx: number, minColPx?: number): number[];
+type FitGridToPageOptions = {
+    /** 是否同步缩放行高（默认 false，列宽为主） */
+    scaleRows?: boolean;
+    minColWidthPx?: number;
+    minRowHeightPx?: number;
+};
+/**
+ * 将 sheet 数据区列宽（及可选行高）等比缩放到 page 可印区域内；仅缩小、不放大。
+ * 返回新 sheet（compact 模式数组索引）。
+ */
+declare function fitSheetDataGridToPage(sheet: SheetTemplateState, page: PageSettings$1, options?: FitGridToPageOptions): SheetTemplateState;
+/** chrome → compact：去掉 gutter 行/列，保留 1-based 单元格坐标 */
+declare function normalizeSheetToCompactGrid(sheet: SheetTemplateState): SheetTemplateState;
+/** 预览/打印：表格数据区宽 vs 可印宽 → fitScale */
+declare function sheetPrintFitScale(sheet: SheetTemplateState): number;
+
+/**
+ * 单元格 `fontSize` 与 Excel 一致，单位为**磅（pt）**；画布/CSS 用 96dpi 逻辑像素时需换算。
+ * 默认 10 磅（常见正文）。
+ */
+declare const DEFAULT_FONT_SIZE_PT = 10;
+declare const MIN_FONT_SIZE_PT = 1;
+/** 与 Excel 字体大小上限一致 */
+declare const MAX_FONT_SIZE_PT = 409;
+/** pt → CSS/Canvas 像素（96dpi：1in = 96px = 72pt） */
+declare function fontSizePtToCssPx(pt: number): number;
+/** 旧版按 px 存的字号 → 磅（用于模板 v1 迁移） */
+declare function cssPxToFontSizePt(px: number): number;
+declare function clampFontSizePt(pt: number): number;
+
+/**
+ * 内置字体：存短 id（JSON），绘制时展开为跨平台 font-family 栈，Excel 导出用中文名。
+ */
+declare const SHEET_FONT_OPTIONS: {
+    value: string;
+    label: string;
+}[];
+/** Canvas / contenteditable 用 CSS font-family 串 */
+declare function sheetFontFamilyCss(id: string | undefined): string;
+/** exceljs font.name */
+declare function sheetFontFamilyExcelName(id: string | undefined): string | undefined;
+/** 从粘贴 CSS font-family 猜内置 id（无法匹配则 undefined，由调用方忽略或保留扩展） */
+declare function guessSheetFontIdFromCssFontFamily(raw: string): string | undefined;
+
+/**
+ * 网格列标（1-based，含行号列偏移）：0 -> '', 1 -> 'A'。
+ * 注意与 formula/a1 的 columnIndexToLetters（0-based，0 -> 'A'）语义不同，故独立命名。
+ */
+declare function gridColumnIndexToLetters(c0: number): string;
+
+/**
+ * 工具栏取色：两排对齐——
+ * - 第一排：常见「纯色」标准（红/黄/蓝等为 sRGB 纯色），首格为白；
+ * - 第二排：与 Excel 主题接近的常用色，首格为黑（与第一排白同一列对应）。
+ */
+declare const SHEET_COLOR_ROW_STANDARD: readonly {
+    hex: string;
+    label: string;
+}[];
+/** 与 Excel 主题色接近的一组（原「标准色」近似） */
+declare const SHEET_COLOR_ROW_THEME: readonly {
+    hex: string;
+    label: string;
+}[];
+
+declare function defaultPageSettings(): PageSettings$1;
+/**
+ * 统一页边距为 cm；兼容旧 `marginsMm`（读入时 /10 转为 cm）。
+ */
+declare function normalizePageSettings(input: unknown): PageSettings$1;
+
+/**
+ * Excel 导入中间格式 — v1
+ * 设计目标：完整保留 .xlsx 解析信息 + LLM 可理解 + 可还原到 SheetTemplateState
+ */
+interface ExcelImportIntermediateV1 {
+    kind: "kt.excelImport";
+    version: 1;
+    source: {
+        fileName: string;
+        fileSize: number;
+        sheetName: string;
+        sheetIndex: number;
+        parsedAt: string;
+    };
+    dimensions: {
+        rowCount: number;
+        colCount: number;
+        usedRange: {
+            r1: number;
+            c1: number;
+            r2: number;
+            c2: number;
+        };
+    };
+    defaults: {
+        rowHeightPx: number;
+        colWidthPx: number;
+        fontFamily: string;
+        fontSizePt: number;
+    };
+    rowHeights: Record<string, number>;
+    colWidths: Record<string, number>;
+    merges: ExcelImportMerge[];
+    cells: Record<string, ExcelImportCell>;
+    stats: ExcelImportStats;
+    availableSheets: {
+        index: number;
+        name: string;
+    }[];
+    extension?: Record<string, unknown>;
+}
+interface ExcelImportMerge {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+    ref?: string;
+}
+interface ExcelImportCell {
+    value: string;
+    formula?: string;
+    style?: ExcelImportCellStyle;
+    richText?: ExcelImportRichRun[];
+}
+interface ExcelImportCellStyle {
+    fontFamily?: string;
+    fontSizePt?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    textColor?: string;
+    superscript?: boolean;
+    subscript?: boolean;
+    horizontalAlign?: "left" | "center" | "right";
+    verticalAlign?: "top" | "middle" | "bottom";
+    wrapText?: boolean;
+    shrinkToFit?: boolean;
+    bgColor?: string;
+    border?: {
+        top?: ExcelImportBorderSide;
+        right?: ExcelImportBorderSide;
+        bottom?: ExcelImportBorderSide;
+        left?: ExcelImportBorderSide;
+    };
+}
+interface ExcelImportBorderSide {
+    width: "thin" | "medium" | "thick";
+    pattern: "solid" | "dashed" | "dotted";
+    color: string;
+}
+interface ExcelImportRichRun {
+    text: string;
+    style?: {
+        bold?: boolean;
+        italic?: boolean;
+        underline?: boolean;
+        strikethrough?: boolean;
+        superscript?: boolean;
+        subscript?: boolean;
+        fontSizePt?: number;
+        fontFamily?: string;
+        textColor?: string;
+    };
+}
+interface ExcelImportStats {
+    totalCells: number;
+    styledCells: number;
+    mergedRegions: number;
+    formulaCells: number;
+    richTextCells: number;
+}
+interface ExcelImportOptions {
+    sheetIndex: number;
+    keepBorders: boolean;
+    keepFonts: boolean;
+    keepMerges: boolean;
+    keepBackground: boolean;
+    keepFormula: boolean;
+    keepDimensions: boolean;
+}
+declare const DEFAULT_IMPORT_OPTIONS: Omit<ExcelImportOptions, "sheetIndex">;
+
+/** 数据区单元格地址，如 A1、B2（r,c 为 0-based 网格坐标，且 r>=1,c>=1） */
+declare function formatA1(r: number, c: number): string;
+/** 名称框展示：单格 A1；多格 A1:B2（与 Excel 一致） */
+declare function formatSelectionA1(sel: SelectionRect): string;
+/** 1-based 数据格 A1 解析（与 coords.parseA1 的 0-based 语义不同，故独立命名）。 */
+declare function parseA1Cell(s: string): {
+    r: number;
+    c: number;
+} | null;
+/** 名称框跳转：支持 A1 或 A1:B2 / A1:A8 等矩形选区 */
+declare function parseA1OrRangeToSelection(s: string): SelectionRect | null;
+declare function parseGridRcAddress(s: string): {
+    r: number;
+    c: number;
+} | null;
+
+/**
+ * 工作簿计算运行器（M3.0 + M3.1 + M3.2 + M3+）：
+ * 给定工作簿 + 元数据 + 字段数据 + 脚本块，按 3 类公式（grid/field/script）
+ * 统一求值并把结果写回 `wb.sheets[*].sheet.cells[key].value`；
+ * 可选应用单元格修约（`CellRoundingMeta`）。
+ *
+ * 评估策略（简化但正确）：
+ *   1. 先以当前字段数据渲染所有"绑定格"的 `value`；
+ *   2. 计算 field 公式（主/子行级），更新字段数据；
+ *   3. 计算 script 块（CALC_*），写入字段数据或单元格；
+ *   4. 渲染一次绑定格；
+ *   5. 计算 grid 公式（A1 依赖图 + 拓扑顺序）；
+ *   6. 对 onCompute 修约的单元格执行修约；
+ *   7. 如仍有依赖跨类（grid → field），迭代第 2~5 步最多 N 次直到稳定。
+ *
+ * M3+ 支持：
+ *   - 跨表引用 Sheet2!A1 / 'Sheet Name'!A1
+ *   - 工作簿命名区域（namedRanges）
+ */
+
+/**
+ * 系统参数构建器（host 注入）。core 引擎不读任何 UI store；
+ * kt-web 提供读 ShellBranding store 的实现，LIMS/TAM 可提供各自实现或省略（无内置参数）。
+ */
+interface ComputeSystemParamsProvider {
+    buildSystemParams: (wb: TemplateWorkbookState, ctx?: {
+        render?: RenderContext;
+        branding?: SystemParamBranding | null;
+    }) => SystemParamMap;
+    buildSystemParamsForSheet: (wb: TemplateWorkbookState, sheetId: string, logicalState: LogicalState | null | undefined, userParams: Record<string, unknown> | null | undefined, branding: SystemParamBranding | null | undefined) => SystemParamMap;
+}
+interface ComputeInput {
+    wb: TemplateWorkbookState;
+    /** 扁平复合键：`${sheetId}::${r},${c}`，值为合并对象 */
+    cellMeta: Record<string, unknown> | null | undefined;
+    fieldData: FieldDataCtx;
+    /** 多 Tab 各 sheet 独立 pageNumber / totalPageNumber 等 */
+    logicalState?: LogicalState | null;
+    /**
+     * 打印/预览逐页重算时按 sheet 注入 RenderContext（优先于 logicalState 推导）。
+     * 键 = sheetId。
+     */
+    renderContextBySheet?: Record<string, RenderContext> | null;
+    /** 系统参数 branding（实例/测试页由 Shell 传入，避免重复读 localStorage） */
+    systemParamBranding?: SystemParamBranding | null;
+    scripts?: WorkbookScripts | null;
+    namedRanges?: WorkbookNamedRange[] | null;
+    /** 子表统计键 / activeCount；缺省读 wb.meta.fieldRegistry */
+    fieldRegistry?: TemplateFieldRegistry | null;
+    /** 最大迭代轮次；默认 3 */
+    maxIterations?: number;
+    /** incremental=录入后增量计算；full=全量重算/设计态试算（默认） */
+    computePass?: 'incremental' | 'full';
+    /** 系统参数构建器（host 注入）；缺省时 systemParam 绑定格按空参数展开。 */
+    systemParamsProvider?: ComputeSystemParamsProvider;
+    /** 调试钩子（host 注入，kt-web 用 window+flag 守卫）；缺省无操作。 */
+    debug?: (event: string, payload: unknown) => void;
+}
+interface ComputeIssue {
+    kind: 'grid' | 'field' | 'script';
+    sheetId?: string;
+    cellKey?: string;
+    blockKey?: string;
+    message: string;
+}
+interface ComputeResult {
+    wb: TemplateWorkbookState;
+    fieldData: FieldDataCtx;
+    issues: ComputeIssue[];
+    /** 迭代停止时的轮次 */
+    iterations: number;
+}
+declare function computeWorkbook(input: ComputeInput): ComputeResult;
+/**
+ * 增量计算包装（M3.4 实例运行时主入口）。
+ * 实际策略：基于 dirtySeeds 判定是否需要计算。
+ *  - 若 cellMeta 中没有任何 formulaKind 条目，直接返回原工作簿（零开销）。
+ *  - 其余情况执行 `computeWorkbook` 完整求值；因为依赖图在内部构造，
+ *    拓扑遍历仅扫当前公式集合，开销可接受。
+ * 未来可在此基础上做真正的「闭包节点仅重算」优化。
+ */
+interface IncrementalInput extends ComputeInput {
+    /** 刚刚变更的种子格位置（配合依赖闭包用；当前版本内部仅做快检） */
+    dirtySeeds?: Array<{
+        sheetId: string;
+        r: number;
+        c: number;
+    }>;
+}
+declare function computeWorkbookIncremental(input: IncrementalInput): ComputeResult;
+
+/**
+ * @k-table/sheet-core — kt 表格无头引擎（增量迁移中，见蓝图 M2）。
+ *
+ * 迁移序（依赖拓扑）：
+ *  0. 【前置】下沉 sheet 模型类型（SheetTemplateState 等）至共享位置，
+ *     否则 core 的 TemplateWorkbookState 反依赖 components/sheet-template（canvas）。
+ *  1. model / 坐标 coords / 几何 geometry / 布局 layout。
+ *  2. serialize / formula / runtime / compose / instance-data。
+ *  3. migrate（复用现有 migrateWorkbook / legacyWorkbookToTemplateWorkbook）。
+ *  4. 补新能力：多层修约覆盖合并、明细列表行重复渲染。
+ *
+ * 纯度由 eslint-boundaries（M0.4）在迁入时机械强制：禁 react/next/window/document/zustand/echarts/fetch。
+ * 当前阶段：包骨架就位，等待 workspace 装配后逐模块搬迁。
+ */
+declare const SHEET_CORE_PACKAGE: "@k-table/sheet-core";
+
+export { type A1RangeRef, type A1Ref, type A1SingleRef, AggregateEmptyAs, type ApplyHeaderFooterOptions, type AssetEmbedDef, type AssetKind, type AstNode, BUILTIN_PARAM_CATALOG_CODES, type BinOp, type BorderApplySpec, BorderPattern, type BorderPreset, BorderWidth, type BuiltinParamCatalogCode, CHROME_GUTTER_COL_WIDTH_PX, CHROME_GUTTER_ROW_HEIGHT_PX, CSS_PX_PER_INCH, type CellBindingKind, type CellBindingMeta, CellData, type CellFormulaBindingMeta, type CellLayoutHint, type CellRoundingMeta, type ChartDataSource, type ChartEmbedDef, type ComboInstanceDataV3, type ComboSharedContext, type CompileResult, type ComputeFieldLhs, type ComputeInput, type ComputeIssue, type ComputePass, type ComputeResult, type ComputeSystemParamsProvider, DEFAULT_FONT_SIZE_PT, DEFAULT_IMPORT_OPTIONS, DESIGN_FIELD_SHORTHAND_SKILLS, DICT_CATALOG_META_KEY, DICT_OVERLAYS_BY_USER_KEY, DepGraph, type DesignFieldMetaFromShorthand, type DictSnapshotEntry, type DictSnapshotsMap, EXCEL_COL_DIGIT_WIDTH_PX, EXCEL_COL_PADDING_PX, EXCEL_DEFAULT_COL_WIDTH_CHAR, EXCEL_DEFAULT_ROW_HEIGHT_PT, type EmbedAnchorCell, type EmbedAnchorRect, type EmbedBase, type EmbedBoxPt, type EmbedInstanceState, type EmbedPrintContext, type EvalContext, type ExcelImportBorderSide, type ExcelImportCell, type ExcelImportCellStyle, type ExcelImportIntermediateV1, type ExcelImportMerge, type ExcelImportOptions, type ExcelImportRichRun, type ExcelImportStats, FORMULA_RUN_WHEN_LABELS, FUNCTIONS, type FieldDataCtx, type FieldDefRegisterMode, type FieldEvalContext, type FieldInputWhen, type FieldLhs, type FieldPullRuleDef, type FieldRegistryIndex, type FieldRoundingTarget, type FieldRunContextOptions, type FillExtension, type FitGridToPageOptions, type FnImpl, type FormulaAny, type FormulaArray, FormulaCatalogEntry, FormulaCatalogTarget, type FormulaError, type FormulaInputTarget, type FormulaRunWhen, type FormulaStdLibOptions, type FormulaValue, type FormulaValueKind, type GridLayoutMode, type HeaderFooterStrip, type HydrateFieldDataOptions, INSTANCE_DATA_SCHEMA_V2, INSTANCE_DATA_SCHEMA_V3, type IncrementalInput, type InstanceDataRoot, type InstanceDictOverlaysByUser, type InstanceFieldPackV2, type InstanceFieldPackV2Ext, type InstanceSubTablePack, type InstanceSubTablesData, KtTemplateRoot, LEGACY_SYSTEM_PARAM_TEMPLATE_TOKENS, type LayoutFontStyleOpts, type LayoutLinesResult, type LogicalState, MAX_FONT_SIZE_PT, MIN_FONT_SIZE_PT, MIN_SHRINK_FONT_PT, MM_PER_INCH, type MasterCell, MergeIndex, MergeRect, type NodeId, PageSettings, type PaginateReportRowsArgs, type ParsedFieldPath, Parser, type PasteCellPatch, type PrintPageSlot, type PullContext, type PullContextSource, ROUNDING_LAYER_ORDER, ROUNDING_WHEN_LABELS, ROUND_MODE_LETTER_MAP, RUNTIME_COMPUTED_SYSTEM_PARAM_CODES, RUNTIME_ONLY_SYSTEM_PARAM_CODES, type Rect, type RefreshPolicy, type RenderContext, type ReportFieldData, type ReportHeaderFooterStrips, type ReportPaginationResult, type ReportPhysicalPage, type ReportRowSegment, type RescaleOptions, type RescaleSheetResult, type RescaleTargetSize, type RoundingLayer, type RoundingLayerScope, type RoundingOverrideEntry, type RoundingOverrideMap, type RoundingTriggerFlags, type RoundingWhenPreset, type RuntimeOnlySystemParamCode, SHEET_COLOR_ROW_STANDARD, SHEET_COLOR_ROW_THEME, SHEET_CORE_PACKAGE, SHEET_ENGINE_CONFIG, SHEET_FONT_OPTIONS, SUBTABLE_SLOT_BINDING_SKILLS, type SelectionRect, Sheet, type SheetDataRegion, SheetItem, type SignatureSlotState, type SignatureSlotStatus, type SignatureWorkflowReport, type SjsBinOp, SjsCycleError, SjsError, type SjsFn, type SjsNode, type SjsObject, type SjsProgram, type SjsStmt, type SjsValue, type SpliceDiagnostic, type SpliceDiagnosticFix, type SpliceDiagnosticLevel, type SpliceDiagnosticsReport, type SpliceDiagnosticsSignals, type SpliceMisalignSignal, type SpliceUnboundSlotSignal, type SubTableRegionConfig, type SystemParamBranding, type SystemParamId, type SystemParamMap, TEMPLATE_DICT_CATALOG_VERSION, TEMPLATE_WORKBOOK_JSON_VERSION, type TemplateDictCatalog, type TemplateDictDef, type TemplateDictItem, type TemplateDictKind, TemplateFieldDef, TemplateFieldRegistry, type TemplateSheetItem, TemplateSubFieldDef, type TemplateWorkbookState, type TextMeasurer, type Token, type TokenType, type UpsertFieldDefInput, V_NULL, Workbook, type WorkbookEmbedDef, WorkbookMeta, WorkbookNamedRange, type WorkbookPrintPlan, WorkbookScripts, activeSubRowIndices, applyBorderPresetToSheet, applyFieldRoundingForStore, applyNumericRounding, applyReportHeaderFooterTemplate, applyRounding, applyRoundingForInstancePlain, applySignatureResultsToEmbedStates, buildActiveSubRowCounts, buildFieldRunContext, buildFormulaStdLib, buildHeaderFooterTemplateWorkbook, buildPastePatches, buildRoundingLayers, buildSignatureWorkflow, buildSpliceDiagnostics, catalogEntryNodeId, catalogEntryRunWhen, cellKey, cellMetaCompoundKey, clampFontSizePt, clampZoom, cloneFieldRegistry, coerceBool, coerceNum, coerceStr, colIndexToLetters, collectReferencedRoots, columnIndexToLetters, columnLettersToIndex, comboDataFromRoot, compileFormulaAssignment, computeFillPreviewSelection, computeFitScale, computeWorkbook, computeWorkbookIncremental, countActiveSubRows, createDefaultPage, createEmptySheet, createEmptyWorkbook, cssOneCmToCssPx, cssPxToCm, cssPxToFontSizePt, cssPxToPt, defaultPageSettings, describeDictKind, describeRoundingWhenPreset, detectFillExtension, detectGridLayoutMode, emptyFieldPackV2, emptyFieldRegistry, enrichParamsForFieldRuntime, evaluate, excelColWidthToPx, excelRowHeightPtToPx, expandFieldTokens, expandReportSlotPages, expandSystemParamTemplate, extensionStripRect, extractBaseFieldDefsFromWorkbookEnvelope, extractFormulaDeps, extractHeaderFooterStrips, extractRowInputFields, fieldPackFromRoot, fieldPartitionKey, fillSparseDemoCells, fitSheetDataGridToPage, fontSizePtToCssPx, forEachArrayValue, formatA1, formatA1Range, formatA1Single, formatFieldTypeShorthand, formatNumericByMeta, formatSelectionA1, getColWidth, getFieldRegistryFromMeta, getRoundingForCommit, getRoundingForComputeMeta, getRoundingMetaFromCellMetaEntry, getRowHeight, gridColumnIndexToLetters, gridNodeId, guessSheetFontIdFromCssFontFamily, hasEmbedsToPaint, hydrateSheetFieldData, hydrateWorkbookFieldData, indexFieldRegistry, injectBaseFieldRegistryIntoWorkbookEnvelope, isComboInstanceDataV3, isErr, isFieldRegistryRecord, isInstanceFieldPackV2, isKnownSystemParamId, isLegacyInstanceDataV1, isRuntimeComputedSystemParam, isSubColumnPresent, isSubFieldRichPersist, jsPdfFormat, jsPdfOrientation, layoutFontCss, layoutLinesForCellM, lettersToColIndex, lhsToRoundingTarget, listKnownSystemParamIdsForTemplate, listTemplateSystemParamTokenEntries, lockFillAxis, mainFieldNodeId, marginsCmToMm, marginsCmToPt, matrixToTsv, mergeBakedFieldRegistry, mergeBaseFieldPartition, mergeInstanceDataJsonWithLogicalState, mergeInstanceDataJsonWithSubTables, mergeRoundingOverrideLayers, mergeSubFieldCellFromAccValue, mergeSystemAndUserParams, mmToCssPx, nextPendingSignature, normSelectionRect, normalizeFieldDef, normalizeFieldKey, normalizeFieldRegistry, normalizeFormulaRunWhen, normalizePageSettings, normalizeRect, normalizeRoundingTriggers, normalizeSheetToCompactGrid, normalizeSubFieldDef, normalizeSubFieldSlotForFormula, normalizeSystemParamId, pageAtRuleCss, paginateReportRows, paperSizeMm, paperSizeMmFromPage, paperSizeMmRaw, parseA1, parseA1Cell, parseA1OrRangeToSelection, parseA1Ref, parseA1Single, parseCellKey, parseCellMetaCompoundKey, parseFieldPath, parseFieldRegistryFromCapabilities, parseFieldTypeSpec, parseFormula, parseGridRcAddress, parseInstanceDataRoot, parseInstanceSubTables, parseInternalR1C1Ref, parseLogicalState, parseRoundingJson, parseSjsExpr, parseSjsProgram, parseWorkbookJson, physicalPaperSizeMmFromPage, pickLogicalStateFromRoot, presetToTriggers, printableSizeCssPx, printableSizeMm, ptToCssPx, pxToExcelColWidth, pxToExcelRowHeightPt, readSelectionAsTsv, rectContains, rectsOverlap, rescaleReportSheet, rescaleReportWorkbook, resolveBaseFieldDefsFromBaseSource, resolveFieldDefRegisterMode, resolveInputDeps, resolveRoundingForTarget, resolveRoundingFromFieldPath, resolveSheetLogicalPage, resolveSubRowStatKey, roundFinite, roundToInterval, roundToSignificant, roundingForCompute, runSjs, runSjsExpr, runWhenToStorage, scaleWidthsProportional, scriptNodeId, selectionIsUnmergedRectangle, serializeFieldPackV2, serializeWorkbook, setFieldRegistryOnMeta, sheetDataColWidthPx, sheetDataGridHeightPx, sheetDataGridWidthPx, sheetDataRegion, sheetDataRowHeightPx, sheetFontFamilyCss, sheetFontFamilyExcelName, sheetPrintFitScale, shouldComputeFieldByInput, shouldRunFieldFormula, shouldRunScriptBlock, signatureResultsFromEmbedStates, signatureSpecsFromEmbeds, sjsTokenize, sliceRectangles, splitBindingAndTypeSuffix, stripFieldPrefix, stripRuntimeComputedUserParams, subFieldNodeId, subFieldPersistValueFromCell, targetRectFromExtension, targetToOverrideKey, templateContainsSystemParamTokens, toA1, tokenize, triggersToPreset, tryParseNumericString, tsvToMatrix, vBool, vErr, vNum, vStr, wrapTextToWidthM };