@k-table/sheet-canvas 0.0.1 → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1651 @@
+import * as _k_table_sheet_core from '@k-table/sheet-core';
+import { TextMeasurer, EmbedBoxPt, EmbedAnchorRect, WorkbookEmbedDef, ChartEmbedDef, SelectionRect, CellBindingMeta, FieldDataCtx, WorkbookScripts, EmbedInstanceState, GridLayoutMode, TemplateWorkbookState, ExcelImportIntermediateV1, ExcelImportOptions, EmbedPrintContext, AssetEmbedDef } from '@k-table/sheet-core';
+export { FillExtension, computeFillPreviewSelection, detectFillExtension, lockFillAxis } from '@k-table/sheet-core';
+import * as _k_table_sheet_core_sheet_template_model from '@k-table/sheet-core/sheet-template-model';
+import { SheetTemplateState, BaseTemplateCellBinding, TextRun, CellStyle, TextRunStyle, CellData, MergeRange, BorderStyle, BorderLinePattern, TextAlign, PageSettings } from '@k-table/sheet-core/sheet-template-model';
+import * as react from 'react';
+import { RefObject, ReactNode } from 'react';
+import * as exceljs from 'exceljs';
+import { jsPDF } from 'jspdf';
+
+/**
+ * 浏览器 Canvas 2D 文本测量适配器（实现 core 的 TextMeasurer 端口）。
+ * core 的换行/shrink 纯算法通过注入本适配器完成实际像素测量。
+ */
+declare function ctxTextMeasurer(ctx: CanvasRenderingContext2D): TextMeasurer;
+
+/**
+ * 模板引擎外围 UI（工具栏/公式栏/页签/Shadow 内衬等，**不含**画布像素绘制与单元格色值域）。
+ * 随根 ConfigProvider、Showcase 明暗与 token 变化；`fallback` 仅补兼容。
+ * 全站自建布局还可使用 `.kt-page-design-token-root` 上的 `--kt-design-*` 别名（见 `antd-mimic-arco.css`）。
+ */
+declare const sheetChrome: {
+    readonly bg: "var(--ant-color-bg-container, #ffffff)";
+    readonly bgElevated: "var(--ant-color-bg-elevated, #ffffff)";
+    readonly bgLayout: "var(--ant-color-bg-layout, #f5f5f5)";
+    /** 与公式栏、次级条带 */
+    readonly bgSubtle: "var(--ant-color-fill-quaternary, #fafafa)";
+    readonly border: "var(--ant-color-border, #d9d9d9)";
+    readonly text: "var(--ant-color-text, rgba(0,0,0,0.88))";
+    readonly textSecondary: "var(--ant-color-text-secondary, rgba(0,0,0,0.65))";
+    readonly textTertiary: "var(--ant-color-text-tertiary, rgba(0,0,0,0.45))";
+    /** 表格外围滚动区（与画布区相邻的“衬垫”色，非格内白底） */
+    readonly fillScroll: "var(--ant-color-fill-tertiary, #e8e8e8)";
+    /** 浮层阴影，明暗下均可用 */
+    readonly shadowPopover: "0 3px 12px rgba(0,0,0,0.12)";
+};
+
+/**
+ * 画布像素绘制色板。
+ * 默认是纸面 WYSIWYG 浅色；宿主可通过 paint 入参覆盖铬层（标尺 / 选区），
+ * 数据格应保持浅色纸，不跟全站暗色。
+ */
+type SheetPaintPalette = {
+    headerBg: string;
+    headerGrid: string;
+    headerText: string;
+    headerHint: string;
+    headerSelBg: string;
+    dataBg: string;
+    dataGrid: string;
+    lockedBg: string;
+    selFill: string;
+    selStroke: string;
+    activeOutline: string;
+    activeCellBg: string;
+    handleStroke: string;
+    guideStroke: string;
+};
+declare const DEFAULT_SHEET_PAINT_PALETTE: SheetPaintPalette;
+declare function resolveSheetPaintPalette(over?: Partial<SheetPaintPalette>): SheetPaintPalette;
+declare const SHEET_GRID_LINE_HEADER: string;
+declare const SHEET_GRID_LINE_DATA: string;
+declare const SHEET_HEADER_BG: string;
+declare const SHEET_HEADER_SEL_BG: string;
+declare const SHEET_DATA_BG: string;
+/** 实例白名单外锁定格，与拼接虚化带数据区一致 */
+declare const SHEET_INSTANCE_FILL_LOCKED_BG: string;
+declare const SHEET_SEL_FILL: string;
+declare const SHEET_SEL_STROKE: string;
+/** 活动格内圈，与选区外框同系蓝色 */
+declare const SHEET_ACTIVE_OUTLINE: string;
+declare const SHEET_ACTIVE_CELL_BG: string;
+/** 行号/列标选中强调线宽（px），与网格同粗避免双线观感 */
+declare const SHEET_HEADER_SEL_ACCENT_PX = 1;
+
+/**
+ * Shadow DOM 内最小样式，减轻 Tailwind/Antd 对 input/canvas 的影响。
+ * 文本与衬垫色用 token 变量，随主题切换；**画布格线绘制**在 TS 中仍为固定浅色（纸面语义）。
+ * `.sheet-editor` 保持白底/深字，与单元格 WYSIWYG 一致，不随全站暗色改为黑底。
+ */
+declare const SHEET_SHADOW_STYLES: string;
+
+/** 嵌入相对单元格边框的内边距（屏显 px，约 1.5pt） */
+declare const EMBED_CELL_INSET_CSS_PX = 2;
+/** 贴图 box 相对锚点格左上角的默认内边距（pt） */
+declare const EMBED_CELL_INSET_PT = 2;
+type EmbedOverlayBox = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+declare function insetOverlayBox(box: EmbedOverlayBox, insetPx?: number): EmbedOverlayBox;
+/** 锚区矩形 → overlay 像素盒（与 geomSheet / cellToOffset 一致） */
+declare function chartSpanOverlayBox(layoutSheet: SheetTemplateState, origin: {
+    left: number;
+    top: number;
+}, r1: number, c1: number, r2: number, c2: number, viewZoom: number): EmbedOverlayBox;
+/** 单格锚点 + pt box → overlay 像素盒（含内边距） */
+declare function assetBoxOverlayBox(origin: {
+    left: number;
+    top: number;
+}, box: EmbedBoxPt): EmbedOverlayBox;
+/** 打印/栅格：锚区矩形像素尺寸（含内边距） */
+declare function chartSpanPrintRect(sheet: SheetTemplateState, r1: number, c1: number, r2: number, c2: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+declare function assetBoxPrintRect(sheet: SheetTemplateState, r: number, c: number, box: EmbedBoxPt): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+
+type ResolvedEmbedRect = {
+    source: "embedAnchor" | "fallback";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** 扫描 sheet 上 embedAnchor 绑定，收集同一 embedId 的格并集 */
+declare function collectEmbedAnchorRect(sheet: SheetTemplateState, embedId: string, sheetId: string): EmbedAnchorRect | null;
+declare function resolveChartLayoutRect(sheet: SheetTemplateState, chart: ChartEmbedDef): ResolvedEmbedRect | null;
+declare function resolveChartPrintRect(sheet: SheetTemplateState, chart: ChartEmbedDef): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+declare function listEmbedAnchorBindings(sheet: SheetTemplateState, embedId: string): Array<{
+    r: number;
+    c: number;
+    role?: BaseTemplateCellBinding["embedRole"];
+}>;
+declare function embedDisplayLabel(e: WorkbookEmbedDef): string;
+
+/** 嵌入 overlay 布局端口：由宿主（SheetCanvasInner）注入坐标，canvas 组件不依赖 React Context。 */
+type EmbedCellOffset = {
+    left: number;
+    top: number;
+};
+type EmbedOverlayLayoutPort = {
+    /** 锚点格左上相对画布 overlay 层的 CSS 像素坐标（已含 zoom / scroll） */
+    cellToOffset: (r: number, c: number) => EmbedCellOffset | null;
+};
+
+declare function joinRuns(runs: TextRun[]): string;
+declare function mergeRunStyle(a: TextRunStyle | undefined, b: TextRunStyle | undefined): TextRunStyle | undefined;
+/** 合并相邻且样式相同的段 */
+declare function normalizeRuns(runs: TextRun[]): TextRun[];
+/** 将 runs 拆成多行（按 \\n），用于画布逐行绘制 */
+declare function splitRunsIntoLines(runs: TextRun[]): TextRun[][];
+/**
+ * 在已有「按 \\n 拆好的行」基础上，按可视宽度再折行（用于 wrapText）。
+ */
+declare function wrapRunsLinesToMaxWidth(lines: TextRun[][], maxContentWidth: number, measureRunWidth: (run: TextRun) => number): TextRun[][];
+/** 用于 contenteditable 与 Excel HTML 导出 */
+declare function runsToEditableHtml(runs: TextRun[]): string;
+/** 从单元格根节点解析富文本（Excel 常含 sup/sub/b/span；相邻块级子元素之间补换行） */
+declare function runsFromCellContentRoot(root: Element): TextRun[];
+declare function editableHtmlToRuns(html: string): TextRun[];
+declare function hasMeaningfulRuns(runs: TextRun[] | undefined): boolean;
+/** 从 CellData 得到绘制用 runs（含旧版整格上下标；分段与整格默认样式合并） */
+declare function getDisplayRuns(data: CellData | undefined): TextRun[];
+/**
+ * 画布/导出用的整格字号基准（pt），用于 `baseRefPx` 与 `measureRun` 中 `runRefPx * fontPx / baseRefPx`。
+ * 若 `style.fontSize` 未写但合并后的 runs 里已有字号（常见于仅段落样式、仅框线、或历史 JSON），
+ * 仍用默认 10pt 作 base 会把大于默认的字按比例压小。
+ */
+declare function effectiveDefaultFontPtForPaint(cellStyle: CellStyle | undefined, displayRuns: TextRun[]): number;
+declare function cellDataFromEdit(valuePlain: string, runs: TextRun[], baseStyle: CellStyle | undefined): CellData;
+/** 保存时：若 runs 只有分段样式，去掉 style 中整格 script */
+declare function finalizeCellDataForSave(data: CellData): CellData;
+declare function mergeScriptIntoRuns(runs: TextRun[], patch: Partial<Pick<CellStyle, 'superscript' | 'subscript'>>): TextRun[];
+/**
+ * 对 [start,end) 内每个字符合并样式；patch 中值为 `undefined` 表示清除该键（与 CellStyle 约定一致）。
+ * 上/下标互斥：若 patch 将某一侧设为 true，会清除另一侧。
+ */
+declare function applyTextRunStylePatchToSubstring(runs: TextRun[], start: number, end: number, patch: Partial<TextRunStyle>): TextRun[];
+declare function applyScriptToRunSubstring(runs: TextRun[], start: number, end: number, patch: Partial<Pick<CellStyle, 'superscript' | 'subscript'>>): TextRun[];
+declare function normalizeCellDataValue(data: CellData): CellData;
+
+/**
+ * 画布渲染用合并区索引（函数式，MergeRange 版）。
+ * 注意与 @k-table/sheet-core 的 class MergeIndex（MergeRect 版）语义/API 不同，各自服务不同调用方。
+ */
+declare function normalizeMerge(m: MergeRange): MergeRange;
+declare function mergesOverlap(a: MergeRange, b: MergeRange): boolean;
+interface MergeIndex {
+    master: Map<string, {
+        mr: number;
+        mc: number;
+    }>;
+    masterRect: Map<string, MergeRange>;
+}
+declare function buildMergeIndex(merges: MergeRange[] | null | undefined): MergeIndex;
+declare function getMaster(sidx: MergeIndex, r: number, c: number): {
+    mr: number;
+    mc: number;
+};
+/**
+ * 选区（已规范化坐标）与某条合并记录矩形完全一致，用于工具栏在「整框选合并块」时提供「取消合并」。
+ */
+declare function selectionBoundsMatchEntireMerge(merges: MergeRange[] | null | undefined, r1: number, c1: number, r2: number, c2: number): boolean;
+
+declare function setCell(sheet: SheetTemplateState, r: number, c: number, data: CellData): SheetTemplateState;
+declare function expandMergeSelectionRect(merges: MergeRange[], sel: SelectionRect): SelectionRect;
+type ApplyMergeSelectionOptions = {
+    expandOverlapping?: boolean;
+};
+declare function applyMergeSelection(sheet: SheetTemplateState, sel: SelectionRect, options?: ApplyMergeSelectionOptions): SheetTemplateState;
+declare function insertRow(sheet: SheetTemplateState, at: number): SheetTemplateState;
+declare function insertCol(sheet: SheetTemplateState, at: number): SheetTemplateState;
+declare function ensureMinDimensions(sheet: SheetTemplateState, lastRowIndex: number, lastColIndex: number): SheetTemplateState;
+
+type FillPattern = {
+    cells: {
+        value: string;
+        style?: CellStyle;
+        runs?: TextRun[];
+    }[][];
+    /** 相对选区左上角的 0-based 合并矩形（与网格下标一致） */
+    merges: MergeRange[];
+};
+/** 从选区提取填充图案（与复制到剪贴板的网格语义一致） */
+declare function extractFillPattern(sheet: SheetTemplateState, mergeIdx: MergeIndex, sel: SelectionRect): FillPattern | null;
+/** 实例录入填充白名单 Port（kt-web shim 注入 table-system 判定与修约） */
+type InstanceFillGuard = {
+    sheetId: string;
+    sheet: SheetTemplateState;
+    isCellFillable: (mr: number, mc: number, mergeIdx: MergeIndex, sheet: SheetTemplateState) => boolean;
+    roundPlain: (plain: string, mr: number, mc: number) => string;
+};
+type ApplyFillOptions = {
+    /** 强制复制填充，不做序列（对应 Excel Ctrl+拖拽） */
+    forceCopy?: boolean;
+    /** 实例录入：不写合并/样式、不扩表、仅 instanceFillable 主格改纯文本 */
+    instanceFillGuard?: InstanceFillGuard;
+};
+/**
+ * 将选区从 source 扩展到 target 的填充（target 须为 source 的单向延伸矩形）。
+ */
+declare function applyFillToSheet(sheet: SheetTemplateState, sourceSel: SelectionRect, targetSel: SelectionRect, options?: ApplyFillOptions): SheetTemplateState;
+/**
+ * 实例录入：在 computeFillPreviewSelection 基础上收缩延伸步数，使延伸带内凡将被写入的格均在白名单内且不越界。
+ */
+declare function computeFillPreviewSelectionInstance(sheet: SheetTemplateState, sourceSel: SelectionRect, axis: 'row' | 'col', hitR: number, hitC: number, guard: InstanceFillGuard, forceCopy?: boolean): SelectionRect;
+
+/** 应用内粘贴优先读此 MIME，可还原值与样式 */
+declare const SHEET_CLIPBOARD_MIME = "application/x-tuodong-sheet+json";
+type SheetClipboardFragmentV1 = {
+    v: 1;
+    cells: {
+        value: string;
+        style?: CellStyle;
+        runs?: TextRun[];
+    }[][];
+    /** 相对 cells 矩阵左上 (0,0) 的合并区（与选区复制范围一致） */
+    merges?: MergeRange[];
+};
+/**
+ * 稠密网格（0 起坐标）+ 相对 merges → 逻辑行（每行仅主格文本，合并块占一格）。
+ */
+declare function denseGridToLogicalPlainGrid(dense: {
+    value: string;
+    style?: CellStyle;
+    runs?: TextRun[];
+}[][], merges: MergeRange[] | null | undefined): string[][];
+/** 选区 → TSV + HTML 表格 + 应用内 JSON（含样式） */
+declare function selectionToClipboardPayload(sheet: SheetTemplateState, mergeIdx: MergeIndex, sel: SelectionRect): {
+    tsv: string;
+    html: string;
+    appJson: string;
+};
+/**
+ * 通过 Clipboard API 写入选区（右键菜单等无原生 copy 事件时使用）。
+ * 依次尝试：完整 MIME（含应用内 JSON）→ 仅 plain+html → 仅纯文本。
+ */
+declare function writeSheetClipboardPayload(p: {
+    tsv: string;
+    html: string;
+    appJson: string;
+}): Promise<boolean>;
+/**
+ * 将 `clipboard.read()` 得到的条目解析为与原生 `paste` 事件一致的 plain/html/appJson。
+ */
+declare function clipboardItemsToPastePayload(items: ClipboardItem[]): Promise<{
+    plain: string;
+    html: string;
+    appJson: string;
+}>;
+/**
+ * 读取系统剪贴板（右键粘贴等）。优先 `read()` 多 MIME，失败则 `readText`。
+ */
+declare function readClipboardForSheetPaste(): Promise<{
+    plain: string;
+    html: string;
+    appJson: string;
+}>;
+declare function selectionToTsv(sheet: SheetTemplateState, mergeIdx: MergeIndex, sel: SelectionRect): string;
+/** 解析 TSV 为二维数组 */
+declare function parseTsvGrid(tsv: string): string[][];
+/** 从 Excel 等复制的 HTML 表格转为 TSV（text/plain 不可用时兜底） */
+declare function htmlTableToTsv(html: string): string;
+declare function splitTsvLine(line: string): string[];
+/** 将富文本网格写入表（1-based 数据坐标）；不处理 merges，由调用方再 applyMergeSelection。
+ *  粘贴不扩展行列——超出当前网格的部分截断。 */
+declare function applyRichGridToSheet(sheet: SheetTemplateState, startR: number, startC: number, grid: {
+    value: string;
+    style?: CellStyle;
+    runs?: TextRun[];
+}[][]): SheetTemplateState;
+/** 从 HTML 表格解析单元格文本与内联样式（含本应用导出的表格） */
+declare function htmlTableToRichGrid(html: string): {
+    value: string;
+    style?: CellStyle;
+    runs?: TextRun[];
+}[][] | null;
+/**
+ * 解析含 colspan/rowspan 的 HTML 表（如 Excel 剪贴板），返回稠密网格与局部合并区。
+ * 网格坐标为 0 起始，粘贴时平移到 startR/startC。
+ */
+declare function htmlTableToRichGridWithSpans(html: string): {
+    grid: {
+        value: string;
+        style?: CellStyle;
+        runs?: TextRun[];
+    }[][];
+    merges: MergeRange[];
+} | null;
+/**
+ * 粘贴：优先应用内 JSON（值+样式）→ HTML 表格 → 纯文本 TSV
+ */
+declare function pasteClipboardIntoSheet(sheet: SheetTemplateState, startR: number, startC: number, plain: string, html: string, appJson: string): SheetTemplateState;
+declare function pasteTsvAt(sheet: SheetTemplateState, startR: number, startC: number, tsv: string): SheetTemplateState;
+/** 实例录入粘贴白名单 Port（kt-web shim 注入 table-system 判定与修约） */
+type InstancePasteGuard = {
+    isCellFillable: (mr: number, mc: number, mergeIdx: MergeIndex, sheet: SheetTemplateState) => boolean;
+    roundPlain: (plain: string, mr: number, mc: number) => string;
+};
+/**
+ * 实例录入：仅写入纯文本；忽略剪贴板样式；不扩表；跳过非 instanceFillable 格。
+ * 源：JSON/HTML WithSpans 用 merges 压成逻辑列；纯 TSV 每列一项。目标：**一律**按合并主格步进（与 Excel 同时给 plain+html 时仍以 plain 为准解析列，避免丢列）。
+ */
+declare function pasteClipboardInstanceValuesOnly(sheet: SheetTemplateState, startR: number, startC: number, plain: string, html: string, appJson: string, guard: InstancePasteGuard): SheetTemplateState;
+
+/** #rgb / #rrggbb / rgb() / rgba() → #rrggbb */
+declare function normalizeCssColorToHex(input: string): string | undefined;
+/**
+ * 从 CSS 声明串解析为 CellStyle（兼容 Excel / Chrome / Office 剪贴板 HTML）
+ */
+declare function parseSpreadsheetInlineCss(css: string): CellStyle;
+/** 合并单元格样式：后写覆盖先写，override 中为 undefined 的键不覆盖 base */
+declare function mergeCellStylesLoose(base: CellStyle, override: CellStyle): CellStyle;
+/**
+ * 从文档内联 `<style>` 提取 `.类名 { 声明 }`（Excel 剪贴板 HTML 常把对齐/框线写在类里）
+ */
+declare function extractClassStyleMapFromDocument(doc: Document): Map<string, string>;
+type PasteCellStyleOptions = {
+    /** 由 extractClassStyleMapFromDocument 得到，与 td 上 class 对应 */
+    classStyleMap?: Map<string, string>;
+};
+/** Excel 常把对齐写在 align / valign 属性上 */
+declare function applyTdAlignAttrs(el: Element, out: CellStyle): void;
+/**
+ * 从粘贴的 td 解析：单元格框线/底纹/对齐 + 分段上下标等（Excel HTML）。
+ * `runs` 仅在存在分段样式或多段时返回，否则仅用 `style` 表示整格样式。
+ */
+declare function pasteCellStyleAndRuns(td: Element, opts?: PasteCellStyleOptions): {
+    style: CellStyle | undefined;
+    runs: TextRun[] | undefined;
+    plain: string;
+};
+/** 合并 td 上 style + 子元素 b/strong/i/em 的常见粗斜体 */
+declare function cellStyleFromTableCell(el: Element): CellStyle | undefined;
+
+declare function sheetTotalSize(sheet: SheetTemplateState): {
+    width: number;
+    height: number;
+};
+/** 拼接虚化带：scrollY 为整画布滚动；band 内 sheet 的可见行范围（band 顶在世界坐标 yOffset） */
+declare function visibleRowRangeInBand(sheet: SheetTemplateState, scrollY: number, viewportH: number, yOffset: number): {
+    start: number;
+    end: number;
+};
+declare function getCellRect(sheet: SheetTemplateState, r: number, c: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+declare function getMergedPixelRect(sheet: SheetTemplateState, sidx: MergeIndex, r: number, c: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** 选区像素包围盒：遍历格内坐标，按合并主格取像素矩形并做并集，避免合并块与选区蓝框错位 */
+declare function getSelectionPixelBounds(sheet: SheetTemplateState, sidx: MergeIndex, sel: SelectionRect): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** 将画布内坐标（含滚动偏移前为 sheet 坐标）转为行列 */
+declare function hitTestToCell(sheet: SheetTemplateState, sheetX: number, sheetY: number): {
+    r: number;
+    c: number;
+} | null;
+declare function columnDividerAtX(sheet: SheetTemplateState, sheetX: number): number | null;
+declare function rowDividerAtY(sheet: SheetTemplateState, sheetY: number): number | null;
+/** 列宽拖拽：仅当光标落在列标行（索引第 0 行）内时返回列边界索引，避免在数据区竖线拖拽误调列宽 */
+declare function columnDividerAtXInHeaderRow(sheet: SheetTemplateState, sheetX: number, sheetY: number): number | null;
+/** 行高拖拽：仅当光标落在行号列（索引第 0 列）内时返回行边界索引，避免在数据区横线拖拽误调行高 */
+declare function rowDividerAtYInHeaderCol(sheet: SheetTemplateState, sheetX: number, sheetY: number): number | null;
+declare function visibleRowRange(sheet: SheetTemplateState, scrollY: number, viewportH: number): {
+    start: number;
+    end: number;
+};
+declare function visibleColRange(sheet: SheetTemplateState, scrollX: number, viewportW: number): {
+    start: number;
+    end: number;
+};
+declare function isDataCell(r: number, c: number): boolean;
+declare function isHeaderCorner(r: number, c: number): boolean;
+declare function isColumnHeaderRow(r: number, c: number): boolean;
+declare function isRowHeaderCol(r: number, c: number): boolean;
+
+/**
+ * 单像素网格线：每个格子只画「右、下」两边，首行/首列补「顶、左」，
+ * 避免相邻两格各 strokeRect 全框导致公共边被画两次、视觉上变粗。
+ *
+ * 四边统一为单元格矩形 [vx, vy, vx+w, vy+h] 的**内侧网格线**：
+ * 竖线 x = vx−0.5 / vx+w−0.5，横线 y = vy−0.5 / vy+h−0.5（与 Excel 像素对齐习惯一致）。
+ */
+declare function strokeUnmergedCellGrid(ctx: CanvasRenderingContext2D, vx: number, vy: number, w: number, h: number, opts: {
+    drawTop: boolean;
+    drawLeft: boolean;
+}): void;
+/** 合并矩形是否为多格（仅主格键存在矩形且跨越多个格） */
+declare function getMergeRect(sidx: MergeIndex, mr: number, mc: number): MergeRange | undefined;
+/** 行号列标区：右+下+（c===0 时左）+（r===0 时顶），与全角格分离避免叠线 */
+declare function strokeHeaderCellGrid(ctx: CanvasRenderingContext2D, vx: number, vy: number, w: number, h: number, r: number, c: number): void;
+
+declare function borderStrokeWidth(style: BorderStyle | undefined): number;
+/** 与 {@link borderStrokeWidth} 最粗线宽一致；若增粗类型须同步改此值 */
+declare const MAX_BORDER_STROKE_WIDTH_PX = 3;
+/**
+ * 画布 clip 相对视口向外扩的像素：粗线 stroke 以路径为中心外扩约 width/2，须留在裁剪区内；
+ * 与 SheetCanvasInner 中区/虚化带、已用区导出 padding 共用。
+ */
+declare function getGridClipBleedPx(): number;
+type BorderPatternPick = Pick<CellStyle, "borderLinePattern" | "borderTopPattern" | "borderRightPattern" | "borderBottomPattern" | "borderLeftPattern">;
+/** 打印裁剪已用区时传入，与 getUsedDataBounds 一致；最外一圈强制按本格样式画边 */
+type ExportBoundsRowsCols = {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+};
+/**
+ * 在合并/单元格矩形上绘制四边；与相邻格去重，避免两边各画一条导致叠粗。
+ */
+declare function drawCellBorders(ctx: CanvasRenderingContext2D, sheet: SheetTemplateState, mergeIdx: MergeIndex, mr: number, mc: number, vx: number, vy: number, vw: number, vh: number, bt?: BorderStyle, br?: BorderStyle, bb?: BorderStyle, bl?: BorderStyle, borderColor?: string, linePattern?: BorderLinePattern, exportBounds?: ExportBoundsRowsCols, clipOriginSheet?: {
+    x: number;
+    y: number;
+}, patternStyle?: BorderPatternPick, perSideColors?: {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}): void;
+
+/**
+ * 数据区合并主格：背景、富文本、边框（与 SheetCanvasInner 主路径一致，供虚化带等复用）。
+ * 实例填写的「设计占位剥离」由宿主经 resolvePlainText 注入（core 不含 host 绑定语义）。
+ */
+
+declare function paintSheetDataCellContent(ctx: CanvasRenderingContext2D, sheet: SheetTemplateState, mergeIdx: MergeIndex, mr: number, mc: number, bx: number, by: number, baseTemplateUseDisplayText?: boolean, hideBoundMainTextWhenSampleOff?: boolean, highlightUnknownBinding?: boolean, underlayColor?: string, instanceFillPaint?: boolean, instanceFillDisplayPlain?: string, 
+/** 宿主注入：从 CellData 解析实例展示主文（剥离设计占位）；缺省仅取 value。 */
+resolvePlainText?: (cd: CellData | undefined | null) => string): void;
+
+/**
+ * 画左上角公式/脚本占位角标。
+ * @param logicalR/logicalC 与 tableSystem.cellMeta 键一致的工作表行/列
+ * @param cellF 格内 `f` 字段（网格公式如 =A1+B1），回退源
+ */
+declare function paintDesignFormulaOverlayForDataCell(ctx: CanvasRenderingContext2D, bx: number, by: number, boxW: number, boxH: number, metaSheetId: string, logicalR: number, logicalC: number, tableSystemCellMeta: Record<string, unknown> | null, cellF?: string | null): void;
+
+/**
+ * 设计态：格内绑定 code / 备注叠画；限制在单元格矩形内，过长省略号截断。
+ * host 绑定语义（读 cellMeta 绑定、格式化绑定行/角标码）经 deps 注入，core/canvas 不含 host 字段串规则。
+ */
+
+/** 宿主注入：绑定叠画所需的 host 语义。 */
+interface BindingOverlayDeps {
+    getBindingMetaForKey: (meta: Record<string, unknown>, ck: string) => CellBindingMeta | null;
+    formatBindingLine: (b: BaseTemplateCellBinding) => string;
+    formatCodeForOverlayFromMeta: (bm: CellBindingMeta | null) => string;
+}
+declare function paintDesignBindingOverlayForDataCell(ctx: CanvasRenderingContext2D, bx: number, by: number, boxW: number, boxH: number, metaSheetId: string, logicalR: number, logicalC: number, tableSystemCellMeta: Record<string, unknown> | null, cellBinding?: BaseTemplateCellBinding | null, textAlign?: TextAlign, mainLayerUsesBindingDisplayText?: boolean, unknownBinding?: boolean, 
+/** 宿主注入的 host 绑定语义；缺省则仅用 cellBinding.key 兜底。 */
+deps?: BindingOverlayDeps): void;
+
+/**
+ * 拼接虚化带：仅用于顶/底预览绘制（不参与编辑逻辑），样式与主画布数据区一致。
+ */
+
+type PaintVirtualBandBindingOverlay = {
+    /** 基础表首张 sheetId，与 base `tableSystem.cellMeta` 键一致 */
+    baseSheetId: string;
+    /** 与 `sliceWorkbookV3RowRange` 一致：数据区首行对应基础表行号 */
+    sourceRowStartInclusive: number;
+    tableSystemCellMeta: Record<string, unknown> | null;
+    /** 宿主注入的绑定叠画 host 语义（缺省则仅用 cellBinding.key 兜底） */
+    deps?: BindingOverlayDeps;
+};
+type PaintVirtualBandOptions = {
+    scrollBandWorldY0: number;
+    designBindingOverlay?: boolean;
+    baseTemplateUseDisplayText?: boolean;
+    hideBoundMainTextWhenSampleOff?: boolean;
+    bindingOverlay?: PaintVirtualBandBindingOverlay | null;
+};
+declare function paintVirtualSheetBand(ctx: CanvasRenderingContext2D, sheet: SheetTemplateState, sx: number, sy: number, vw: number, vh: number, opts: PaintVirtualBandOptions): void;
+declare function virtualBandWorldHeight(sheet: SheetTemplateState | null | undefined): number;
+
+/** 是否视为「占用打印区域」：有文本，或有背景/框线，或显式格式。 */
+declare function isCellUsedForPrintBounds(data: CellData | undefined): boolean;
+/**
+ * 数据区 (r,c>=1) 中包含占用格的最小矩形（按合并块整体计入）。全表无占用返回 null。
+ */
+declare function getUsedDataBounds(sheet: SheetTemplateState, mergeIdx: MergeIndex): {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+} | null;
+/** 已用区在表坐标中的像素包围盒；无占用时返回单格 (1,1) 的矩形 */
+declare function getUsedExportPixelRect(sheet: SheetTemplateState, bounds: {
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+type SheetExportSizeOptions = {
+    includeHeaders: boolean;
+    /** 仅包含有内容或框线等占用格的最小矩形（打印预览用） */
+    clipToUsedRange?: boolean;
+    mergeIdx?: MergeIndex;
+};
+type SheetExportOptions = {
+    /** 含行号列标；false 时仅数据区 */
+    includeHeaders: boolean;
+    /**
+     * 是否绘制默认淡色网格线。打印预览为 false，仅保留单元格样式里的框线。
+     * 默认 true（与编辑器一致的完整网格）。
+     */
+    drawDefaultGrid?: boolean;
+    /**
+     * 已用区裁剪导出时传入（与 getUsedDataBounds 一致），框线在最外一圈按本格绘制，避免邻格去重缺失边线。
+     */
+    exportBounds?: ExportBoundsRowsCols;
+    /** 与 translate 偏移一致，供顶/左边对齐到可画区像素 */
+    clipOriginSheet?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * true：不绘制单元格 style.bgColor（打印/PDF 去底色；数据区仍为白底）。
+     * 默认 false，与编辑/屏幕导出一致。
+     */
+    omitCellBackground?: boolean;
+};
+declare function getSheetExportSize(sheet: SheetTemplateState, opts: SheetExportSizeOptions): {
+    width: number;
+    height: number;
+};
+/**
+ * 在已设置尺寸的逻辑坐标系中绘制（1 单元格 = 1 像素与编辑器一致）。
+ * 若 `includeHeaders === false`，请先 `ctx.translate(-getCellRect(sheet,1,1).x, -getCellRect(sheet,1,1).y)`。
+ */
+declare function renderSheetExport(ctx: CanvasRenderingContext2D, sheet: SheetTemplateState, mergeIdx: MergeIndex, options: SheetExportOptions): void;
+type RasterizeSheetExportOptions = SheetExportOptions & {
+    /** 设备像素比，打印建议 2 */
+    deviceScale?: number;
+    /**
+     * true：画布仅为「有内容/框线等」占用格的最小包围盒（不含行列索引区）。
+     * 打印预览默认应开启。
+     */
+    clipToUsedRange?: boolean;
+};
+/** 打印/导出 PDF 的默认：无索引、无默认网格线、裁剪已用区域 */
+declare const PRINT_EXPORT_PRESET: Pick<RasterizeSheetExportOptions, 'includeHeaders' | 'drawDefaultGrid' | 'clipToUsedRange'>;
+/** 离屏 Canvas，逻辑尺寸见 logicalWidth/Height（css 像素） */
+declare function rasterizeSheetExportToCanvas(sheet: SheetTemplateState, mergeIdx: MergeIndex, options: RasterizeSheetExportOptions): {
+    canvas: HTMLCanvasElement;
+    logicalWidth: number;
+    logicalHeight: number;
+    deviceScale: number;
+};
+/**
+ * 导出整张表为 PNG DataURL（逻辑坐标 × deviceScale）。
+ */
+declare function rasterizeSheetExport(sheet: SheetTemplateState, mergeIdx: MergeIndex, options: RasterizeSheetExportOptions): {
+    dataUrl: string;
+    width: number;
+    height: number;
+    logicalWidth: number;
+    logicalHeight: number;
+};
+/** 从整表 canvas 按逻辑像素矩形切片（用于多页实际大小） */
+declare function sliceExportCanvasToDataUrls(source: HTMLCanvasElement, logicalRects: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}[], deviceScale: number): string[];
+
+type SheetScrollPort = {
+    isUnified: boolean;
+    /** 命中/坐标换算用的内层 `.sheet-scroll` */
+    hitEl: HTMLDivElement | null;
+    getScrollXY(zoom: number): {
+        sx: number;
+        sy: number;
+    };
+    getScrollLeftTop(): {
+        sl: number;
+        st: number;
+    };
+    setScrollLeftTop(sl: number, st: number): void;
+    getViewport(): {
+        vw: number;
+        vh: number;
+        scrollWidth: number;
+        scrollHeight: number;
+    };
+};
+declare function createSheetScrollPort(input: {
+    scrollRef: RefObject<HTMLDivElement | null>;
+    wrapRef: RefObject<HTMLElement | null>;
+    unifiedScroll: boolean;
+    unifiedScrollRef: RefObject<HTMLDivElement | null> | null;
+}): SheetScrollPort;
+
+/**
+ * 单元格 contenteditable 内「纯文本」偏移与 DOM Range 边界互转。
+ * 须与 cellRichText editableHtmlToRuns / joinRuns 的拼接长度一致。
+ */
+declare function getSelectionForEditableRoot(root: HTMLElement): Selection | null;
+declare function plainLengthToBoundary(root: HTMLElement, container: Node, offset: number): number;
+declare function getPlainOffsetsFromSelection(root: HTMLElement): {
+    start: number;
+    end: number;
+} | null;
+declare function boundaryAtPlainIndex(root: HTMLElement, index: number): {
+    node: Node;
+    offset: number;
+};
+declare function setPlainTextSelection(root: HTMLElement, start: number, end: number): void;
+
+/** 填充柄热点尺寸（px） */
+declare const FILL_HANDLE_PX = 6;
+/** 选区矩形是否恰好覆盖某一合并主格整块（含未合并单格） */
+declare function selectionMatchesMergeMaster(mergeIdx: MergeIndex, selection: SelectionRect, mr: number, mc: number): boolean;
+/** 正在编辑且选区覆盖整块合并主格时，不显示/不响应填充柄 */
+declare function fillHandleBlockedByEdit(editing: {
+    r: number;
+    c: number;
+} | null, mergeIdx: MergeIndex, activeCell: {
+    r: number;
+    c: number;
+}, selection: SelectionRect): boolean;
+/** 命中测试：sheet 坐标是否落在选区右下角填充柄热区 */
+declare function hitTestFillHandle(sheet: SheetTemplateState, mergeIdx: MergeIndex, selection: SelectionRect, sheetX: number, sheetY: number, handlePx?: number, pad?: number): boolean;
+
+type SelectionHeaderHighlight = {
+    selR1: number;
+    selR2: number;
+    selC1: number;
+    selC2: number;
+    isFullRowSelection: boolean;
+    isFullColumnSelection: boolean;
+    highlightColumnHeaders: boolean;
+    highlightRowHeaders: boolean;
+};
+/** 选区铺满整行/整列时，行号列标高亮策略（与 Excel 一致） */
+declare function selectionHeaderHighlightFlags(sel: SelectionRect, maxDataR: number, maxDataC: number): SelectionHeaderHighlight;
+type SelectionEditChromeFlags = {
+    hideSelStrokeForEdit: boolean;
+    hideActiveStrokeForEdit: boolean;
+    hideFillHandleForEdit: boolean;
+};
+/**
+ * 内联编辑与活动格重合时的选区/活动格外框与填充柄隐藏策略。
+ * selPx / activeBox 须为已减 scroll 的视口坐标（与 paint 内 rx/ax 同系）。
+ */
+declare function selectionEditChromeFlags(editing: {
+    r: number;
+    c: number;
+} | null, activeR: number, activeC: number, selPx: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, activeBox: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): SelectionEditChromeFlags;
+type InstanceSelectionChromeState = {
+    instanceLockedFullMergeSelection: boolean;
+    instanceEmptyLockedHideChrome: boolean;
+    activeLockedInInstance: boolean;
+};
+/** 实例白名单模式下选区/活动格 chrome 底色与描边策略 */
+declare function instanceSelectionChromeState(input: {
+    instanceFillWhitelist: boolean;
+    metaSheetId: string;
+    sheet: _k_table_sheet_core_sheet_template_model.SheetTemplateState;
+    mergeIdx: MergeIndex;
+    selection: SelectionRect;
+    selMr: number;
+    selMc: number;
+    selAnchoredInData: boolean;
+    activeMr: number;
+    activeMc: number;
+    selectionMatchesMergeMaster: (mergeIdx: MergeIndex, sel: SelectionRect, mr: number, mc: number) => boolean;
+    isInstanceCellFillable: (mr: number, mc: number) => boolean;
+    isDataCellTextuallyEmpty: (sheet: _k_table_sheet_core_sheet_template_model.SheetTemplateState, mr: number, mc: number) => boolean;
+}): InstanceSelectionChromeState;
+
+/** 画布视图缩放钳制（与 SheetCanvasInner / sheetScrollPort 一致） */
+declare function clampSheetViewZoom(zoom: number): number;
+
+/** 把选区两角限制在数据区内并规范为矩形（勿用 min(r1,r2,max) 同时赋给 r1/r2） */
+declare function clampSelection(rowCount: number, colCount: number, r1: number, c1: number, r2: number, c2: number): SelectionRect;
+/** 整行/整列选区时矩形极大，滚入视口会把条拖到底/最右；保持当前滚动位置 */
+declare function shouldSkipScrollRevealForSelection(selection: SelectionRect, maxDataR: number, maxDataC: number): boolean;
+
+/** 客户端坐标 → 表世界坐标（含拼接顶区偏移的 sheetYFull） */
+declare function clientToSheetCoords(input: {
+    clientX: number;
+    clientY: number;
+    scrollBoundingRect: {
+        left: number;
+        top: number;
+    };
+    scrollSx: number;
+    scrollSy: number;
+    viewZoom: number;
+    midBandTopH: number;
+}): {
+    sheetX: number;
+    sheetY: number;
+    sheetYFull: number;
+};
+
+type ScrollRevealInput = {
+    selectionPixelRect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    viewZoom: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    scrollLeft: number;
+    scrollTop: number;
+    scrollWidth: number;
+    scrollHeight: number;
+    midBandTopH: number;
+    /** 拼接统一滚动时外层块 offsetTop * zoom */
+    unifiedScrollBlockTop?: number;
+    pad?: number;
+};
+/** 选区/活动格变化时计算应滚动到的 left/top（像素，已 floor） */
+declare function computeScrollToRevealSelection(input: ScrollRevealInput): {
+    scrollLeft: number;
+    scrollTop: number;
+    changed: boolean;
+};
+
+/** 数据区主格：无可见文本/公式（实例白名单下用于「空锁定格」不显示选中外框） */
+declare function isDataCellTextuallyEmpty(sheet: SheetTemplateState, mr: number, mc: number): boolean;
+
+type SheetCanvasViewport = {
+    viewZoom: number;
+    cssWidth: number;
+    cssHeight: number;
+    worldWidth: number;
+    worldHeight: number;
+    devicePixelRatio: number;
+};
+/** 配置 canvas 元素尺寸与 2D 变换，返回视口世界坐标尺寸 */
+declare function setupSheetCanvasElement(input: {
+    canvas: HTMLCanvasElement;
+    viewZoom: number;
+    unifiedScroll: boolean;
+    totalWidth: number;
+    totalHeight: number;
+    wrapClientWidth: number;
+    wrapClientHeight: number;
+    devicePixelRatio?: number;
+}): SheetCanvasViewport;
+
+/**
+ * SheetCanvasInner 绘制帧的宿主注入端口（实例白名单 / 设计态绑定 / dict 展示等）。
+ * kt-web shim 组装真实实现；canvas 包内不含 zustand/table-system/antd 依赖。
+ */
+type SheetCanvasPaintPort = {
+    /** 实例白名单：格是否可填（锁定格灰底、不叠选区色） */
+    isInstanceCellFillable: (mr: number, mc: number) => boolean;
+    /** 设计态：绑定字段是否未知（红色高亮） */
+    isUnknownBindingForCell?: (cell: CellData | undefined) => boolean;
+    /** 实例格 dict 格式化展示文案 */
+    getInstanceFillDisplayPlain?: (mr: number, mc: number) => string | undefined;
+    /** 实例明文解析（剥离设计占位） */
+    resolveInstancePlainText?: (data: CellData | null | undefined) => string;
+    /** 设计态只读样式灰底 */
+    getDesignReadonlyUnderlay?: (mr: number, mc: number) => string | undefined;
+};
+/** 无实例/设计宿主语义时的默认端口（全部格可填、无绑定高亮） */
+declare const DEFAULT_SHEET_CANVAS_PAINT_PORT: SheetCanvasPaintPort;
+
+type PrintLayoutMode = 'fitOnePage' | 'actualSize';
+type BuildPrintDocumentOptions = {
+    sheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    page: PageSettings;
+    layoutMode: PrintLayoutMode;
+    deviceScale?: number;
+    /** 为 true 时在 body 加灰底，仅屏幕预览用 */
+    screenPreviewChrome?: boolean;
+    omitCellBackground?: boolean;
+    sliceSheetFactory?: (sliceIndex: number, sliceCount: number) => SheetTemplateState;
+};
+type BuildPrintWorkbookItem = {
+    sheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    page: PageSettings;
+    sliceSheetFactory?: (sliceIndex: number, sliceCount: number) => SheetTemplateState;
+};
+type BuildPrintWorkbookDocumentOptions = {
+    items: BuildPrintWorkbookItem[];
+    layoutMode: PrintLayoutMode;
+    deviceScale?: number;
+    screenPreviewChrome?: boolean;
+    omitCellBackground?: boolean;
+};
+/** 判断多表是否共用同一 `@page`（纸张+边距）；不一致时浏览器单次打印不可靠，应导出 PDF 或按 Tab 分表打印。 */
+declare function pageSettingsPrintKey(p: PageSettings): string;
+/**
+ * 生成可打印的完整 HTML（含 @page）。与 Canvas 导出同源。
+ */
+declare function buildPrintDocument(opts: BuildPrintDocumentOptions): {
+    html: string;
+    pageCount: number;
+};
+/**
+ * 多工作表单一 HTML：仅当各表 `page` 一致时合法（同一 `@page`）。
+ */
+declare function buildPrintWorkbookDocument(opts: BuildPrintWorkbookDocumentOptions): {
+    html: string;
+    pageCount: number;
+    uniformPage: boolean;
+};
+
+/** SheetCanvasInner 窗口级拖拽状态（pointer 捕获在 window） */
+type SheetDragState = {
+    mode: "select";
+    anchor: {
+        r: number;
+        c: number;
+    };
+    extend: boolean;
+} | {
+    mode: "selectColHeader";
+    anchorC: number;
+} | {
+    mode: "selectRowHeader";
+    anchorR: number;
+} | {
+    mode: "col";
+    col: number;
+    startW: number;
+    startX: number;
+} | {
+    mode: "row";
+    row: number;
+    startH: number;
+    startY: number;
+} | {
+    mode: "fill";
+    sourceSel: SelectionRect;
+    axis: "row" | "col" | null;
+    startSheetX: number;
+    startSheetY: number;
+    forceCopy: boolean;
+};
+type SheetDragGuide = {
+    kind: "col";
+    lineX: number;
+} | {
+    kind: "row";
+    lineY: number;
+};
+
+/**
+ * SheetCanvasInner 主绘制帧（纯 Canvas 2D，无 React）。
+ * 宿主经 SheetCanvasPaintPort 注入实例白名单 / 设计态绑定 / dict 展示语义。
+ */
+
+type PaintSheetCanvasFrameInput = {
+    ctx: CanvasRenderingContext2D;
+    viewport: SheetCanvasViewport;
+    scrollSx: number;
+    scrollSy: number;
+    sheet: SheetTemplateState;
+    geomSheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+    editing: {
+        r: number;
+        c: number;
+    } | null;
+    showCellGridLines: boolean;
+    instanceFillWhitelist: boolean;
+    metaSheetId: string;
+    designBindingOverlay: boolean;
+    designReadonlyStyle: boolean;
+    useBindingDisplayText: boolean;
+    hideBoundMainTextWhenSampleOff: boolean;
+    showPrintPageBreaks: boolean;
+    showPrintableAreaOutline: boolean;
+    printableAreaHeightExtraDeductionPx: number;
+    printBreakLayoutMode: PrintLayoutMode;
+    virtualTopSheet: SheetTemplateState | null;
+    virtualBottomSheet: SheetTemplateState | null;
+    spliceVirtualTopBinding: PaintVirtualBandBindingOverlay | null;
+    spliceVirtualBottomBinding: PaintVirtualBandBindingOverlay | null;
+    headerDragGuide: SheetDragGuide | null;
+    resizeGuide: SheetDragGuide | null;
+    fillDragPreview: SelectionRect | null;
+    port: SheetCanvasPaintPort;
+    tableSystemCellMeta: Record<string, unknown> | null;
+    /** 标尺 / 选区覆盖；不传则用默认浅色纸色板 */
+    palette?: Partial<SheetPaintPalette>;
+};
+declare function paintSheetCanvasFrame(input: PaintSheetCanvasFrameInput): void;
+
+/** 指针落在拼接虚化顶区（不参与中区编辑） */
+declare function isPointerInVirtualTopBand(sheetYFull: number, midBandTopH: number): boolean;
+/** 指针落在拼接虚化底区 */
+declare function isPointerInVirtualBottomBand(sheetYFull: number, midBandTopH: number, midBandHeight: number): boolean;
+/** 顶/底虚化带激活时，中区外的 pointer 应忽略（选区/填充/改尺寸） */
+declare function shouldIgnorePointerOutsideMidBand(input: {
+    sheetYFull: number;
+    midBandTopH: number;
+    midBandHeight: number;
+    virtualTopActive: boolean;
+    virtualBottomActive: boolean;
+}): boolean;
+
+/**
+ * 填充柄拖拽：根据位移与命中格相对源选区位置锁定 row/col 轴。
+ * 与 SheetCanvasInner 原逻辑一致（轻微水平抖动不误锁 col）。
+ */
+declare function resolveFillDragAxis(input: {
+    ddr: number;
+    ddc: number;
+    hitR: number;
+    hitC: number;
+    sourceSel: SelectionRect;
+}): "row" | "col" | null;
+
+/** 框选拖拽：列标/行号扩选时把命中格规范到数据区对角 */
+declare function normalizeSelectDragHit(hit: {
+    r: number;
+    c: number;
+}, rowCount: number, colCount: number): {
+    r: number;
+    c: number;
+} | null;
+/** 列标拖选：命中列索引钳制到数据列 */
+declare function clampColumnHeaderDragEnd(hitC: number, maxC: number): number | null;
+/** 行号拖选：命中行索引钳制到数据行 */
+declare function clampRowHeaderDragEnd(hitR: number, maxR: number): number | null;
+/** 列宽/行高拖拽后的新尺寸（世界 px，已钳制最小值） */
+declare function computeResizedColWidth(startW: number, dxScreen: number, viewZoom: number): number;
+declare function computeResizedRowHeight(row: number, startH: number, dyScreen: number, viewZoom: number): number;
+
+type SheetPointerCursorInput = {
+    drag: SheetDragState | null;
+    sheetX: number;
+    sheetY: number;
+    sheetYFull: number;
+    geomSheet: SheetTemplateState;
+    midBandTopH: number;
+    virtualTopActive: boolean;
+    virtualBottomActive: boolean;
+    readOnly: boolean;
+    formatPainterArmed: boolean;
+    selection: SelectionRect;
+    mergeIdx: MergeIndex;
+    editing: {
+        r: number;
+        c: number;
+    } | null;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+};
+/** 表头/数据区 pointer 悬停时应显示的 CSS cursor（空串表示 default） */
+declare function resolveSheetPointerCursor(input: SheetPointerCursorInput): string;
+
+type SheetDragMoveInput = {
+    drag: SheetDragState;
+    clientX: number;
+    clientY: number;
+    sheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    viewZoom: number;
+    scrollSx: number;
+    scrollSy: number;
+    midBandTopH: number;
+    virtualTopActive: boolean;
+    virtualBottomActive: boolean;
+    clientToSheet: (clientX: number, clientY: number) => {
+        sheetX: number;
+        sheetY: number;
+        sheetYFull: number;
+    };
+    /** 宿主注入：实例白名单填充预览（缺省用 core computeFillPreviewSelection） */
+    computeFillPreview?: (sourceSel: SelectionRect, axis: "row" | "col", hitR: number, hitC: number) => SelectionRect;
+    /** 宿主注入：拖选合并扩展 */
+    expandMergeSelection: (merges: SheetTemplateState["merges"], raw: SelectionRect) => SelectionRect;
+    setColWidth: (sheet: SheetTemplateState, col: number, width: number) => SheetTemplateState;
+    setRowHeight: (sheet: SheetTemplateState, row: number, height: number) => SheetTemplateState;
+};
+type SheetDragMoveOutcome = {
+    sheet?: SheetTemplateState;
+    selection?: SelectionRect;
+    resizeGuide?: SheetDragGuide | null;
+    headerGuide?: SheetDragGuide | null;
+    fillPreview?: SelectionRect | null;
+    /** 填充柄首次锁轴后写回 drag */
+    fillAxis?: "row" | "col";
+    paint: boolean;
+};
+declare function processSheetDragMove(input: SheetDragMoveInput): SheetDragMoveOutcome | null;
+
+type SheetDragEndInput = {
+    drag: SheetDragState | null;
+    fillPreview: SelectionRect | null;
+    sheet: SheetTemplateState;
+    selection: SelectionRect;
+    formatPainterArmed: boolean;
+    applyFillToSheet: (sheet: SheetTemplateState, sourceSel: SelectionRect, targetSel: SelectionRect, opts: {
+        forceCopy: boolean;
+    }) => SheetTemplateState;
+};
+type SheetDragEndOutcome = {
+    sheet?: SheetTemplateState;
+    selection?: SelectionRect;
+    activeCell?: {
+        r: number;
+        c: number;
+    };
+    applyFormatPainter?: boolean;
+    clearGuides: boolean;
+    paint: boolean;
+};
+declare function processSheetDragEnd(input: SheetDragEndInput): SheetDragEndOutcome;
+
+type SheetWindowDragListeners = {
+    move: (e: Event) => void;
+    up: () => void;
+    moveEvent: "pointermove" | "mousemove";
+};
+declare function preferredWindowDragMoveEvent(): "pointermove" | "mousemove";
+/** 在 window 捕获阶段挂载拖拽监听（拖出画布仍能收到 move/up） */
+declare function attachSheetWindowDragListeners(prev: SheetWindowDragListeners | null, next: SheetWindowDragListeners): void;
+declare function detachSheetWindowDragListeners(L: SheetWindowDragListeners): void;
+declare function createSheetWindowDragHandlers(onMove: (e: Event) => void, onUp: () => void): SheetWindowDragListeners;
+
+/** 单点正在编辑的同一格时保留内联编辑层焦点 */
+declare function shouldKeepInlineEditFocus(input: {
+    editing: {
+        r: number;
+        c: number;
+    } | null;
+    geomSheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    sheetX: number;
+    sheetY: number;
+}): boolean;
+/** 列宽拖拽分隔线：可拖则返回列索引，否则 null */
+declare function resolveColResizeDivider(geomSheet: SheetTemplateState, sheetX: number, sheetY: number, colCount: number, columnLayoutLocked: boolean): number | null;
+/** 行高拖拽分隔线 */
+declare function resolveRowResizeDivider(geomSheet: SheetTemplateState, sheetX: number, sheetY: number, rowCount: number, rowLayoutLocked: boolean): number | null;
+declare function isFillHandlePointerDown(input: {
+    readOnly: boolean;
+    geomSheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+    editing: {
+        r: number;
+        c: number;
+    } | null;
+    sheetX: number;
+    sheetY: number;
+}): boolean;
+declare function buildFillDragState(selection: SelectionRect, sheet: SheetTemplateState, sheetX: number, sheetY: number, forceCopy: boolean): SheetDragState;
+/** 公式拾取：字段模式优先绑定行，否则 A1 */
+declare function resolveFormulaPickerRefText(input: {
+    kind: "field" | "grid";
+    mr: number;
+    mc: number;
+    bindingLine?: string;
+}): string;
+declare function computeSelectAllCornerSelection(rowCount: number, colCount: number): {
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+};
+declare function computeColumnHeaderPointerSelection(input: {
+    hitC: number;
+    shiftKey: boolean;
+    activeCol: number;
+    rowCount: number;
+    colCount: number;
+}): {
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+};
+declare function computeRowHeaderPointerSelection(input: {
+    hitR: number;
+    shiftKey: boolean;
+    activeRow: number;
+    rowCount: number;
+    colCount: number;
+}): {
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+};
+declare function computeDataCellPointerSelection(input: {
+    mr: number;
+    mc: number;
+    hitR: number;
+    hitC: number;
+    shiftKey: boolean;
+    activeR: number;
+    activeC: number;
+    rowCount: number;
+    colCount: number;
+    mergeIdx: MergeIndex;
+    merges: SheetTemplateState["merges"];
+    expandMergeSelection: (merges: SheetTemplateState["merges"], raw: SelectionRect) => SelectionRect;
+}): {
+    selection: SelectionRect;
+    activeCell?: {
+        r: number;
+        c: number;
+    };
+    selectDrag: SheetDragState;
+};
+/** 右键菜单：表头命中时映射到活动格行/列 */
+declare function resolveContextMenuCell(input: {
+    hitR: number;
+    hitC: number;
+    activeR: number;
+    activeC: number;
+}): {
+    row: number;
+    col: number;
+};
+type SheetPointerDownInput = {
+    pointerType: string;
+    button: number;
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    clientX: number;
+    sheetX: number;
+    sheetY: number;
+    sheetYFull: number;
+    readOnly: boolean;
+    columnLayoutLocked: boolean;
+    rowLayoutLocked: boolean;
+    instanceFillWhitelist: boolean;
+    geomSheet: SheetTemplateState;
+    sheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+    editing: {
+        r: number;
+        c: number;
+    } | null;
+    midBandTopH: number;
+    virtualTopActive: boolean;
+    virtualBottomActive: boolean;
+    formulaPickerArmed: boolean;
+    formulaPickerKind: "field" | "grid";
+    bindingLineForPicker?: string;
+    expandMergeSelection: (merges: SheetTemplateState["merges"], raw: SelectionRect) => SelectionRect;
+    /** 实例格是否可填（辅助录入触发判定） */
+    isCellFillable?: (mr: number, mc: number) => boolean;
+    instanceFillInputMode?: "native" | "assistedTouch" | "assistedPointer" | string;
+};
+type SheetPointerDownResult = {
+    action: "ignore";
+} | {
+    action: "formula";
+    refText: string;
+} | {
+    action: "focus";
+    keepInlineFocus: boolean;
+} | {
+    action: "resizeCol";
+    col: number;
+} | {
+    action: "resizeRow";
+    row: number;
+} | {
+    action: "fill";
+    drag: SheetDragState;
+} | {
+    action: "noHit";
+} | {
+    action: "corner";
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+} | {
+    action: "colHeader";
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+    startColHeaderDrag: boolean;
+} | {
+    action: "rowHeader";
+    selection: SelectionRect;
+    activeCell: {
+        r: number;
+        c: number;
+    };
+    startRowHeaderDrag: boolean;
+} | {
+    action: "dataCell";
+    mr: number;
+    mc: number;
+    selection: SelectionRect;
+    activeCell?: {
+        r: number;
+        c: number;
+    };
+    startSelectDrag: boolean;
+    endEditIfOtherCell: boolean;
+    openAssistedTouch?: boolean;
+    openAssistedPointer?: boolean;
+};
+declare function processSheetPointerDown(input: SheetPointerDownInput): SheetPointerDownResult;
+
+/** 宿主注入：图片/图表/二维码栅格化依赖（避免 canvas 包直接耦合文件 API 与 echarts） */
+type PaintEmbedsDeps = {
+    resolveEmbedImageSrc: (fileId: string | undefined) => Promise<string | null>;
+    rasterizeChartEmbedToDataUrl: (def: ChartEmbedDef, fieldData: FieldDataCtx, widthPx: number, heightPx: number, runtime?: unknown, scripts?: WorkbookScripts | null) => Promise<string | null>;
+    qrToDataUrl: (payload: string, opts: {
+        errorCorrectionLevel?: "L" | "M" | "Q" | "H";
+        margin: number;
+        width: number;
+    }) => Promise<string>;
+};
+type PaintEmbedsOptions = PaintEmbedsDeps & {
+    sheetId: string;
+    embeds: WorkbookEmbedDef[];
+    embedStates?: Record<string, EmbedInstanceState>;
+    qrPayloadBySlot?: Record<string, string>;
+    /** 图表 live 渲染数据源（打印不走 UI cache） */
+    fieldData?: FieldDataCtx;
+    scripts?: WorkbookScripts | null;
+    /** 与 rasterize 相同的 translate 偏移 */
+    offsetX?: number;
+    offsetY?: number;
+};
+/** 在已绘制的 sheet canvas 上叠画 embed（asset + chart） */
+declare function paintEmbedsToCanvas(ctx: CanvasRenderingContext2D, sheet: SheetTemplateState, _mergeIdx: MergeIndex, opts: PaintEmbedsOptions): Promise<void>;
+
+/**
+ * 在表像素坐标系中返回「每页」矩形（与打印切片逻辑一致），供编辑画布叠画分页虚线。
+ * - 整表一页：已用区外包络一块
+ * - 实际大小：按可印区逻辑像素切片多块
+ */
+declare function getPrintPageOverlayRects(sheet: SheetTemplateState, mergeIdx: MergeIndex, page: PageSettings, layoutMode: PrintLayoutMode): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}[];
+
+/** 将单 Sheet 状态写入 ExcelJS Worksheet */
+declare function writeSheetToWorksheet(ws: exceljs.Worksheet, sheet: SheetTemplateState): Promise<void>;
+/** 将表模板导出为 Excel（.xlsx），含合并、框线、字体、对齐、填充、行列尺寸（近似）。 */
+declare function sheetToExcelBuffer(sheet: SheetTemplateState): Promise<ArrayBuffer>;
+/** 多 Sheet 工作簿 → 单个 xlsx（每 sheet 一页，名称取自 TemplateSheetItem.name） */
+declare function workbookToExcelBuffer(workbook: _k_table_sheet_core.TemplateWorkbookState): Promise<ArrayBuffer>;
+declare function downloadExcelFile(filename: string, buffer: ArrayBuffer): void;
+declare function downloadSheetAsExcel(sheet: SheetTemplateState, baseName?: string): Promise<void>;
+
+/**
+ * 多 Sheet 工作簿 Excel 往返（布局层；不含 fieldRegistry / binding 语义）。
+ */
+
+type XlsxToWorkbookLayoutOptions = {
+    /** 按 worksheet 名映射到已有 sheet id（导入合并时用） */
+    sheetIdByWorksheetName?: Record<string, string>;
+    /** compact：报表/KTL；chrome：Canvas 模板编辑器 */
+    gridMode?: GridLayoutMode;
+    /** 目标纸张（报表导入应传模板 page，保证与预览/导出同一可印宽） */
+    page?: PageSettings;
+    fitToPrintable?: boolean;
+};
+/** xlsx → 仅含布局的 TemplateWorkbookState（sheet id 由 worksheet 名推导） */
+declare function xlsxToWorkbookLayout(buffer: ArrayBuffer, fileName?: string, options?: XlsxToWorkbookLayoutOptions): Promise<TemplateWorkbookState>;
+
+declare function downloadWorkbookAsExcel(workbook: TemplateWorkbookState, baseName?: string): Promise<void>;
+
+/**
+ * Excel (.xlsx) 解析核心 — 使用 ExcelJS 读取工作簿，输出中间 JSON 格式。
+ */
+
+/**
+ * 解析 .xlsx 文件为中间 JSON 格式
+ */
+declare function parseExcelToIntermediate(file: File, options: ExcelImportOptions): Promise<ExcelImportIntermediateV1>;
+/** 从 ArrayBuffer 解析指定 Sheet 为中间格式 */
+declare function parseExcelBufferToIntermediate(buffer: ArrayBuffer, options: ExcelImportOptions, fileName?: string): Promise<ExcelImportIntermediateV1>;
+/** 解析 xlsx 全部 Sheet（多 Sheet 布局导入） */
+declare function parseExcelBufferAllSheets(buffer: ArrayBuffer, fileName?: string): Promise<ExcelImportIntermediateV1[]>;
+declare function getExcelSheetList(file: File): Promise<{
+    index: number;
+    name: string;
+}[]>;
+
+/**
+ * 将中间 JSON 还原为引擎 SheetTemplateState。
+ * - chrome（默认）：row/col 0 为索引 gutter，供 Canvas 模板编辑器
+ * - compact：KTL/报表，无 gutter，尺寸与 @colWidths 一致
+ */
+type IntermediateToSheetOptions = {
+    gridMode?: GridLayoutMode;
+    /** 目标纸张；报表导入应传入模板 sheet.page */
+    page?: PageSettings;
+    /** 列总宽超出可印宽时等比缩小（默认 true） */
+    fitToPrintable?: boolean;
+};
+declare function intermediateToSheetState(json: ExcelImportIntermediateV1, options?: IntermediateToSheetOptions): SheetTemplateState;
+
+/** 悬浮输入面板跟随模式 */
+type PanelFollowMode = "topSide" | "bottomSide" | "leftSide" | "rightSide" | "fixed";
+declare const PANEL_FOLLOW_MODE_DEFAULT: PanelFollowMode;
+declare function isPanelFollowMode(v: string | null | undefined): v is PanelFollowMode;
+declare function loadPanelFollowMode(): PanelFollowMode;
+declare function savePanelFollowMode(mode: PanelFollowMode): void;
+declare const PANEL_FOLLOW_MODE_OPTIONS: {
+    key: PanelFollowMode;
+    label: string;
+}[];
+
+declare const FLOATING_PANEL_GAP = 4;
+declare const FLOATING_PANEL_DEFAULT_W = 240;
+declare const FLOATING_PANEL_TEXT_H = 120;
+declare const CALENDAR_PANEL_APPROX_H = 320;
+type ViewportPoint = {
+    left: number;
+    top: number;
+};
+type ViewportRect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+declare function clampFloatingPanelPos(pos: ViewportPoint, panelW: number, panelH: number, viewport?: {
+    width: number;
+    height: number;
+}): ViewportPoint;
+/** overlay 盒 + 容器 viewport rect → fixed 定位用的 viewport 坐标 */
+declare function overlayBoxToViewportRect(box: EmbedOverlayBox, containerRect: DOMRect | null | undefined): ViewportRect;
+declare function computeFloatingPanelFollowPos(followMode: PanelFollowMode, cellRect: ViewportRect | null, currentPos: ViewportPoint, panelW: number, panelH: number, gap?: number): ViewportPoint;
+/** 日期/日历弹出层：优先下方，空间不足时翻转到上方 */
+declare function computeDatePopupPos(anchorRect: Pick<DOMRect, "left" | "top" | "bottom">, panelApproxH?: number, gap?: number, viewportH?: number): ViewportPoint;
+/** 单元格 A1 风格标签（0-based r,c，与 sheet 引擎一致） */
+declare function cellEditorA1Label(r: number, c: number): string;
+
+type RasterizeSheetWithEmbedsOptions = RasterizeSheetExportOptions & PaintEmbedsDeps & {
+    sheetId: string;
+    embeds?: WorkbookEmbedDef[];
+    embedStates?: Record<string, EmbedInstanceState>;
+    qrPayloadBySlot?: Record<string, string>;
+    fieldData?: FieldDataCtx;
+    scripts?: WorkbookScripts | null;
+};
+declare function rasterizeSheetWithEmbeds(sheet: SheetTemplateState, mergeIdx: MergeIndex, opts: RasterizeSheetWithEmbedsOptions): Promise<{
+    canvas: HTMLCanvasElement;
+    logicalWidth: number;
+    logicalHeight: number;
+    deviceScale: number;
+}>;
+
+type SheetPdfRasterOptions = PaintEmbedsDeps & {
+    layoutMode: PrintLayoutMode;
+    deviceScale?: number;
+    omitCellBackground?: boolean;
+    sliceSheetFactory?: (sliceIndex: number, sliceCount: number) => SheetTemplateState;
+    sheetId?: string;
+    embedPrintContext?: EmbedPrintContext;
+};
+declare function appendSheetToPdfAsync(pdf: jsPDF | null, sheet: SheetTemplateState, mergeIdx: MergeIndex, page: PageSettings, options: SheetPdfRasterOptions): Promise<jsPDF>;
+/** 同步路径不含 embed 叠画（与 kt-web 历史行为一致）。 */
+declare function appendSheetToPdf(pdf: jsPDF | null, sheet: SheetTemplateState, mergeIdx: MergeIndex, page: PageSettings, options: Omit<SheetPdfRasterOptions, keyof PaintEmbedsDeps>): jsPDF;
+declare function sheetToPdfBlob(sheet: SheetTemplateState, mergeIdx: MergeIndex, page: PageSettings, options: Omit<SheetPdfRasterOptions, keyof PaintEmbedsDeps>): Blob;
+declare function sheetToPdfBlobAsync(sheet: SheetTemplateState, mergeIdx: MergeIndex, page: PageSettings, options: SheetPdfRasterOptions): Promise<Blob>;
+type WorkbookPdfSheetSlice = {
+    sheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    page: PageSettings;
+    layoutMode: PrintLayoutMode;
+    sliceSheetFactory?: (sliceIndex: number, sliceCount: number) => SheetTemplateState;
+    sheetId?: string;
+};
+declare function workbookToPdfBlobAsync(slices: WorkbookPdfSheetSlice[], options: Pick<SheetPdfRasterOptions, "deviceScale" | "omitCellBackground" | "embedPrintContext"> & PaintEmbedsDeps): Promise<Blob>;
+type WorkbookPdfSheetSliceSync = {
+    sheet: SheetTemplateState;
+    mergeIdx: MergeIndex;
+    page: PageSettings;
+    layoutMode: PrintLayoutMode;
+    sliceSheetFactory?: (sliceIndex: number, sliceCount: number) => SheetTemplateState;
+};
+declare function workbookToPdfBlob(slices: WorkbookPdfSheetSlice[], options: {
+    deviceScale?: number;
+    omitCellBackground?: boolean;
+}): Blob;
+
+type BuildPrintDocumentAsyncOptions = BuildPrintDocumentOptions & PaintEmbedsDeps & {
+    sheetId: string;
+    embedPrintContext?: EmbedPrintContext;
+};
+type BuildPrintWorkbookDocumentAsyncOptions = BuildPrintWorkbookDocumentOptions & PaintEmbedsDeps & {
+    embedPrintContext?: EmbedPrintContext;
+    defaultSheetId?: string;
+};
+declare function buildPrintDocumentAsync(opts: BuildPrintDocumentAsyncOptions): Promise<{
+    html: string;
+    pageCount: number;
+}>;
+type BuildPrintWorkbookItemWithSheetId = BuildPrintWorkbookItem & {
+    sheetId?: string;
+};
+declare function buildPrintWorkbookDocumentAsync(opts: BuildPrintWorkbookDocumentAsyncOptions): Promise<{
+    html: string;
+    pageCount: number;
+    uniformPage: boolean;
+}>;
+
+/**
+ * 轻量只读条带（消费级）：给定已解析 sheet，渲染行区间的表格预览（HTML 表格，非 canvas）。
+ * 无 hooks / 无浏览器 API，可在 RSC / LIMS / TAM 直接复用；解析 workbookJson 由宿主完成。
+ */
+type Props = {
+    sheet: SheetTemplateState | null;
+    title: string;
+    rowStart: number;
+    rowEnd: number;
+    className?: string;
+    /** 是否显示 Excel 式列标与行号 */
+    showRulers?: boolean;
+};
+declare function StaticWorkbookSlicePreview({ sheet: sh, title, rowStart, rowEnd, className, showRulers }: Props): react.JSX.Element;
+
+type QrToDataUrlFn = (payload: string, opts: {
+    errorCorrectionLevel?: "L" | "M" | "Q" | "H";
+    margin: number;
+    width: number;
+    color?: {
+        dark?: string;
+        light?: string;
+    };
+}) => Promise<string>;
+type QrEmbedSlotProps = {
+    def: AssetEmbedDef;
+    state?: EmbedInstanceState;
+    payload?: string;
+    readOnly?: boolean;
+    layout: EmbedOverlayLayoutPort;
+    qrToDataUrl: QrToDataUrlFn;
+};
+/** QR 槽位：按 payload 渲染二维码图片 */
+declare function QrEmbedSlot({ def, state, payload, readOnly, layout, qrToDataUrl }: QrEmbedSlotProps): react.JSX.Element | null;
+
+type AssetEmbedHostDeps = {
+    resolveEmbedImageSrc: (fileId: string | undefined) => Promise<string | null>;
+    registerEmbedFileObject: (file: File) => Promise<{
+        fileId: string;
+        previewUrl: string;
+    }>;
+};
+type AssetEmbedHostProps = AssetEmbedHostDeps & {
+    def: AssetEmbedDef;
+    state?: EmbedInstanceState;
+    readOnly?: boolean;
+    layout: EmbedOverlayLayoutPort;
+    onUpload?: (slotId: string, fileId: string) => void;
+    onClear?: (slotId: string) => void;
+};
+/** 签章/图片槽：实例态可点击上传 */
+declare function AssetEmbedHost({ def, state, readOnly, layout, resolveEmbedImageSrc, registerEmbedFileObject, onUpload, onClear, }: AssetEmbedHostProps): react.JSX.Element | null;
+
+/** ECharts 实例最小接口（canvas 不直接依赖 echarts 包） */
+type ChartEchartsInstance = {
+    setOption: (option: unknown, notMerge?: boolean) => void;
+    resize: (opts: {
+        width: number;
+        height: number;
+    }) => void;
+    dispose: () => void;
+};
+/** 宿主注入：ECharts 初始化与 option 构建 */
+type ChartEchartsPort = {
+    init: (el: HTMLElement) => ChartEchartsInstance;
+    buildOption: (def: _k_table_sheet_core.ChartEmbedDef, seriesData: unknown) => unknown;
+    ensureModules: (option: unknown, def: _k_table_sheet_core.ChartEmbedDef) => void;
+    getOptionEvalError: (def: _k_table_sheet_core.ChartEmbedDef, seriesData: unknown) => string | null;
+};
+type ChartEmbedHostProps = {
+    def: _k_table_sheet_core.ChartEmbedDef;
+    state?: _k_table_sheet_core.EmbedInstanceState;
+    layout: EmbedOverlayBox | null;
+    /** scroll/zoom 变化时递增，触发 resize */
+    layoutTick?: number;
+    resolveSeriesData: () => unknown | null;
+    echartsPort: ChartEchartsPort;
+    resolveEmbedImageSrc: (fileId: string | undefined) => Promise<string | null>;
+    /** 计算完成后刷新图表（实例态） */
+    onComputeDone?: (handler: () => void) => () => void;
+};
+
+/** 图表嵌入 host：ECharts 渲染由宿主注入 ChartEchartsPort */
+declare function ChartEmbedHost({ def, state, layout, layoutTick, resolveSeriesData, echartsPort, resolveEmbedImageSrc, onComputeDone, }: ChartEmbedHostProps): react.JSX.Element | null;
+
+type SheetEmbedOverlayProps = {
+    assets: AssetEmbedDef[];
+    charts: ChartEmbedDef[];
+    layout: EmbedOverlayLayoutPort;
+    /** 由宿主渲染 ChartEmbedHost（避免 canvas 内循环依赖 workbook store） */
+    renderChart: (def: ChartEmbedDef) => ReactNode;
+};
+/** 嵌入层 DOM：设计态 asset 虚线框 + chart（由 renderChart 注入） */
+declare function SheetEmbedOverlay({ assets, charts, layout, renderChart }: SheetEmbedOverlayProps): react.JSX.Element;
+
+type InstanceAssetLayerProps = {
+    assets: AssetEmbedDef[];
+    charts: ChartEmbedDef[];
+    embedStates?: Record<string, EmbedInstanceState>;
+    qrPayloads: Record<string, string>;
+    readOnly?: boolean;
+    showCharts?: boolean;
+    renderChart: (def: ChartEmbedDef, state?: EmbedInstanceState) => ReactNode;
+    renderQr: (def: AssetEmbedDef, state?: EmbedInstanceState, payload?: string) => ReactNode;
+    renderAsset: (def: AssetEmbedDef, state?: EmbedInstanceState) => ReactNode;
+};
+/** 实例态嵌入层：按 asset/chart 列表渲染，具体 host 由宿主 inject render* 回调 */
+declare function InstanceAssetLayer({ assets, charts, embedStates, qrPayloads, showCharts, renderChart, renderQr, renderAsset, }: InstanceAssetLayerProps): react.JSX.Element;
+type InstanceEmbedLayerMode = "design" | "instance";
+type InstanceEmbedLayerProps = {
+    mode: InstanceEmbedLayerMode;
+    /** 设计态 overlay（宿主注入 SheetEmbedOverlay shim） */
+    designOverlay: ReactNode;
+    /** 实例态 asset/chart 层 */
+    instanceLayer: ReactNode;
+};
+/** 实例/设计态嵌入层入口（mode 切换） */
+declare function InstanceEmbedLayer({ mode, designOverlay, instanceLayer }: InstanceEmbedLayerProps): ReactNode;
+
+/**
+ * 名称框 A1 地址格式化/解析（网格 1-based：A1 对应 r=1,c=1）。
+ * 与 @k-table/sheet-core 的 formula/coords A1（0-based、异常抛错）语义不同，故置于画布 UI 层。
+ */
+/** 数据区单元格地址，如 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;
+declare function parseA1(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;
+
+/**
+ * @k-table/sheet-canvas — kt 表格画布/渲染层（增量抽包，M3）。
+ *
+ * 职责：Canvas 2D 绘制适配、React 编辑器/实例组件、打印/PDF 叠层。
+ * 依赖 @k-table/sheet-core（无头引擎）与 @k-table/sheet-host（契约）；React/echarts/antd 为宿主 external。
+ * 纯几何/模型/引擎逻辑属 core，本包只放"需要 DOM/React/Canvas"的部分。
+ */
+declare const SHEET_CANVAS_PACKAGE: "@k-table/sheet-canvas";
+
+export { type ApplyFillOptions, type ApplyMergeSelectionOptions, AssetEmbedHost, type AssetEmbedHostDeps, type AssetEmbedHostProps, type BindingOverlayDeps, type BuildPrintDocumentAsyncOptions, type BuildPrintDocumentOptions, type BuildPrintWorkbookDocumentAsyncOptions, type BuildPrintWorkbookDocumentOptions, type BuildPrintWorkbookItem, type BuildPrintWorkbookItemWithSheetId, CALENDAR_PANEL_APPROX_H, type ChartEchartsInstance, type ChartEchartsPort, ChartEmbedHost, type ChartEmbedHostProps as ChartEmbedHostCoreProps, DEFAULT_SHEET_CANVAS_PAINT_PORT, DEFAULT_SHEET_PAINT_PALETTE, EMBED_CELL_INSET_CSS_PX, EMBED_CELL_INSET_PT, type EmbedCellOffset, type EmbedOverlayBox, type EmbedOverlayLayoutPort, type ExportBoundsRowsCols, FILL_HANDLE_PX, FLOATING_PANEL_DEFAULT_W, FLOATING_PANEL_GAP, FLOATING_PANEL_TEXT_H, type FillPattern, InstanceAssetLayer, type InstanceAssetLayerProps, InstanceEmbedLayer, type InstanceEmbedLayerMode, type InstanceEmbedLayerProps, type InstanceFillGuard, type InstancePasteGuard, type InstanceSelectionChromeState, MAX_BORDER_STROKE_WIDTH_PX, type MergeIndex, PANEL_FOLLOW_MODE_DEFAULT, PANEL_FOLLOW_MODE_OPTIONS, PRINT_EXPORT_PRESET, type PaintEmbedsDeps, type PaintEmbedsOptions, type PaintSheetCanvasFrameInput, type PaintVirtualBandBindingOverlay, type PaintVirtualBandOptions, type PanelFollowMode, type PasteCellStyleOptions, type PrintLayoutMode, QrEmbedSlot, type QrEmbedSlotProps, type QrToDataUrlFn, type RasterizeSheetExportOptions, type RasterizeSheetWithEmbedsOptions, type ResolvedEmbedRect, SHEET_ACTIVE_CELL_BG, SHEET_ACTIVE_OUTLINE, SHEET_CANVAS_PACKAGE, SHEET_CLIPBOARD_MIME, SHEET_DATA_BG, SHEET_GRID_LINE_DATA, SHEET_GRID_LINE_HEADER, SHEET_HEADER_BG, SHEET_HEADER_SEL_ACCENT_PX, SHEET_HEADER_SEL_BG, SHEET_INSTANCE_FILL_LOCKED_BG, SHEET_SEL_FILL, SHEET_SEL_STROKE, SHEET_SHADOW_STYLES, type ScrollRevealInput, type SelectionEditChromeFlags, type SelectionHeaderHighlight, type SheetCanvasPaintPort, type SheetCanvasViewport, type SheetClipboardFragmentV1, type SheetDragEndInput, type SheetDragEndOutcome, type SheetDragGuide, type SheetDragMoveInput, type SheetDragMoveOutcome, type SheetDragState, SheetEmbedOverlay, type SheetEmbedOverlayProps, type SheetExportOptions, type SheetExportSizeOptions, type SheetPaintPalette, type SheetPdfRasterOptions, type SheetPointerCursorInput, type SheetPointerDownInput, type SheetPointerDownResult, type SheetScrollPort, type SheetWindowDragListeners, StaticWorkbookSlicePreview, type ViewportPoint, type ViewportRect, type WorkbookPdfSheetSlice, type WorkbookPdfSheetSliceSync, type XlsxToWorkbookLayoutOptions, appendSheetToPdf, appendSheetToPdfAsync, applyFillToSheet, applyMergeSelection, applyRichGridToSheet, applyScriptToRunSubstring, applyTdAlignAttrs, applyTextRunStylePatchToSubstring, assetBoxOverlayBox, assetBoxPrintRect, attachSheetWindowDragListeners, borderStrokeWidth, boundaryAtPlainIndex, buildFillDragState, buildMergeIndex, buildPrintDocument, buildPrintDocumentAsync, buildPrintWorkbookDocument, buildPrintWorkbookDocumentAsync, cellDataFromEdit, cellEditorA1Label, cellStyleFromTableCell, chartSpanOverlayBox, chartSpanPrintRect, clampColumnHeaderDragEnd, clampFloatingPanelPos, clampRowHeaderDragEnd, clampSelection, clampSheetViewZoom, clientToSheetCoords, clipboardItemsToPastePayload, collectEmbedAnchorRect, columnDividerAtX, columnDividerAtXInHeaderRow, computeColumnHeaderPointerSelection, computeDataCellPointerSelection, computeDatePopupPos, computeFillPreviewSelectionInstance, computeFloatingPanelFollowPos, computeResizedColWidth, computeResizedRowHeight, computeRowHeaderPointerSelection, computeScrollToRevealSelection, computeSelectAllCornerSelection, createSheetScrollPort, createSheetWindowDragHandlers, ctxTextMeasurer, denseGridToLogicalPlainGrid, detachSheetWindowDragListeners, downloadExcelFile, downloadSheetAsExcel, downloadWorkbookAsExcel, drawCellBorders, editableHtmlToRuns, effectiveDefaultFontPtForPaint, embedDisplayLabel, ensureMinDimensions, expandMergeSelectionRect, extractClassStyleMapFromDocument, extractFillPattern, fillHandleBlockedByEdit, finalizeCellDataForSave, formatA1, formatSelectionA1, getCellRect, getDisplayRuns, getExcelSheetList, getGridClipBleedPx, getMaster, getMergeRect, getMergedPixelRect, getPlainOffsetsFromSelection, getPrintPageOverlayRects, getSelectionForEditableRoot, getSelectionPixelBounds, getSheetExportSize, getUsedDataBounds, getUsedExportPixelRect, hasMeaningfulRuns, hitTestFillHandle, hitTestToCell, htmlTableToRichGrid, htmlTableToRichGridWithSpans, htmlTableToTsv, insertCol, insertRow, insetOverlayBox, instanceSelectionChromeState, intermediateToSheetState, isCellUsedForPrintBounds, isColumnHeaderRow, isDataCell, isDataCellTextuallyEmpty, isFillHandlePointerDown, isHeaderCorner, isPanelFollowMode, isPointerInVirtualBottomBand, isPointerInVirtualTopBand, isRowHeaderCol, joinRuns, listEmbedAnchorBindings, loadPanelFollowMode, mergeCellStylesLoose, mergeRunStyle, mergeScriptIntoRuns, mergesOverlap, normalizeCellDataValue, normalizeCssColorToHex, normalizeMerge, normalizeRuns, normalizeSelectDragHit, overlayBoxToViewportRect, pageSettingsPrintKey, paintDesignBindingOverlayForDataCell, paintDesignFormulaOverlayForDataCell, paintEmbedsToCanvas, paintSheetCanvasFrame, paintSheetDataCellContent, paintVirtualSheetBand, parseA1, parseA1OrRangeToSelection, parseExcelBufferAllSheets, parseExcelBufferToIntermediate, parseExcelToIntermediate, parseGridRcAddress, parseSpreadsheetInlineCss, parseTsvGrid, pasteCellStyleAndRuns, pasteClipboardInstanceValuesOnly, pasteClipboardIntoSheet, pasteTsvAt, plainLengthToBoundary, preferredWindowDragMoveEvent, processSheetDragEnd, processSheetDragMove, processSheetPointerDown, rasterizeSheetExport, rasterizeSheetExportToCanvas, rasterizeSheetWithEmbeds, readClipboardForSheetPaste, renderSheetExport, resolveChartLayoutRect, resolveChartPrintRect, resolveColResizeDivider, resolveContextMenuCell, resolveFillDragAxis, resolveFormulaPickerRefText, resolveRowResizeDivider, resolveSheetPaintPalette, resolveSheetPointerCursor, rowDividerAtY, rowDividerAtYInHeaderCol, runsFromCellContentRoot, runsToEditableHtml, savePanelFollowMode, selectionBoundsMatchEntireMerge, selectionEditChromeFlags, selectionHeaderHighlightFlags, selectionMatchesMergeMaster, selectionToClipboardPayload, selectionToTsv, setCell, setPlainTextSelection, setupSheetCanvasElement, sheetChrome, sheetToExcelBuffer, sheetToPdfBlob, sheetToPdfBlobAsync, sheetTotalSize, shouldIgnorePointerOutsideMidBand, shouldKeepInlineEditFocus, shouldSkipScrollRevealForSelection, sliceExportCanvasToDataUrls, splitRunsIntoLines, splitTsvLine, strokeHeaderCellGrid, strokeUnmergedCellGrid, virtualBandWorldHeight, visibleColRange, visibleRowRange, visibleRowRangeInBand, workbookToExcelBuffer, workbookToPdfBlob, workbookToPdfBlobAsync, wrapRunsLinesToMaxWidth, writeSheetClipboardPayload, writeSheetToWorksheet, xlsxToWorkbookLayout };