ooxml-excel-editor 1.1.0 → 1.3.0

package/dist/core/edit/context-menu.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 右键上下文菜单宿主(框架无关 DOM)—— 挂到 document.body 的 fixed 菜单,点项执行 action + 关闭,
+ * 点外部 / Esc 关闭,贴边自动翻转。Vue / React 壳只把 contextmenu 事件转给 controller,菜单逻辑全在这。
+ */
+export interface MenuItem {
+    label?: string;
+    action?: () => void;
+    disabled?: boolean;
+    /** true = 分隔线 */
+    separator?: boolean;
+}
+export declare class ContextMenuHost {
+    private el;
+    private cleanup;
+    isOpen(): boolean;
+    show(x: number, y: number, items: MenuItem[]): void;
+    close(): void;
+    dispose(): void;
+}

package/dist/core/edit/edit-controller.d.ts

@@ -1,10 +1,11 @@
 import { CellStyleOverride, ColumnInfo, ImageAnchor, MergeRange, RowInfo, SheetModel, WorkbookModel } from '../model/types';
 import { CellValue } from '../model/data-access';
 import { CellSnapshot } from '../model/snapshot';
-import { CellPos, DimAxis } from './commands';
+import { ParsedClipboard } from './clipboard-html';
+import { CellPos, DimAxis, EditCommand } from './commands';
 import { StructOp } from '../model/structure';
 import { FormulaEngineFactory } from '../formula/engine';
-export type EditEventName = 'cell-change' | 'edit-start' | 'edit-commit' | 'dim-change' | 'dirty-change' | 'image-change' | 'struct-change';
+export type EditEventName = 'cell-change' | 'edit-start' | 'edit-commit' | 'dim-change' | 'dirty-change' | 'image-change' | 'struct-change' | 'permission-denied';
 export type EditSource = 'api' | 'ui' | 'undo' | 'redo';
 /** 结构变更事件载荷(增删行列;restore = 撤销/重做的整体还原) */
 export interface StructChangePayload {
@@ -93,6 +94,14 @@ export declare class EditController {
     editCell(row: number, col: number, value: CellValue): boolean;
     /** 区域批量设值(2D,左上对齐 range.top/left);跳过只读格,返回是否有改动 */
     editRange(range: MergeRange, values: CellValue[][]): boolean;
+    /**
+     * 富粘贴(Excel/WPS 复制的 HTML 解析后):值 + 样式 + 合并 + 图片,**整体单次撤销**。
+     * start = 落点左上角。跳过只读格。一次 cloneWorkbook 快照 → 应用全部 → 压一条 restore-wb 逆。
+     */
+    pasteRich(start: {
+        row: number;
+        col: number;
+    }, parsed: ParsedClipboard): boolean;
     /** 清空区域(跳过只读) */
     clearRange(range: MergeRange): boolean;
     /** 给区域套样式覆盖(E5;跳过只读格)。返回是否有改动。前后 style 不同 → 发 cell-change。 */
@@ -102,6 +111,12 @@ export declare class EditController {
     insertCols(at: number, count?: number): boolean;
     deleteCols(at: number, count?: number): boolean;
     private structEdit;
+    /** 合并区域(吸收相交旧合并,清空被覆盖格只留左上锚点)。单格不合并。
+     *  Phase A 补漏 (2026-06-08): 区域内任一格只读 → 拒绝整次合并 + emit permission-denied. */
+    mergeCells(range: MergeRange): boolean;
+    /** 拆分:移除与区域相交的所有合并。
+     *  Phase A 补漏 (2026-06-08): 区域内任一格只读 → 拒绝整次拆分 + emit permission-denied. */
+    unmergeCells(range: MergeRange): boolean;
     /** 读当前表全部图片锚点(克隆,防外部改)。 */
     getImages(): ImageAnchor[];
     /** 加一张图,返回插入索引(失败 -1)。 */
@@ -113,8 +128,57 @@ export declare class EditController {
      * baseline 须在变更前由调用方 ensureBaseline() 捕获。
      */
     recordImageEdit(index: number, before: ImageAnchor, after: ImageAnchor): void;
+    /**
+     * 浮动图 → 单元格内嵌图(DISPIMG):把第 imageIndex 张浮动图塞进 (row,col) 格。
+     * 图缺字节不可转 → 返 false。入命令栈(undo 走整簿快照还原)。
+     */
+    convertImageToCell(imageIndex: number, row: number, col: number): boolean;
+    /**
+     * 批量把多张浮动图嵌入各自的目标格(整表/整列);一次进撤销栈。返回成功嵌入的张数。
+     * targets 的 imageIndex 是调用前的浮动图索引(内部按降序 splice,索引互不干扰)。
+     * Phase A 补漏: 过滤掉目标格只读的 targets, denied 一次性 emit.
+     */
+    convertImagesToCells(targets: {
+        imageIndex: number;
+        row: number;
+        col: number;
+    }[]): number;
+    /**
+     * 单元格内嵌图 → 浮动图:把 (row,col) 的 DISPIMG 拎出来变成浮动图(默认 96×96px)。
+     * 非内嵌图格 → 返 false。入命令栈。
+     * Phase A 补漏: 源格只读 → 拒绝 (拎出来意味着该格内容变了,属于修改).
+     */
+    convertCellImageToFloat(row: number, col: number, size?: {
+        width: number;
+        height: number;
+    }): boolean;
+    /**
+     * 批量把多格 DISPIMG 拎成浮动图(选区批量反向);非内嵌图格自动跳过;一次进撤销栈。
+     * 返回成功转换的张数。
+     * Phase A 补漏: 过滤掉源格只读的, denied 一次性 emit.
+     */
+    convertCellImagesToFloats(cells: {
+        row: number;
+        col: number;
+        size?: {
+            width: number;
+            height: number;
+        };
+    }[]): number;
     /** 程序化设列宽/行高(API 路径:apply-via-command)。返回是否生效。 */
     setDimension(axis: DimAxis, index: number, size: number): boolean;
+    /**
+     * 批量设维度尺寸 (Phase B, 2026-06-08). target 接 number | number[] | {from,to}.
+     * 多 index 时聚合成单次 restore-wb undo (跟 convertImagesToCells 范式一致).
+     * strictDimensions=true + 白名单未覆盖某 index → skip 那个 + 累计 deniedDims; 整次结束 emit 一次 permission-denied.
+     * 返回成功条数 (0 = 全 skip / editable=false).
+     */
+    setDimensions(axis: DimAxis, indices: number[], size: number, canDim: (i: number) => boolean): number;
+    /**
+     * 重置某些列宽/行高到默认 (Phase B, 2026-06-08) — 移除 columns/rows Map 条目, 渲染回落 defaultColWidth/Height.
+     * 多 index 时单次 restore-wb undo.
+     */
+    resetDimensions(axis: DimAxis, indices: number[], canDim: (i: number) => boolean): number;
     /**
      * 补登一次维度变更(拖拽/autofit 路径:模型已被 renderer 改完,这里只补 undo 项 + 发事件)。
      * baseline 须在变更前(拖拽起始/autofit 前)由调用方 ensureBaseline() 捕获。
@@ -132,6 +196,10 @@ export declare class EditController {
     redo(): void;
     private collectEditable;
     private pushUndo;
+    /** 公开版 pushUndo (Phase B 2026-06-08): 给 controller 的批量 autoFit 用. 一般业务不要直调. */
+    pushUndoExternal(inverse: EditCommand): void;
+    /** 公开版 markDirty: 给 controller 的批量 autoFit 用. 一般业务不要直调. */
+    markDirtyExternal(): void;
     /** 应用一条命令:建前快照 → apply → 重绘 → 发事件(cell 族 cell-change / dim 族 dim-change)。返回逆命令。 */
     private exec;
 }

package/dist/core/edit/editor-context.d.ts

@@ -27,12 +27,27 @@ export interface CellEditorContext {
     commit(value: EditorCommitValue, move?: 'down' | 'right'): void;
     /** 取消编辑(不改模型) */
     cancel(): void;
+    /**
+     * 请求 host 重新 position 编辑器 (Phase 1 长文本撑高用, 2026-06-08).
+     * 编辑器在内容变化(input 事件)后调一次, host 会重新读 `getDesiredHeight()` 并撑高.
+     * 不实现 `getDesiredHeight` 的编辑器调它无效(仍按 cell rect 尺寸).
+     */
+    reposition?(): void;
 }
-/** 编辑器工厂:返回 DOM 元素,或 { el, destroy }(destroy 在卸载时清理) */
-export type CellEditorFactory = (ctx: CellEditorContext) => HTMLElement | {
+/**
+ * 编辑器工厂的返回类型:可以是裸 HTMLElement, 或带钩子的对象.
+ * - `destroy`: 卸载时清理(可选)
+ * - `getDesiredHeight`: Phase 1 长文本撑高用. host 在 position 时调, 传入当前列宽 (px),
+ *   编辑器返回内容期望的总高度 (px). host 取 max(原 cell h, desired) 作为最终高度.
+ *   不实现 = 高度锁定为单元格高度(老行为).
+ */
+export interface CellEditorReturn {
     el: HTMLElement;
     destroy?: () => void;
-};
+    getDesiredHeight?(widthPx: number): number;
+}
+/** 编辑器工厂:返回 DOM 元素,或 { el, destroy?, getDesiredHeight? }(destroy 在卸载时清理) */
+export type CellEditorFactory = (ctx: CellEditorContext) => HTMLElement | CellEditorReturn;
 /** 编辑器解析器:按格决定用哪个工厂(无 → 该格无自定义编辑器) */
 export type EditorResolver = (cell: CellModel | null, pos: {
     row: number;

package/dist/core/edit/editor-host.d.ts

@@ -14,7 +14,12 @@ export declare class CellEditorHost {
      * rectOverride 给定时用它定位(合并单元格 → 整片合并区),否则按单格 rectOf。
      */
     mount(row: number, col: number, factory: CellEditorFactory, ctx: CellEditorContext, rectOverride?: () => Rect | null): boolean;
-    /** 按当前 rectOf 重定位活动编辑器(滚动/缩放后跟随) */
+    /**
+     * 按当前 rectOf 重定位活动编辑器(滚动/缩放后跟随).
+     * Phase 1 长文本撑高 (2026-06-08): 若编辑器实现了 `getDesiredHeight`,
+     * 最终高度 = max(单元格原高, 期望高度), 上限 viewport 一半防撑爆.
+     * 宽度仍 = 列宽 (跟 WPS 一致, 仅向下溢出).
+     */
     position(): void;
     /** 卸载活动编辑器 */
     unmount(): void;

package/dist/core/edit/permissions.d.ts

@@ -1,3 +1,42 @@
-import { SheetModel } from '../model/types';
-import { EditConfig } from './types';
+import { MergeRange, SheetModel } from '../model/types';
+import { DimTarget, EditableTarget, EditConfig } from './types';
+/** 把 DimTarget 3 形态规范化成 index 数组. 重复 / 越界由调用方各自处理. */
+export declare function normalizeDimTarget(target: DimTarget): number[];
+/**
+ * 该列/行能否改尺寸 (Phase B, 2026-06-08).
+ * - editable=false → 一律 false
+ * - strictDimensions=false (默认) → 仅受全局 editable 控制, 一律 true
+ * - strictDimensions=true + 没设白名单 → true (没白名单 = 默认全可编辑)
+ * - strictDimensions=true + 设了白名单 → 该轴 index 上至少 1 格在白名单内才 true
+ */
+export declare function canEditDimension(sheet: SheetModel, axis: 'col' | 'row', index: number, cfg: EditConfig): boolean;
+/** 单格 / 行 / 列 / 区域 四态 target 命中判定. 形状由有哪些字段自动识别. */
+export declare function matchesEditableTarget(row: number, col: number, t: EditableTarget): boolean;
+/** 把一组格按"是否可编辑"二分. 用于粘贴 / 图片转换 等"批量目标 + 部分跳过"场景. */
+export declare function partitionByEditable(sheet: SheetModel, cells: Array<{
+    row: number;
+    col: number;
+}>, cfg: EditConfig): {
+    allowed: Array<{
+        row: number;
+        col: number;
+    }>;
+    denied: Array<{
+        row: number;
+        col: number;
+    }>;
+};
+/** 区域是否**全可编辑**(任一格只读即返 ok=false + firstDenied). 用于 mergeCells / unmergeCells. */
+export declare function rangeAllEditable(sheet: SheetModel, range: MergeRange, cfg: EditConfig): {
+    ok: boolean;
+    firstDenied?: {
+        row: number;
+        col: number;
+    };
+};
+/** 收集区域里全部不可编辑的格(用于 emit permission-denied 时填 cells 列表). */
+export declare function collectDeniedInRange(sheet: SheetModel, range: MergeRange, cfg: EditConfig): Array<{
+    row: number;
+    col: number;
+}>;
 export declare function resolveEditable(sheet: SheetModel, row: number, col: number, cfg: EditConfig): boolean;

package/dist/core/edit/types.d.ts

@@ -1,5 +1,46 @@
 import { CellModel, MergeRange } from '../model/types';
 import { FormulaEngineFactory } from '../formula/engine';
+/**
+ * 行/列维度目标 (Phase B, 2026-06-08) —— 用于尺寸 API (setColumnWidth / setRowHeight /
+ * autoFitColumns / resetColumnWidth ...) 的参数. 3 种形状自动识别:
+ *
+ *   ┌────────────────────┬──────────────────────────┐
+ *   │ 形状                │ 含义                      │
+ *   ├────────────────────┼──────────────────────────┤
+ *   │ `number`           │ 单个 index               │
+ *   │ `number[]`         │ 多 index (允许不相邻)     │
+ *   │ `{ from, to }`     │ 闭区间范围               │
+ *   └────────────────────┴──────────────────────────┘
+ */
+export type DimTarget = number | number[] | {
+    from: number;
+    to: number;
+};
+/**
+ * 可编辑目标 —— 用于 `EditConfig.editableTargets` 的白名单元素;接受 4 种形状,
+ * 自动识别(看带哪些字段):
+ *
+ *   ┌──────────────────────────────────────┬─────────────────────────────┐
+ *   │ 形状                                  │ 含义                         │
+ *   ├──────────────────────────────────────┼─────────────────────────────┤
+ *   │ `{ row, col }`                       │ 单格(命中精确这一格)         │
+ *   │ `{ row }`                            │ 整行(该行所有列)             │
+ *   │ `{ col }`                            │ 整列(该列所有行)             │
+ *   │ `{ top, left, bottom, right }`       │ 矩形区域(0-based 闭区间)     │
+ *   └──────────────────────────────────────┴─────────────────────────────┘
+ *
+ * 多个 target 可以**重叠 / 不相邻**;命中**任一**就算可编辑。
+ */
+export type EditableTarget = {
+    row: number;
+    col: number;
+} | {
+    row: number;
+    col?: undefined;
+} | {
+    col: number;
+    row?: undefined;
+} | MergeRange;
 export interface EditConfig {
     /** 总开关:默认 false = 只读(行为与历史完全一致) */
     editable?: boolean;
@@ -10,6 +51,27 @@ export interface EditConfig {
     }) => boolean | void;
     /** 只读区域(0-based 闭区间);命中即只读 */
     readOnlyRanges?: MergeRange[];
+    /**
+     * **可编辑白名单**(2026-06-08 新增) —— 设了就是"白名单模式":默认只读,
+     * 只有命中**任一** target 的格才可编辑。**未设(undefined)= 默认全可编辑**
+     * (老行为)。**显式传空数组 `[]`** = 全只读(没格在白名单)。
+     *
+     * 用例: 协同编辑、点检表单只填几格、模板里只让用户改"金额"列等.
+     *
+     * 与黑名单组合(优先级): `editable=false` → 全只读 ► 不在白名单 → 只读 ►
+     * 命中 `readOnlyRanges` → 只读 ► `cellReadOnly` 返 true → 只读 ► 否则可编辑.
+     */
+    editableTargets?: EditableTarget | EditableTarget[];
+    /**
+     * **严格尺寸闸门**(Phase B, 2026-06-08) —— 默认 `false`:setColumnWidth / setRowHeight /
+     * autoFit / resetDimensions 等尺寸 API 仅受 `editable` 全局闸门控制 (老行为, 简单).
+     *
+     * 设 `true` + 启用了 `editableTargets` 白名单 → 升级语义:**该列/行至少有 1 格在白名单内**
+     * 才能改它的宽高; 否则拒绝 + emit permission-denied (reason='dimension').
+     *
+     * 跟"白名单未覆盖 = 完全只读"的严格语义一致, 防"用户改不了数据但能改列宽行高"。
+     */
+    strictDimensions?: boolean;
     /**
      * 公式重算(E4):默认 false = 沿用 Excel 缓存值(只读/无公式路径零成本)。
      * 开启后,编辑公式格或被公式引用的格 → 依赖格自动重算并逐个发 cell-change。

package/dist/core/export/abort.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 长任务防假死 + 取消的两件小工具(框架无关)。
+ *
+ * 长导出(PDF / PNG / XLSX、批量图片转换)必须在循环中:
+ *   1. checkAborted(signal) — 用户调 abortController.abort() 立刻中断
+ *   2. await yieldToEvent() — 让出主线程跑一次绘制 / 事件,避免 UI 假死
+ * 配合 ExportProgress 的 onProgress 回调,使用者可显示进度条 + 取消按钮。
+ */
+/**
+ * 让出主线程跑一帧。优先 requestAnimationFrame(浏览器),其次 setTimeout(node / worker 无 rAF)。
+ * 用 await yieldToEvent() 包在循环里防 UI 假死。返回 0 让调用方可选取用时间戳。
+ */
+export declare function yieldToEvent(): Promise<number>;
+/**
+ * 抛 AbortError 让上层 try/catch 区分"取消"与"真出错"。
+ * AbortSignal 标准:`signal.aborted === true` 时调用方应 throw `DOMException('Aborted', 'AbortError')`。
+ * 跨环境兜底:Node 18+ / 现代浏览器 / Worker 均有 DOMException;无 DOMException 时回退普通 Error 但保留 name。
+ */
+export declare function checkAborted(signal?: AbortSignal): void;
+/** 判断是否 AbortError(便于上层在 catch 里区分,避免吞掉真异常) */
+export declare function isAbortError(e: unknown): boolean;

package/dist/core/export/exporter.d.ts

@@ -41,7 +41,8 @@ export declare class WorkbookExporter {
     /** 导出当前/指定表为图片 Blob(图片为单表;多表请用 PDF) */
     exportImage(opts?: ImageExportOptions): Promise<Blob>;
     downloadImage(opts?: ImageExportOptions): Promise<void>;
-    /** 导出为 PDF Blob(每个目标表分页;需可选依赖 jspdf)。未显式指定的页面参数取自工作表 pageSetup。 */
+    /** 导出为 PDF Blob(每个目标表分页;需可选依赖 jspdf)。未显式指定的页面参数取自工作表 pageSetup。
+     *  支持 `onProgress` 分阶段(render/compose/paginate/write)报进度 + `signal` 取消(标准 AbortSignal)。 */
     exportPdf(opts?: PdfExportOptions): Promise<Blob>;
     downloadPdf(opts?: PdfExportOptions): Promise<void>;
     /** 打开系统打印(可在对话框另存为 PDF)。页面参数同样默认取自 pageSetup。 */

package/dist/core/export/types.d.ts

@@ -1,4 +1,5 @@
 import { MergeRange } from '../model/types';
+import { ExportProgressFn } from '../progress';
 /** 选哪些工作表导出 */
 export type ExportTarget = 'active' | 'all' | number | number[];
 /** 公共渲染选项(决定底图怎么画) */
@@ -13,6 +14,13 @@ export interface RenderExportOptions {
     gridlines?: boolean;
     /** 背景色(默认白) */
     background?: string;
+    /**
+     * 长任务进度回调。每个调度阶段(render/compose/paginate/write/zip)各 emit。
+     * 大表 / 多表 / 多页时穿插 `await yieldToEvent()` 避免 UI 假死。
+     */
+    onProgress?: ExportProgressFn;
+    /** 取消信号。`abortController.abort()` 后下一个调度点抛 AbortError(标准语义) */
+    signal?: AbortSignal;
 }
 /** 图片导出选项 */
 export interface ImageExportOptions extends RenderExportOptions {

package/dist/core/export/wps-cellimages.d.ts

@@ -0,0 +1,6 @@
+import { WorkbookModel } from '../model/types';
+/**
+ * 把 WorkbookModel.cellImages 回注进 ExcelJS 写出的 zip 字节,返回新 zip 字节。
+ * 无内嵌图(或全缺字节)→ 原样返回(零开销)。
+ */
+export declare function injectCellImagesIntoZip(zipBytes: Uint8Array, workbook: WorkbookModel): Uint8Array;

package/dist/core/export/xlsx-writer.d.ts

@@ -1,4 +1,5 @@
 import { WorkbookModel } from '../model/types';
+import { ExportProgressFn } from '../progress';
 export interface XlsxExportOptions {
     /**
      * 保真模式:
@@ -6,10 +7,18 @@ export interface XlsxExportOptions {
      * - `'overlay'`:重载原始 .xlsx,只把编辑后的 值/样式/合并/行高列宽/冻结 叠加上去,**保留** ExcelJS
      *   能往返的其余部分(条件格式/数据验证/打印设置/定义名/图表等)。需 `sourceBuffer`(壳自动注入);
      *   缺原件时自动回退 rebuild。注:overlay 不反映 结构增删行列 / 图片 编辑(那类用 rebuild)。
+     *
+     * WPS 单元格内嵌图(DISPIMG):两种模式都会在 ExcelJS 写出后**于 zip 层回注** `xl/cellimages.xml`
+     * + rels + media + Content_Types/workbook-rels(见 wps-cellimages.ts),从模型重建 → 原有的 + App 内
+     * 新转的内嵌图导出后都在(blob-only 无字节的图除外)。导出 → 用 WPS 打开,内嵌图正常显示。
      */
     fidelity?: 'rebuild' | 'overlay';
     /** 原始 .xlsx 字节(overlay 模式用;由 exporter 从 host 注入,用方一般不直接传) */
     sourceBuffer?: ArrayBuffer;
+    /** 长任务进度回调(zip 写出前/后 emit `{stage:'zip'}`;exceljs writeBuffer 黑盒) */
+    onProgress?: ExportProgressFn;
+    /** 取消信号(zip 阶段前后检查) */
+    signal?: AbortSignal;
 }
 /** WorkbookModel → .xlsx Blob(懒加载 exceljs)。overlay 模式重载原件叠加编辑,否则从模型重建。 */
 export declare function workbookToXlsxBlob(workbook: WorkbookModel, opts?: XlsxExportOptions): Promise<Blob>;

package/dist/core/format/color.d.ts

@@ -1,5 +1,10 @@
 import { CssColor } from '../model/types';
 export declare function argbToCss(argb: string | undefined): CssColor | undefined;
+/**
+ * 任意 css 颜色 → `#RRGGBB`(大写);供 <input type=color> 回显 / 粘贴样式解析。
+ * 支持 #RGB / #RRGGBB / #RRGGBBAA / rgb()/rgba();识别不了返 ''。
+ */
+export declare function toHex6(css: string | undefined): string;
 export declare function indexedToCss(idx: number): CssColor | undefined;
 /** 主题色 + tint → css。tint > 0 变亮，< 0 变暗(按 OOXML 规范的 HSL Luminance 调整)。 */
 export declare function themeToCss(themeColors: CssColor[], themeIdx: number, tint?: number): CssColor | undefined;

package/dist/core/format/number-format.d.ts

@@ -3,3 +3,6 @@ export interface FormatResult {
     color?: string;
 }
 export declare function formatValue(value: number | string | boolean | Date | null, code: string | undefined, date1904?: boolean): FormatResult;
+/** Date → Excel 序列号(导出/往返用). date1904=true 时 epoch=1904-01-01;
+ *  1900 系统时跳过 phantom 1900-02-29(序号 ≥ 60 加 1 补回 bug 偏移). */
+export declare function dateToSerial(date: Date, date1904: boolean): number;

package/dist/core/layout/autofit.d.ts

@@ -1,2 +1,5 @@
 import { SheetModel, WorkbookModel } from '../model/types';
+/** 失效某 sheet 的"已 fit"标记;下次 autoFitRowHeights 会重新测量。
+ *  用法:模型有结构性变化(wrapText 切换 / 富文本编辑 / 列宽改) → 行高需按新内容重撑 → 调一次。 */
+export declare function invalidateAutofit(sheet: SheetModel): void;
 export declare function autoFitRowHeights(sheet: SheetModel, workbook: WorkbookModel, ctx?: CanvasRenderingContext2D): void;

package/dist/core/layout/grid-metrics.d.ts

@@ -1,8 +1,17 @@
 import { SheetModel } from '../model/types';
+/** Excel/WPS 网格上限:行 1,048,576 / 列 16,384(虚拟外推封顶,防失控) */
+export declare const MAX_GRID_ROWS = 1048576;
+export declare const MAX_GRID_COLS = 16384;
 export declare class GridMetrics {
     private sheet;
     readonly cols: number;
     readonly rows: number;
+    /**
+     * 虚拟行/列上限(≥ dimension,≤ Excel 上限)。**仅**用于"滚动出空行"的 spacer 尺寸 /
+     * 可视区范围 / 命中夹取 / 表头;**不**改 totalWidth/Height(导出与 data-access 仍按 dimension)。
+     */
+    readonly vRows: number;
+    readonly vCols: number;
     /** 行表头(显示行号)宽度 px */
     readonly rowHeaderWidth: number;
     /** 列表头(显示列字母)高度 px */
@@ -13,7 +22,7 @@ export declare class GridMetrics {
     private rowHeights;
     /** 当前缩放比例(几何与字体同步按它缩放，保证缩放后排版一致) */
     readonly zoom: number;
-    constructor(sheet: SheetModel, zoom?: number);
+    constructor(sheet: SheetModel, zoom?: number, virtualRows?: number, virtualCols?: number);
     colWidth(c: number): number;
     rowHeight(r: number): number;
     private get dcw();
@@ -23,10 +32,13 @@ export declare class GridMetrics {
     rowTop(r: number): number;
     get totalWidth(): number;
     get totalHeight(): number;
+    /** 含虚拟外推的总宽/高(spacer 尺寸用;= totalWidth + 虚拟列外推) */
+    get virtualWidth(): number;
+    get virtualHeight(): number;
     /** 给定网格 x 坐标，返回所在列。超出数据范围按默认列宽外推。 */
     colAt(x: number): number;
     rowAt(y: number): number;
-    /** 数据单元格的可视区列区间(end 限制在数据范围内，避免画空 cell) */
+    /** 数据单元格的可视区列区间(end 夹到虚拟范围 vCols-1,允许滚动出空列;空格 paint 为 no-op) */
     visibleColRange(scrollX: number, viewW: number): [number, number];
     visibleRowRange(scrollY: number, viewH: number): [number, number];
     /** 网格线/表头的可视区列区间(可超出数据范围，铺满视口，模拟 Excel) */

package/dist/core/loader-json.d.ts

@@ -0,0 +1,23 @@
+import { WorkbookModel } from './model/types';
+export type JsonRow = unknown[] | Record<string, unknown>;
+export type JsonSheetInput = {
+    name?: string;
+    rows: JsonRow[];
+};
+export type JsonInput = unknown[][] | Record<string, unknown>[] | {
+    sheets: JsonSheetInput[];
+};
+export interface JsonLoadOptions {
+    /** 对象数组:首行写表头(键名);默认 true。`false` 直接从首行起当数据(用 columns 控制顺序) */
+    headerRow?: boolean;
+    /** 单表 / 默认表名,缺省 'Sheet1' */
+    sheetName?: string;
+    /** 主题色 17 色调色板;不给用全黑兜底 */
+    themeColors?: string[];
+    /** 数字串 → 数字、'TRUE'/'FALSE' → boolean、ISO 日期串 → Date(默认 true) */
+    autoInfer?: boolean;
+}
+/** JSON → WorkbookModel。input shape 自动识别。 */
+export declare function jsonToWorkbook(input: JsonInput, opts?: JsonLoadOptions): WorkbookModel;
+/** 用方传 WorkbookModel-shape 时的浅校验(壳分支用) */
+export declare function isWorkbookModel(v: unknown): v is WorkbookModel;

package/dist/core/model/clone.d.ts

@@ -1,9 +1,8 @@
 import { WorkbookModel } from './types';
-/** 深克隆整个工作簿(供 editable 时懒捕获 baseline)。 */
+/** 轻量深克隆整个工作簿(供 editable 懒捕获 baseline + 结构编辑 undo 快照)。 */
 export declare function cloneWorkbook(wb: WorkbookModel): WorkbookModel;
 /**
- * 把 baseline(snap)的内容就地还原进 live(不换 live / live.sheets / 各 sheet 的对象身份)。
- * 每次都对 snap 取一份新克隆,故 baseline 自身保持原始、可重复还原。
- * 约定:editing 期间不增删 sheet,故按 index 对齐;多出的 live sheet 不动。
+ * 把 baseline/快照(snap)的内容就地还原进 live(不换 live / live.sheets / 各 sheet 的对象身份)。
+ * 每次对 snap 取一份新轻量克隆,故 snap 自身保持可重复还原(redo / 多次 reset)。
  */
 export declare function restoreWorkbookInto(live: WorkbookModel, snap: WorkbookModel): void;

package/dist/core/model/inspect.d.ts

@@ -0,0 +1,43 @@
+import { CellStyleOverride, ImageAnchor, MergeRange, SheetModel, WorkbookModel } from './types';
+import { CellSnapshot } from './snapshot';
+export interface CellInspection extends CellSnapshot {
+    /** 该格所属合并区(锚点格 = 自身;被覆盖格 = 覆盖它的;否则 null) */
+    merge: MergeRange | null;
+    /** 是否合并区的左上锚点 */
+    isMergeAnchor: boolean;
+    /** 覆盖到该格的浮动图(按 sheet.images 索引 + 锚点克隆) */
+    floatingImages: Array<{
+        index: number;
+        anchor: ImageAnchor;
+    }>;
+    /** WPS 单元格内嵌图(DISPIMG) */
+    cellImage: {
+        id: string;
+        src: string;
+        mime?: string;
+    } | null;
+    /** 命中的数据验证范围(无则 null;详细规则字段当前模型未建模) */
+    dataValidation: MergeRange | null;
+    /** 命中的条件格式规则索引 + 该规则计算后的等效样式 */
+    conditional: Array<{
+        ruleIndex: number;
+        style: CellStyleOverride;
+    }>;
+    /** 直读 cell.hyperlink(便于不深入 cell 字段) */
+    hyperlink: string | null;
+    /** 直读 cell.comment */
+    comment: string | null;
+}
+/** 该格落在哪个合并区(锚点 / 被覆盖均算);否则 null */
+export declare function findMergeAt(sheet: SheetModel, row: number, col: number): MergeRange | null;
+/** 一张浮动图的锚点是否覆盖到 (row,col)。twoCellAnchor 用 from..to 矩形;oneCellAnchor 仅 from 格。 */
+export declare function imageAnchorContains(anchor: ImageAnchor, row: number, col: number): boolean;
+/**
+ * 聚合查询。
+ * @param sheet 工作表
+ * @param workbook 工作簿(用于 WPS 内嵌图登记表 cellImages)
+ * @param row 0-based
+ * @param col 0-based
+ * @param date1904 仅作 buildCellSnapshot 文本格式化用
+ */
+export declare function inspectCell(sheet: SheetModel, workbook: WorkbookModel, row: number, col: number, date1904: boolean): CellInspection;

package/dist/core/model/mutations.d.ts

@@ -1,4 +1,4 @@
-import { CellModel, CellStyle, CellStyleOverride, ColumnInfo, ImageAnchor, MergeRange, RowInfo, SheetModel } from './types';
+import { CellModel, CellStyle, CellStyleOverride, ColumnInfo, ImageAnchor, MergeRange, RowInfo, SheetModel, WorkbookModel } from './types';
 import { CellValue } from './data-access';
 /** 设单元格值。返回旧 CellModel(克隆,供 undo);新值为空则删除该格。 */
 export declare function setCellValue(sheet: SheetModel, row: number, col: number, value: CellValue): void;
@@ -23,6 +23,21 @@ export declare function cloneImageAnchor(a: ImageAnchor): ImageAnchor;
 export declare function addImage(sheet: SheetModel, anchor: ImageAnchor, index?: number): number;
 /** 删一张图(调用方负责为 undo 捕获前态)。 */
 export declare function removeImage(sheet: SheetModel, index: number): void;
+/**
+ * 浮动图 → WPS 单元格内嵌图(DISPIMG)。
+ * 取 sheet.images[imageIndex] 的字节登记到 wb.cellImages(新 id),目标格设 =DISPIMG 公式 + dispImgId,
+ * 移除该浮动图。返回新 id;图缺 bytes/mime 不可转 → 返 null(不动模型)。
+ */
+export declare function convertFloatToCellImage(wb: WorkbookModel, sheet: SheetModel, imageIndex: number, row: number, col: number): string | null;
+/**
+ * WPS 单元格内嵌图 → 浮动图。
+ * 取 (row,col) 的 dispImgId 对应登记图,造一张 oneCellAnchor 浮动图锚在该格(默认尺寸 sizePx),
+ * 清空该格。登记表里若无其它格再引用该 id,一并回收。返回浮动图索引;非内嵌图格返 -1。
+ */
+export declare function convertCellImageToFloat(wb: WorkbookModel, sheet: SheetModel, row: number, col: number, size?: {
+    width: number;
+    height: number;
+}): number;
 /**
  * 设图片的内容矩形(zoom 后像素,content 坐标)→ 规整为原点相对 oneCellAnchor。
  * 像素↔EMU:left_px = emuToPx(colOffEmu)*zoom ⇒ colOffEmu = pxToEmu(left/zoom)。不依赖列/行几何。

package/dist/core/model/types.d.ts

@@ -85,6 +85,12 @@ export interface CellModel {
     comment?: string;
     /** 样式索引，指向 SheetModel.styles */
     styleId: number;
+    /**
+     * WPS DISPIMG 单元格内嵌图的 id(指向 WorkbookModel.cellImages)。
+     * 有值时渲染器把图画进格内(随行高列宽缩放、随网格滚动裁剪),而非画 formula 文本。
+     * 由 cell-image-parser 从 `=DISPIMG("id",n)` 公式解析填充。
+     */
+    dispImgId?: string;
 }
 /** 合并区域(0-based，闭区间) */
 export interface MergeRange {
@@ -102,6 +108,12 @@ export interface RowInfo {
     /** 行高，单位 = px(已从 pt 换算) */
     height: number;
     hidden: boolean;
+    /**
+     * 是否"手动设定行高"(OOXML `<row customHeight="1">`)。
+     * true 时渲染层**不做自动行高**(与 Excel/WPS 一致:手动高度的行只裁切/溢出,不撑大)。
+     * 由 row-meta-parser 从原始 XML 读出(ExcelJS 不暴露此标记)。
+     */
+    customHeight?: boolean;
 }
 /** 冻结窗格: 冻结前 frozenRows 行 / frozenCols 列 */
 export interface FreezeInfo {
@@ -155,6 +167,19 @@ export interface AnchorCell {
     row: number;
     rowOffEmu: number;
 }
+/**
+ * WPS DISPIMG 单元格内嵌图(workbook 级登记表 xl/cellimages.xml 的一条)。
+ * 单元格通过 `=DISPIMG("id",n)` 公式按 id 引用;不同于浮动图(ImageAnchor),它"属于"单元格。
+ */
+export interface CellImage {
+    /** DISPIMG id(= cellimages.xml 里 cNvPr@name,如 "ID_5db4b3...") */
+    id: string;
+    /** 原始图片字节 + mime(解析层产出,可跨 Worker 传输) */
+    bytes?: Uint8Array;
+    mime?: string;
+    /** blob url(主线程 finalize 从 bytes 生成;解析阶段为空) */
+    src: string;
+}
 /** 图表规格(从 chartN.xml 抽出，交给 ECharts 映射) */
 export interface ChartSpec {
     type: 'bar' | 'line' | 'pie' | 'area' | 'scatter' | 'doughnut' | 'radar' | 'unsupported';
@@ -265,6 +290,11 @@ export interface WorkbookModel {
     /** 主题色调色板(theme1.xml 解析所得，索引同 ECMA dk1/lt1/dk2/lt2/accent1..6/hlink/folHlink) */
     themeColors: CssColor[];
     date1904: boolean;
+    /**
+     * WPS DISPIMG 单元格内嵌图登记表(id → 图)。对应 xl/cellimages.xml,workbook 级共享。
+     * 单元格 CellModel.dispImgId 指向此表;无 WPS 内嵌图时为 undefined。
+     */
+    cellImages?: Map<string, CellImage>;
 }
 export declare const cellKey: (row: number, col: number) => string;
 /** 数据钩子: 解析后、渲染前改模型(返回新模型或就地改) */
@@ -282,8 +312,20 @@ export interface CellStyleOverride {
     indent?: number;
     numFmt?: string;
 }
-/** 渲染钩子: 按单元格覆盖样式(返回部分样式,与解析样式合并) */
+/**
+ * 渲染钩子上下文 (Phase C, 2026-06-08).
+ * 给 `cellStyle` 钩子的第 3 入参, 让插件能感知该格当前是否可编辑 →
+ * 给只读格定制样式不再需要在 setup 里间接调 viewer.isCellEditable.
+ */
+export interface CellStyleCtx {
+    /** 该格此刻是否可编辑(综合 editable + editableTargets + readOnlyRanges + cellReadOnly) */
+    editable: boolean;
+}
+/**
+ * 渲染钩子: 按单元格覆盖样式(返回部分样式,与解析样式合并).
+ * Phase C 2026-06-08: 加可选第 3 入参 `ctx: CellStyleCtx`, 含 `editable`. 旧 `(cell, pos) => ...` 签名兼容.
+ */
 export type CellStyleFn = (cell: CellModel, pos: {
     row: number;
     col: number;
-}) => CellStyleOverride | void;
+}, ctx?: CellStyleCtx) => CellStyleOverride | void;