ooxml-excel-editor 1.1.0 → 1.2.0

package/dist/core/plugin.d.ts

@@ -1,7 +1,10 @@
 import { CellStyleFn, CellStyleOverride, ImageAnchor, MergeRange, TransformModelFn, WorkbookModel } from './model/types';
 import { CellValue, ReadOptions, SheetToJSONOptions } from './model/data-access';
 import { CellSnapshot } from './model/snapshot';
+import { CellInspection } from './model/inspect';
+import { MenuItem } from './edit/context-menu';
 import { EditorResolver } from './edit/editor-context';
+import { EditableTarget } from './edit/types';
 import { ViewerTheme } from './render/theme';
 import { ExcelSource } from './loader';
 import { ImageExportOptions, PdfExportOptions, PrintOptions } from './export/types';
@@ -12,7 +15,30 @@ export interface Rect {
     w: number;
     h: number;
 }
-export type PluginEvent = 'cell-click' | 'cell-dblclick' | 'selection-change' | 'sheet-change' | 'hyperlink-click' | 'cell-change' | 'edit-start' | 'edit-commit' | 'dim-change' | 'dirty-change' | 'image-change' | 'struct-change';
+export type PluginEvent = 'cell-click' | 'cell-dblclick' | 'selection-change' | 'sheet-change' | 'hyperlink-click' | 'cell-change' | 'edit-start' | 'edit-commit' | 'dim-change' | 'dirty-change' | 'image-change' | 'struct-change' | 'permission-denied';
+/**
+ * 权限拒绝事件 payload (Phase A, 2026-06-08):mutation 因 editable / editableTargets /
+ * readOnlyRanges / cellReadOnly 被阻挡时, 一次操作结束**统一**发一次. 默认行为仍是
+ * **静默跳过**(跟 editRange 一致), 此事件**只通知**消费方做 toast / 高亮, 不阻断流程.
+ *
+ * 一次操作只 emit 一次 (避免 N 张图 spam N 次).
+ */
+export interface PermissionDeniedPayload {
+    /** 触发的操作类型 */
+    reason: 'paste' | 'merge' | 'unmerge' | 'image-place' | 'image-convert' | 'dimension' | 'other';
+    /** 被拒的目标格 (粘贴 / 合并 / 图片转换 等场景下的具体位置;'dimension' 时可空) */
+    cells: Array<{
+        row: number;
+        col: number;
+    }>;
+    /** 'dimension' 场景下被拒的列 / 行 index 列表 */
+    dims?: {
+        axis: 'col' | 'row';
+        indices: number[];
+    };
+    /** 给消费方的可读说明 */
+    message?: string;
+}
 /** 命令式 API(组件 ref 与插件 ctx 共用) */
 export interface ViewerApi {
     load(src: ExcelSource): void;
@@ -24,8 +50,17 @@ export interface ViewerApi {
     rectOf(row: number, col: number): Rect | null;
     rectOfRange(range: MergeRange): Rect | null;
     redraw(): void;
-    /** 该格当前是否可编辑(综合 editable + readOnlyRanges + cellReadOnly) */
+    /** 该格当前是否可编辑(综合 editable + editableTargets 白名单 + readOnlyRanges + cellReadOnly) */
     isCellEditable(row: number, col: number): boolean;
+    /**
+     * **运行时**改可编辑白名单 (2026-06-08 新增). 接受 4 种 target 形状:
+     * `{row,col}` 单格 / `{row}` 整行 / `{col}` 整列 / `MergeRange` 矩形;单值或数组都支持,允许**不相邻**.
+     * 传 `undefined` = 关闭白名单(默认全可编辑);`[]` = 全只读;命中**任一** target → 可编辑.
+     * 立即生效, 不动 `:editableTargets` prop.
+     */
+    setEditableTargets(targets: EditableTarget | EditableTarget[] | undefined): void;
+    /** 当前生效的可编辑白名单. `undefined` 表示未启用白名单. */
+    getEditableTargets(): EditableTarget | EditableTarget[] | undefined;
     /** 导出当前/指定表为图片 Blob(默认 png) */
     exportImage(opts?: ImageExportOptions): Promise<Blob>;
     /** 导出为图片并触发下载 */
@@ -81,6 +116,8 @@ export interface ViewerApi {
     } | null;
     /** 查询任意格的完整快照(底层结构 + raw/computed/text/style) */
     getCellSnapshot(row: number, col: number): CellSnapshot | null;
+    /** 单元格"全息体检":snapshot + 合并区 + 浮动图覆盖 + WPS 内嵌图 + 数据验证 + 条件格式命中 + 链接/批注 */
+    inspectCell(row: number, col: number): CellInspection | null;
     /** 进入编辑(需有 editor 工厂 + 可编辑);返回是否进入 */
     beginEdit(row: number, col: number): boolean;
     /** 取消当前编辑(不改模型) */
@@ -89,6 +126,37 @@ export interface ViewerApi {
     isEditing(): boolean;
     /** 给区域套样式覆盖(E5;粗体/对齐/填充等);editable 时入命令栈(可撤销 + 发 cell-change + 记脏) */
     setStyle(range: MergeRange, patch: CellStyleOverride): boolean;
+    /** 活动格当前背景填充色(#RRGGBB;无填充→白) —— 工具栏色板回显用 */
+    getActiveFillColor(): string;
+    /** 活动格当前字体色(#RRGGBB;缺省黑) */
+    getActiveFontColor(): string;
+    /** 给当前选区设背景填充色(null=清除填充);editable 时入命令栈 */
+    setSelectionFill(color: string | null): boolean;
+    /** 给当前选区设字体色;editable 时入命令栈 */
+    setSelectionFontColor(color: string): boolean;
+    /** 当前选区里 wrapText 的整体态:'all' 全开 / 'none' 全关 / 'mixed' 混合(工具栏 active/右键勾选用) */
+    getSelectionWrapState(): 'all' | 'none' | 'mixed';
+    /** 切换当前选区的"自动换行"(WPS 风格 toggle);editable 时入命令栈,行高按内容重撑(只扩不缩) */
+    toggleWrapTextOnSelection(): boolean;
+    /** 合并区域(G1;清空被覆盖格,只留左上锚点);editable 时入命令栈 */
+    mergeCells(range: MergeRange): boolean;
+    /** 拆分区域内的合并(G1);editable 时入命令栈 */
+    unmergeCells(range: MergeRange): boolean;
+    /** 把 TSV 文本粘到选区左上角(G2;类型自动推断、跳过只读、入命令栈);at 缺省用活动格 */
+    pasteText(text: string, at?: {
+        row: number;
+        col: number;
+    }): boolean;
+    /** 解析 Excel/WPS 复制的剪贴板 HTML → 富粘贴(值+字体/颜色/填充/边框/对齐+合并+data-uri图),整体单次撤销 */
+    pasteRichHtml(html: string, at?: {
+        row: number;
+        col: number;
+    }): boolean;
+    /** 把一张图片 blob 落到活动格(转内嵌图);剪贴板单图 / 拖文件进网格用 */
+    pasteImageBlob(blob: Blob, at?: {
+        row: number;
+        col: number;
+    }): Promise<boolean>;
     /** 读当前表全部图片锚点(克隆;E6) */
     getImages(): ImageAnchor[];
     /** 加一张图(无 src 但有 bytes+mime 时自动生成 blob url);返回插入索引 */
@@ -99,6 +167,51 @@ export interface ViewerApi {
     moveImage(index: number, dxPx: number, dyPx: number): boolean;
     /** 缩放图片(目标屏幕像素宽高);editable 时入命令栈 + 发 image-change */
     resizeImage(index: number, widthPx: number, heightPx: number): boolean;
+    /** 活动格在公式栏里的可编辑字符串(公式→`=...`;数值→原始数字串;布尔→TRUE/FALSE;其余→显示文本) */
+    getCellEditString(): string;
+    /** 活动格此刻是否可经公式栏/命令式编辑(editable 开 + 该格非只读) */
+    canEditActiveCell(): boolean;
+    /** 经公式栏提交活动格的值(同 editCell 输入语义);move='down' 提交后活动格下移。返回是否提交 */
+    commitActiveCellValue(value: string, move?: 'down'): boolean;
+    /** 读 WPS 单元格内嵌图(DISPIMG)登记表(id→{id,src,mime});非 WPS 文件返空数组 */
+    getCellImages(): {
+        id: string;
+        src: string;
+        mime?: string;
+    }[];
+    /** 某格是否内嵌图 → {id,src,mime} 否则 null(供图片放大判定) */
+    getCellImageAt(row: number, col: number): {
+        id: string;
+        src: string;
+        mime?: string;
+    } | null;
+    /** 打开图片放大灯箱(命令式;src = blob/data/http url) */
+    openImageLightbox(src: string, fileName?: string, mime?: string): void;
+    /** 设 WPS 单元格内嵌图贴合方式(fill 拉伸铺满 / contain 等比留白 / cover 等比裁剪);即时重绘 */
+    setCellImageFit(fit: 'fill' | 'contain' | 'cover'): void;
+    /** 浮动图 → 单元格内嵌图(显式目标格);editable 时入命令栈 */
+    convertImageToCell(imageIndex: number, row: number, col: number): boolean;
+    /** 浮动图 → 内嵌图(**就近**:图在哪格就嵌哪格,几何反推目标);editable 时入命令栈 */
+    convertImageToCellAuto(imageIndex: number): boolean;
+    /** 批量把浮动图就近嵌入各自单元格(整表;`col` 给定则仅该列);一次进撤销栈,返回嵌入张数 */
+    convertAllImagesToCells(col?: number): number;
+    /** 选区批量:把中心落在 range 内的浮动图全部就近嵌入,单次撤销;返回嵌入张数。
+     *  壳侧 1.2.0 起返 `Promise<number>`(为接内置 ExportProgressOverlay;关闭 `:exportProgress` 也仍是 Promise) */
+    convertImagesInRangeToCell(range: MergeRange): Promise<number>;
+    /** 选区批量(反向):range 内所有 DISPIMG 格拎成浮动图,单次撤销;返回转换张数(壳侧返 Promise,见上) */
+    convertCellImagesInRangeToFloat(range: MergeRange, size?: {
+        width: number;
+        height: number;
+    }): Promise<number>;
+    /** 程序化打开右键菜单(Plan C;键盘 Shift+F10 / 工具栏触发等);items 不给则按当前选区算内置 */
+    openContextMenu(x: number, y: number, items?: MenuItem[]): void;
+    /** 关闭当前打开的右键菜单 */
+    closeContextMenu(): void;
+    /** 单元格内嵌图 → 浮动图(把 row,col 的 DISPIMG 拎成浮动图,默认 96×96px);editable 时入命令栈 */
+    convertCellImageToFloat(row: number, col: number, size?: {
+        width: number;
+        height: number;
+    }): boolean;
     /** 在 at 处插入 count 行(E7);editable 时入命令栈 + 发 struct-change */
     insertRows(at: number, count?: number): boolean;
     /** 删除 [at, at+count) 行(与合并相交则相交合并被移除) */
@@ -107,12 +220,29 @@ export interface ViewerApi {
     insertCols(at: number, count?: number): boolean;
     /** 删除 [at, at+count) 列 */
     deleteCols(at: number, count?: number): boolean;
-    /** 程序化设列宽(px,模型单位);editable 时入命令栈(可撤销 + 发 dim-change + 记脏) */
-    setColumnWidth(col: number, width: number): boolean;
-    /** 程序化设行高(px,模型单位);editable 时入命令栈 */
-    setRowHeight(row: number, height: number): boolean;
+    /**
+     * 程序化设列宽 (px, 模型单位). Phase B 2026-06-08:
+     * target 接 `number | number[] | {from,to}` (DimTarget). 多 index 时聚合成单次 undo.
+     * 返回**成功条数** (0 = 全 skip / editable=false). 老 `setColumnWidth(5, 100)` 单值用法兼容.
+     */
+    setColumnWidth(target: import('./edit/types').DimTarget, width: number): number;
+    /** 程序化设行高. 同 setColumnWidth, 维度 = 'row'. */
+    setRowHeight(target: import('./edit/types').DimTarget, height: number): number;
+    /** 批量 autoFit 列宽 (Phase B). target 不传 = 整表; 传 DimTarget = 选定列. 返成功条数. */
+    autoFitColumns(target?: import('./edit/types').DimTarget): number;
+    /** 批量 autoFit 行高 (Phase B). 同上, 维度 = 'row'. */
+    autoFitRows(target?: import('./edit/types').DimTarget): number;
+    /** 重置列宽到默认 (Phase B) — 移除 columns Map 条目, 回落 defaultColWidth. 返成功条数. */
+    resetColumnWidth(target: import('./edit/types').DimTarget): number;
+    /** 重置行高到默认. 同上, 维度 = 'row'. */
+    resetRowHeight(target: import('./edit/types').DimTarget): number;
     /** 公式引擎是否已就绪(recalc 开启 + 异步 warm 完成);未开重算恒 false */
     isRecalcReady(): boolean;
+    /** 当前虚拟范围(滚动出空行/列的外推上限,含 dimension 兜底);不动 dimension/文件 */
+    getVirtualExtent(): {
+        rows: number;
+        cols: number;
+    };
     /** 当前是否有未保存修改(自加载/还原以来发生过编辑或 resize) */
     isDirty(): boolean;
     /** 放弃全部修改,还原到刚加载的原件;返回是否还原 */
@@ -173,8 +303,16 @@ export interface ExcelPlugin {
     overlay?: (ctx: OverlayContext) => OverlayNode;
     /** 按格自定义编辑控件(返回工厂;多插件数组序首个非空胜,组件 editor prop 覆盖);需 editable 开启。 */
     editor?: EditorResolver;
+    /** 右键菜单 transform(Plan C):`(ctx, items) => items[]`,多插件按数组顺序串行,组件 :contextMenu prop 最后覆盖 */
+    contextMenu?: import('./viewer/controller').ContextMenuTransform;
     /** 高级: 拿命令式 API、订阅事件;返回可选清理函数 */
     setup?: (ctx: ExcelPluginContext) => void | (() => void);
 }
 /** 定义插件(仅作类型推断,原样返回) */
 export declare function definePlugin(plugin: ExcelPlugin): ExcelPlugin;
+export { jsonToWorkbook, isWorkbookModel, type JsonInput, type JsonLoadOptions, type JsonRow, type JsonSheetInput } from './loader-json';
+export { applyStyleTemplate } from './template/style-overlay';
+export type { CellInspection } from './model/inspect';
+export type { EditableTarget, EditConfig } from './edit/types';
+export type { MenuItem } from './edit/context-menu';
+export type { ContextMenuCtx, ContextMenuTransform, ContextMenuBeforePayload, ContextMenuShowPayload, } from './viewer/controller';

package/dist/core/progress.d.ts

@@ -5,3 +5,26 @@ export interface ParseProgress {
     ratio?: number;
 }
 export type ProgressFn = (p: ParseProgress) => void;
+/**
+ * 导出 / 批量转换进度。所有耗时操作(PDF / PNG / XLSX / 批量浮动↔嵌入)统一报这套。
+ * stage 语义:
+ *  - 'render':canvas 渲染一张表(大表分块时按 ratio 报子进度)
+ *  - 'compose':多表合成一张大图 / 合并几何
+ *  - 'paginate':PDF 分页 / 每页布局
+ *  - 'write':PDF / 图片 blob 编码写出
+ *  - 'zip':XLSX zip 压缩(exceljs 黑盒,只前/后两次)
+ *  - 'convert':批量图片浮动↔嵌入(P2)
+ */
+export type ExportStage = 'render' | 'compose' | 'paginate' | 'write' | 'zip' | 'convert';
+export interface ExportProgress {
+    stage: ExportStage;
+    /** 当前正在处理的表(可选) */
+    sheetIndex?: number;
+    /** PDF 分页阶段:当前页 */
+    pageIndex?: number;
+    /** 0..1;黑盒阶段省略 */
+    ratio?: number;
+    /** 给 UI 显示的标签(可选,如"渲染 Sheet1 (3/5)") */
+    label?: string;
+}
+export type ExportProgressFn = (p: ExportProgress) => void;

package/dist/core/render/canvas-renderer.d.ts

@@ -1,10 +1,37 @@
-import { CellStyle, CellStyleFn, MergeRange, SheetModel, WorkbookModel } from '../model/types';
+import { CellStyle, CellStyleFn, CellStyleOverride, MergeRange, SheetModel, WorkbookModel } from '../model/types';
 import { ViewerTheme } from './theme';
 import { GridMetrics } from '../layout/grid-metrics';
 import { FreezeGeometry } from '../layout/freeze';
+/**
+ * WPS 单元格内嵌图(DISPIMG)在格内的贴合方式:
+ * - `contain`(默认,与 WPS 渲染一致):等比缩放完整显示,周围留白(不裁剪、不变形)。
+ *   WPS 打开导出文件时 DISPIMG 固定按 contain 渲染,故默认 contain 让预览所见即所得。
+ * - `fill`:拉伸铺满整格,随宽高变形(预览铺满,但导出后 WPS 仍按 contain 显示,二者不一致);
+ * - `cover`:等比放大铺满,超出部分裁掉(不变形、不留白)。
+ */
+export type CellImageFit = 'fill' | 'contain' | 'cover';
 export interface RendererOptions {
     theme?: Partial<ViewerTheme>;
     cellStyle?: CellStyleFn;
+    /** 异步内容(WPS 单元格内嵌图)解码完成后请求重绘;壳/控制器接到 scheduleRender */
+    onNeedsRedraw?: () => void;
+    /** WPS 单元格内嵌图贴合方式(默认 contain,与 WPS 渲染一致) */
+    cellImageFit?: CellImageFit;
+    /**
+     * 只读单元格视觉钩子 (Phase C, 2026-06-08):
+     *   - false (默认) = 无视觉差异 (老行为不变)
+     *   - true = 套内置默认 (灰底 #f5f7fa)
+     *   - CellStyleOverride 对象 = 固定样式给所有只读格
+     *   - CellStyleFn 函数 = 按格自定义
+     * 仅在 cellStyle 钩子之后, 该格 editable=false 时套用.
+     */
+    readOnlyCellStyle?: boolean | CellStyleOverride | CellStyleFn;
+    /**
+     * 查询某格是否可编辑 (Phase C, 2026-06-08):
+     * 让渲染器把 ctx.editable 喂给 cellStyle 钩子 + 决定是否套 readOnlyCellStyle.
+     * controller 注入, 默认 () => true (不知道权限 → 当全可编辑, 老行为不变).
+     */
+    isEditable?: (row: number, col: number) => boolean;
 }
 /** 导出为离屏 canvas 的选项 */
 export interface ExportToCanvasOptions {
@@ -84,10 +111,28 @@ export declare class CanvasRenderer {
     private sparklineIndex;
     private theme;
     private cellStyleHook?;
+    private onNeedsRedraw?;
+    private cellImageFit;
+    /** Phase C 2026-06-08: 只读视觉钩子, 渲染时按格套用 */
+    private readOnlyStyleHook?;
+    /** Phase C 2026-06-08: 查询该格是否可编辑 (controller 注入). 默认全可编辑 (老行为) */
+    private isEditableFn;
+    /** 虚拟外推行/列数(滚动出空行用;0 = 仅按 dimension)。透传给 GridMetrics,不影响导出。 */
+    private virtualRows;
+    private virtualCols;
+    /** WPS 单元格内嵌图解码缓存: blob src → 已加载的 HTMLImageElement(complete 才画) */
+    private cellImageCache;
     constructor(canvas: HTMLCanvasElement, sheet: SheetModel, workbook: WorkbookModel, zoom?: number, opts?: RendererOptions);
+    /** 改 WPS 单元格内嵌图贴合方式(fill/contain/cover);返回是否有变化(变了需重绘)。 */
+    setCellImageFit(fit: CellImageFit): boolean;
     /** 改变缩放: 重建几何(列宽行高表头按 zoom 缩放)。合并/条件格式无需重建。 */
     setZoom(zoom: number): void;
-    /** 内容总尺寸(含表头)，给外层滚动容器用 */
+    /**
+     * 设虚拟外推行/列数(滚动出空行/空列);仅当变化时重建 GridMetrics,返回是否变了(变了需重绘 + 刷 spacer)。
+     * 不影响 dimension / 导出 / data-access。
+     */
+    setVirtualExtent(rows: number, cols: number): boolean;
+    /** 内容总尺寸(含表头)，给外层滚动容器用(用虚拟范围 → 可滚动出空行/列) */
     get contentWidth(): number;
     get contentHeight(): number;
     get freezeGeometry(): FreezeGeometry;
@@ -202,6 +247,15 @@ export declare class CanvasRenderer {
     private borderEdgeOf;
     /** 画单个 cell(或合并区)的: 填充 → 条件背景 → 数据条 → 边框 → 内容 → 图标 → 筛选按钮 */
     private paintCellBox;
+    /**
+     * 把 WPS 单元格内嵌图(DISPIMG)画进格内,贴合方式由 `cellImageFit` 决定(fill/contain/cover);
+     * 始终裁剪到格内、随行高列宽变化。未解码完成/缺图时画淡占位。
+     */
+    private drawCellImage;
+    /** 取/起一张内嵌图的解码;未缓存则起加载,onload 请求重绘(无 DOM 环境返 null) */
+    private getCellImageEl;
+    /** 缺图提示(仅画淡图标,**不盖底色** — 让单元格自身填充色透出来) */
+    private drawImagePlaceholder;
     private drawCellContent;
     /**
      * 文本溢出可用的裁剪范围: 从本格向对齐方向延伸，吞掉相邻"空白"格(无值且无填充)。

package/dist/core/render/conditional.d.ts

@@ -21,5 +21,12 @@ export declare class ConditionalEngine {
     hasRules(): boolean;
     private numericValuesIn;
     private prepare;
+    /** 返回所有命中该格的规则索引 + 各自计算出的 effect(供 Cell Inspector 查询;不做"第一条赢"短路) */
+    inspectHits(row: number, col: number, value: number | string | boolean | Date | null): Array<{
+        ruleIndex: number;
+        effect: CellEffect;
+    }>;
+    /** 单条规则在某格上的 effect(命中返 patch,不命中返 null);effectsFor 与 inspectHits 共用 */
+    private evalRule;
     effectsFor(row: number, col: number, value: number | string | boolean | Date | null): CellEffect | null;
 }

package/dist/core/template/style-overlay.d.ts

@@ -0,0 +1,9 @@
+import { WorkbookModel } from '../model/types';
+/**
+ * 把模板的样式套到数据 workbook 上,产出新 workbook(不修改入参).
+ *
+ * @param dataWb     数据源(JSON / CSV 加载得到的 WorkbookModel),raw 值的来源
+ * @param templateWb 模板源(.xlsx 解析得到的 WorkbookModel),styling 的来源
+ * @returns 合成 workbook —— 用模板的 sheet 形态 + 数据的 raw 内容
+ */
+export declare function applyStyleTemplate(dataWb: WorkbookModel, templateWb: WorkbookModel): WorkbookModel;

package/dist/core/viewer/controller.d.ts

@@ -3,8 +3,10 @@ import { EditConfig } from '../edit/types';
 import { EditController, EditEventName } from '../edit/edit-controller';
 import { CellValue, SheetToJSONOptions } from '../model/data-access';
 import { CellSnapshot } from '../model/snapshot';
+import { CellInspection } from '../model/inspect';
+import { MenuItem } from '../edit/context-menu';
 import { EditorCommitValue, EditorResolver } from '../edit/editor-context';
-import { CanvasRenderer, RendererOptions, ViewState } from '../render/canvas-renderer';
+import { CanvasRenderer, CellImageFit, RendererOptions, ViewState } from '../render/canvas-renderer';
 import { OverlayQuads } from './overlay-manager';
 import { ImageExportOptions, PdfExportOptions, PrintOptions } from '../export/types';
 import { XlsxExportOptions } from '../export/xlsx-writer';
@@ -70,6 +72,33 @@ export interface ViewerControllerHooks {
     onFilterChange: () => void;
     /** 编辑事件(cell-change/edit-start/edit-commit;壳转 emit + 插件派发) */
     onEditEvent: (event: EditEventName, payload: unknown) => void;
+    /** 右键菜单触发前(Plan C):用户可调 `preventDefault()` 阻止内置菜单弹出(然后自渲染) */
+    onContextMenuBefore?: (payload: ContextMenuBeforePayload) => void;
+    /** 右键菜单"展示"通知(Plan C):无论内置是否弹都触发,供壳自渲染或事件流串到业务 */
+    onContextMenuShow?: (payload: ContextMenuShowPayload) => void;
+}
+/** 右键菜单上下文(单格/选区 + 活动格 + 当前表/簿 + editable 闸门态) */
+export interface ContextMenuCtx {
+    range: MergeRange;
+    single: boolean;
+    activeCell: Cell;
+    sheet: SheetModel;
+    workbook: WorkbookModel;
+    editable: boolean;
+}
+/** 用户 transform:在内置 items 上做加 / 减 / 重排;返新数组生效,返 undefined 用原样 */
+export type ContextMenuTransform = (ctx: ContextMenuCtx, items: MenuItem[]) => MenuItem[] | undefined | void;
+export interface ContextMenuBeforePayload {
+    event: MouseEvent;
+    ctx: ContextMenuCtx;
+    items: MenuItem[];
+    preventDefault: () => void;
+}
+export interface ContextMenuShowPayload {
+    x: number;
+    y: number;
+    ctx: ContextMenuCtx;
+    items: MenuItem[];
 }
 export declare class ViewerController {
     private els;
@@ -83,11 +112,20 @@ export declare class ViewerController {
     private rafId;
     private contentW;
     private contentH;
+    /** 虚拟外推行/列数(滚动出空行/空列;只增不减,封顶 Excel 上限)。不动 dimension/文件。 */
+    private virtualRows;
+    private virtualCols;
     private workbook;
     private activeIndex;
     private rendererOpts;
     /** 下载默认文件名(壳可随 props 更新) */
     fileName: string | undefined;
+    /** 右键上下文菜单宿主(G3;body 级 DOM,框架无关) */
+    private menuHost;
+    private lightbox;
+    private lightboxEnabled;
+    /** 用户的右键菜单 transform 回调(Plan C):`(ctx, items) => MenuItem[] | undefined` */
+    private ctxMenuTransform;
     /** 原始 .xlsx 字节(壳加载时注入;供高保真 overlay 导出重载原件) */
     private sourceBuffer;
     /** 壳在加载后注入原始字节(供 exportXlsx({fidelity:'overlay'}) 重载原件叠加编辑) */
@@ -107,6 +145,7 @@ export declare class ViewerController {
     private resizeStartInfo;
     private resizeStartModelSize;
     private dragMoved;
+    private dragStartXY;
     private findQuery;
     private findMatchCase;
     private findWholeCell;
@@ -145,10 +184,30 @@ export declare class ViewerController {
     autoFitColumn(col: number): void;
     /** 双击行边界: 自适应行高(editable 时入命令栈/发事件/记脏) */
     autoFitRow(row: number): void;
-    /** 程序化设列宽(px,模型单位/非缩放);editable 时走命令栈(可撤销+发 dim-change+记脏)。 */
-    setColumnWidth(col: number, width: number): boolean;
-    /** 程序化设行高(px,模型单位/非缩放);editable 时走命令栈。 */
-    setRowHeight(row: number, height: number): boolean;
+    /**
+     * 程序化设列宽 (px, 模型单位/非缩放). Phase B 2026-06-08:
+     * target 接 `number | number[] | {from,to}` (DimTarget). 多 index 时聚合成单次 undo.
+     * editable 时走命令栈;strictDimensions=true 时该列至少 1 格在白名单内才生效.
+     * 返回**成功条数** (0 = 全部 skip / editable=false).
+     */
+    setColumnWidth(target: import('../edit/types').DimTarget, width: number): number;
+    /** 程序化设行高 (px, 模型单位/非缩放). 同 setColumnWidth, 维度 = 'row'. */
+    setRowHeight(target: import('../edit/types').DimTarget, height: number): number;
+    /**
+     * 批量 autoFit 列宽 (Phase B 2026-06-08). target 不传 = 整表; 传 DimTarget = 选定列.
+     * 单 index 走 autoFitColumn (含 resize-record); 多 index 单次 restore-wb undo + 循环 autofit.
+     * 返回成功条数.
+     */
+    autoFitColumns(target?: import('../edit/types').DimTarget): number;
+    /** 批量 autoFit 行高 (Phase B 2026-06-08). 同 autoFitColumns, 维度 = 'row'. */
+    autoFitRows(target?: import('../edit/types').DimTarget): number;
+    /**
+     * 重置列宽到默认 (Phase B 2026-06-08) — 移除 sheet.columns Map 条目, 回落到 defaultColWidth.
+     * 多 index 单次 undo. 返回成功条数.
+     */
+    resetColumnWidth(target: import('../edit/types').DimTarget): number;
+    /** 重置行高到默认. 同 resetColumnWidth, 维度 = 'row'. */
+    resetRowHeight(target: import('../edit/types').DimTarget): number;
     /** 公式引擎是否已就绪(recalc 开启 + 异步 warm 完成);未开重算恒 false。 */
     isRecalcReady(): boolean;
     /** 当前是否有未保存修改(自加载/还原以来发生过编辑或 resize)。 */
@@ -172,10 +231,34 @@ export declare class ViewerController {
     dispose(): void;
     /** 内容总尺寸变化 → 量 + 直接撑 spacer(滚动范围由它决定) */
     refreshContentSize(): void;
+    /**
+     * 据当前滚动+视口算"虚拟范围"(滚到数据下方仍有空行/空列可滚动/选中/编辑)。
+     * 只增不减(防 spacer 抖动)、封顶 Excel 上限。**不动 dimension/文件**;编辑虚拟格才靠 growDimension 变实。
+     * 仅当范围真变化时重建 GridMetrics + 刷 spacer。
+     */
+    recomputeVirtualExtent(): void;
+    /** 当前虚拟范围(含 dimension 兜底);供调试/e2e。 */
+    getVirtualExtent(): {
+        rows: number;
+        cols: number;
+    };
     /** 当前选区(随 mode 解析为单元格/整行/整列范围,含合并单元格扩展) */
     getSelection(): MergeRange | null;
     /** 活动单元格(选区的"焦点"角) */
     getActiveCell(): Cell | null;
+    /**
+     * 活动格(或指定格)在公式栏里**可编辑的字符串**:
+     * 公式 → `=...`;数值 → 原始数字串(非格式化,避免编辑货币/千分位被当文本);布尔 → TRUE/FALSE;
+     * 日期/字符串/富文本 → 显示文本。空格返 ''。供公式栏 / 命令式取活动格编辑值。
+     */
+    getCellEditString(row?: number, col?: number): string;
+    /** 活动格此刻是否可经公式栏/命令式编辑(editable 开 + 该格非只读) */
+    canEditActiveCell(): boolean;
+    /**
+     * 经公式栏提交活动格的值(value 同 editCell 的输入语义:`=`→公式、数字串→数字…)。
+     * 仅在 editable + 该格可编辑时生效;move='down' 时提交后活动格下移(像 Excel 回车)。返回是否提交。
+     */
+    commitActiveCellValue(value: string, move?: 'down'): boolean;
     /** 清空选区 */
     clearSelection(): void;
     /** 全选 */
@@ -201,12 +284,59 @@ export declare class ViewerController {
     /** 拖拽结束:模型已被 renderer 改完,补登一条 undo 项 + 发 dim-change。 */
     private endResizeRecord;
     onMouseLeave(): void;
+    /** 右键上下文菜单(G3;仅 editable;只读用浏览器默认菜单)。壳把 contextmenu 事件转给它。 */
+    /**
+     * 右键事件入口(Plan C 全面开放):
+     *  1. 算 ctx(选区 + 单/多格 + 活动格);右键不在当前选区 → 先选中(仿 Excel)
+     *  2. 算内置 items(`buildBuiltinContextMenuItems`,editable 时才有,否则空)
+     *  3. 跑用户 `setContextMenuTransform` 回调(可加/减/重排)
+     *  4. 触发 `onContextMenuBefore` 钩子(可 preventDefault)
+     *  5. 没被 prevent + items 非空 → 弹内置浮层;无论是否弹,都触发 `onContextMenuShow`(让用户也能自渲染)
+     */
+    onContextMenu(e: MouseEvent): void;
+    /** 算右键 ctx:命中格 + 选区调整;非内容区 / 无 renderer 返 null */
+    private buildContextMenuCtx;
+    /** 编辑模式下的内置菜单项(独立提取,便于 transform 回调拿到再二次加工) */
+    buildBuiltinContextMenuItems(ctx: ContextMenuCtx): MenuItem[];
+    /** 设置用户 transform 回调(`(ctx, items) => MenuItem[] | undefined`);壳侧调用 */
+    setContextMenuTransform(fn: ContextMenuTransform | null | undefined): void;
+    /** 程序化打开菜单(键盘 Shift+F10 / 自定义触发);items 不给则按当前选区算内置 */
+    openContextMenu(x: number, y: number, items?: MenuItem[]): void;
+    /** 关闭当前菜单(无打开则 no-op) */
+    closeContextMenu(): void;
     private updateHover;
     onDblClick(e: MouseEvent): void;
     private pageRows;
     onKeyDown(e: KeyboardEvent): void;
     private scrollActiveIntoView;
     copySelection(): Promise<void>;
+    /**
+     * 从系统剪贴板粘贴。优先 `clipboard.read()` 拿 **text/html**(Excel/WPS 复制 → 富粘贴:值+字体+颜色+
+     * 填充+边框+合并),否则单张图片 → 落格,再否则回退 **text/plain** TSV(`pasteText`)。需读权限/安全上下文,
+     * 受限时回退 readText;都失败返 false。
+     */
+    pasteFromClipboard(): Promise<boolean>;
+    /**
+     * 解析 Excel/WPS 复制的剪贴板 HTML(text/html)→ 富粘贴:值 + 字体/颜色/填充/边框/对齐 + 合并 + data-uri 图,
+     * **整体单次撤销**。无 `<table>` 返 false(调用方回退 TSV)。at 缺省用活动格。
+     */
+    pasteRichHtml(html: string, at?: {
+        row: number;
+        col: number;
+    }): boolean;
+    /** 把一张图片 blob 落到活动格(转内嵌图);剪贴板单图粘贴 / 拖文件进网格用。 */
+    pasteImageBlob(blob: Blob, at?: {
+        row: number;
+        col: number;
+    }): Promise<boolean>;
+    /**
+     * 把 TSV(Excel/表格复制的制表符分隔文本)粘到选区左上角(无 at 时用活动格)。
+     * 值类型自动推断(纯数字串→数字、`=`→公式)、跳过只读格;入命令栈可撤销。返回是否有改动。
+     */
+    pasteText(text: string, at?: {
+        row: number;
+        col: number;
+    }): boolean;
     /** 查找状态快照(壳渲染 FindBar) */
     getFindState(): FindState;
     setFindQuery(q: string): void;
@@ -260,13 +390,39 @@ export declare class ViewerController {
     sortColumn(col: number, dir: 'asc' | 'desc'): void;
     /** 设置编辑配置(默认只读;壳在挂载 + props 变化时调) */
     setEditConfig(cfg: EditConfig): void;
-    /** 该格当前是否可编辑(综合 editable + readOnlyRanges + cellReadOnly) */
+    /** 该格当前是否可编辑(综合 editable + editableTargets 白名单 + readOnlyRanges + cellReadOnly) */
     isCellEditable(row: number, col: number): boolean;
+    /**
+     * **运行时**改可编辑白名单(2026-06-08 新增) —— 不动 `:editableTargets` prop,
+     * 直接覆盖 `editCfg.editableTargets`. 立即重绘以反映只读光标变化.
+     * 传 `undefined` = 关闭白名单(默认全可编辑);`[]` = 全只读;单值或数组 = 白名单.
+     */
+    setEditableTargets(targets: EditConfig['editableTargets']): void;
+    /** 当前生效的可编辑白名单(运行时 setEditableTargets 或初始 prop). 用 `undefined` 表示未启用白名单 */
+    getEditableTargets(): EditConfig['editableTargets'];
     editCell(row: number, col: number, value: CellValue): boolean;
     editRange(range: MergeRange, values: CellValue[][]): boolean;
     clearRange(range: MergeRange): boolean;
     /** 给区域套样式覆盖(E5;粗体/对齐/填充等);editable 时走命令栈(可撤销 + 发 cell-change + 记脏) */
     setStyle(range: MergeRange, patch: CellStyleOverride): boolean;
+    /** 活动格当前背景填充色(#RRGGBB);无填充/非纯色 → 默认白 #FFFFFF。 */
+    getActiveFillColor(): string;
+    /** 活动格当前字体色(#RRGGBB);缺省黑 #000000。 */
+    getActiveFontColor(): string;
+    /** 给当前选区设背景填充色(null = 清除填充);editable 时入命令栈。 */
+    setSelectionFill(color: string | null): boolean;
+    /** 给当前选区设字体色;editable 时入命令栈。 */
+    setSelectionFontColor(color: string): boolean;
+    /** 当前选区里 wrapText 的整体态:'all' 全开 / 'none' 全关 / 'mixed' 混合。空选区→'none'。 */
+    getSelectionWrapState(): 'all' | 'none' | 'mixed';
+    /** 切换当前选区的"自动换行"(WPS 风格):全 wrap → 全关;否则 → 全开。
+     *  失效行高缓存让 autofit 按新 wrap 重撑(只扩不缩);editable 时入命令栈(单次撤销 style)。
+     *  注:undo 回滚 style 但不回滚行高,与现有 setStyle/autofit "只扩不缩"语义一致。 */
+    toggleWrapTextOnSelection(): boolean;
+    /** 合并区域(G1;清空被覆盖格,只留左上锚点);editable 时入命令栈 */
+    mergeCells(range: MergeRange): boolean;
+    /** 拆分区域内的合并(G1);editable 时入命令栈 */
+    unmergeCells(range: MergeRange): boolean;
     /** 读当前表全部图片锚点(克隆)。 */
     getImages(): ImageAnchor[];
     /** 加一张图(无 src 但有 bytes+mime 时自动生成 blob url);返回插入索引(失败 -1)。 */
@@ -277,6 +433,50 @@ export declare class ViewerController {
     moveImage(index: number, dxPx: number, dyPx: number): boolean;
     /** 缩放图片(目标屏幕像素宽高);editable 时入命令栈 + 发 image-change。 */
     resizeImage(index: number, widthPx: number, heightPx: number): boolean;
+    /** 改 WPS 单元格内嵌图贴合方式(fill/contain/cover);即时重绘。 */
+    setCellImageFit(fit: CellImageFit): void;
+    /** 读 WPS 单元格内嵌图登记表(克隆,id→{id,src,mime});无则空数组。 */
+    getCellImages(): {
+        id: string;
+        src: string;
+        mime?: string;
+    }[];
+    /** 某格是否内嵌图(DISPIMG)→ 返 {id,src,mime},否则 null(供点击放大判定)。 */
+    getCellImageAt(row: number, col: number): {
+        id: string;
+        src: string;
+        mime?: string;
+    } | null;
+    /** 开/关图片点击放大灯箱(默认开;只读模式单击图、编辑模式右键菜单触发)。 */
+    setLightboxEnabled(b: boolean): void;
+    /** 打开图片放大灯箱(命令式;src = blob/data/http url)。 */
+    openImageLightbox(src: string, fileName?: string, mime?: string): void;
+    /** 一张浮动图视觉中心落在哪个单元格(用几何反推;无渲染器时回落锚点 from 格)。 */
+    imageCellOf(index: number): {
+        row: number;
+        col: number;
+    } | null;
+    /** 浮动图 → 单元格内嵌图(显式指定目标格);失败返 false。 */
+    convertImageToCell(imageIndex: number, row: number, col: number): boolean;
+    /** 选区批量:把"中心格落在 range 内"的所有浮动图就近嵌入,聚合成单次 undo;返回成功嵌入张数。 */
+    convertImagesInRangeToCell(range: MergeRange): number;
+    /** 选区批量:把 range 内所有 DISPIMG 格拎成浮动图;聚合成单次 undo;返回成功转换张数。 */
+    convertCellImagesInRangeToFloat(range: MergeRange, size?: {
+        width: number;
+        height: number;
+    }): number;
+    /** 浮动图 → 内嵌图(**就近**:图在哪格就嵌哪格,目标由几何反推);失败返 false。 */
+    convertImageToCellAuto(imageIndex: number): boolean;
+    /**
+     * 批量把浮动图按"所在单元格"就近嵌入(整表 / 整列)。`col` 给定则只嵌中心落在该列的图。
+     * 一次进撤销栈(单次 Ctrl+Z 全撤)。返回成功嵌入的张数。
+     */
+    convertAllImagesToCells(col?: number): number;
+    /** 单元格内嵌图 → 浮动图(把 row,col 的 DISPIMG 拎成浮动图);非内嵌图格返 false。 */
+    convertCellImageToFloat(row: number, col: number, size?: {
+        width: number;
+        height: number;
+    }): boolean;
     /** 在 at 处插入 count 行(原 at 行及之后下移)。 */
     insertRows(at: number, count?: number): boolean;
     /** 删除 [at, at+count) 行(与合并相交则警告,相交合并被移除)。 */
@@ -296,6 +496,9 @@ export declare class ViewerController {
         col: number;
     } | null;
     getCellSnapshot(row: number, col: number): CellSnapshot | null;
+    /** 单元格"全息体检":snapshot + 合并区 + 浮动图覆盖 + WPS 内嵌图 + 数据验证 + 条件格式命中 + 链接/批注。
+     *  无 workbook / sheet / 越界返 null。详见 [src/core/model/inspect.ts](src/core/model/inspect.ts)。 */
+    inspectCell(row: number, col: number): CellInspection | null;
     /** 壳注入合并后的编辑器解析器(plugin.editor + prop.editor) */
     setEditorResolver(fn?: EditorResolver): void;
     /**