@taocompany/magic-grid 0.2.0 → 0.3.0

package/dist/types/core.d.ts

@@ -0,0 +1,3038 @@
+import { Ref } from 'vue';
+import { Rule } from 'async-validator';
+
+export declare interface AddRowItem {
+    /** 行数据；新增临时行时 rowKey 字段应省略或为 null */
+    data: RowData;
+}
+
+/** 带插入位置的新增行 payload（applyTransaction / addRows 共用） */
+export declare interface AddRowPayload {
+    data: RowData;
+    index?: number;
+    indexMode?: RowIndexMode;
+}
+
+export declare interface AddRowsOptions {
+    rows: AddRowItem[];
+    /** 插入起始下标；省略 = 末尾 */
+    index?: number;
+    /** 下标基准，默认 'source' */
+    indexMode?: RowIndexMode;
+}
+
+export declare interface AsyncRowMutationAddParams {
+    rows: ReadonlyArray<{
+        data: RowData;
+    }>;
+    index?: number;
+    indexMode?: RowIndexMode;
+    signal: AbortSignal;
+}
+
+export declare interface AsyncRowMutationAddResult {
+    rows?: ReadonlyArray<AsyncRowMutationAddResultRow | void>;
+}
+
+export declare interface AsyncRowMutationAddResultRow {
+    /** 写入 data[rowKey]；提供则创建持久化行（非 transient） */
+    businessId?: string | number;
+    /** 合并进 data（如服务端 enrich 字段） */
+    data?: RowData;
+}
+
+/** 异步行变更持久化钩子（GridOptions.asyncRowMutation） */
+export declare interface AsyncRowMutationHandlers {
+    /** 新增：await 服务端成功后 apply 本地；reject 则不写入 */
+    add?: (params: AsyncRowMutationAddParams) => Promise<AsyncRowMutationAddResult | void>;
+    /** 更新：await 服务端成功后 apply 本地；reject 则不写入 */
+    update?: (params: AsyncRowMutationUpdateParams) => Promise<void>;
+    /** 删除：await 服务端成功后 apply 本地；reject 则不删除 */
+    remove?: (params: AsyncRowMutationRemoveParams) => Promise<void>;
+}
+
+export declare interface AsyncRowMutationRemoveParams {
+    rowIds: readonly string[];
+    rows: ReadonlyArray<{
+        rowId: string;
+        data: RowData;
+    }>;
+    signal: AbortSignal;
+}
+
+export declare interface AsyncRowMutationUpdateParams {
+    rows: ReadonlyArray<{
+        rowId: string;
+        data: RowData;
+    }>;
+    signal: AbortSignal;
+}
+
+export declare type AutoSizeStrategy = SizeColumnsToFitGridStrategy | SizeColumnsToFitProvidedWidthStrategy | SizeColumnsToContentStrategy;
+
+export declare interface BodyScrollEvent {
+    scrollTop: number;
+    scrollLeft: number;
+}
+
+/** 内置编辑器标识 */
+export declare type BuiltInCellEditor = 'text' | 'number' | 'checkbox';
+
+/** 对外 API / 事件 rowId：与用户 data[rowKey] 同型；临时行无业务主键时为 null */
+export declare type BusinessRowId = RowId | null;
+
+export declare interface CellClickedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+    rowNode: RowNode;
+}
+
+/** 单元格批注载荷 */
+export declare interface CellComment<TMetadata = unknown> {
+    /** 批注正文（纯文本） */
+    text: string;
+    /** true → 内置 UI 只读；API 仍可覆盖 */
+    readOnly?: boolean;
+    author?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: TMetadata;
+}
+
+export declare interface CellCommentChangedEvent<TMetadata = unknown> {
+    rowId: BusinessRowId;
+    colId: string;
+    /** null 表示已删除 */
+    comment: CellComment<TMetadata> | null;
+    source: CellCommentSource;
+}
+
+export declare interface CellCommentParams<TData = RowData> {
+    rowId: BusinessRowId;
+    colId: string;
+    data: TData;
+    column: Column;
+}
+
+/** 批注持久化数据源；提供即启用批注能力 */
+export declare interface CellCommentsDataSource<TData = RowData, TMetadata = unknown> {
+    getComment: (params: CellCommentParams<TData>) => CellComment<TMetadata> | undefined | null;
+    setComment: (params: SetCellCommentParams<TData, TMetadata>) => void | Promise<void>;
+    init?: (ctx: CellCommentsDataSourceInitContext) => void;
+    destroy?: () => void;
+}
+
+export declare interface CellCommentsDataSourceInitContext {
+    api: GridApi;
+}
+
+export declare type CellCommentSource = 'ui' | 'api';
+
+export declare type CellCommentTrigger = 'hover' | 'click';
+
+export declare interface CellCommitFinishedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+    committed: boolean;
+    aborted?: boolean;
+}
+
+export declare interface CellCommitStartedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+}
+
+export declare type CellDisabledFn<TData = RowData> = (params: CellDisabledParams<TData>) => boolean;
+
+/** 格级禁用判定参数 */
+export declare interface CellDisabledParams<TData = RowData> {
+    data: TData;
+    rowId: BusinessRowId;
+    colId: string;
+}
+
+/** 编辑范围：单格编辑 vs 整行编辑 */
+export declare type CellEditBehavior = 'cell' | 'row';
+
+export declare interface CellEditingStartedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+    value: unknown;
+}
+
+export declare interface CellEditingStoppedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+    committed: boolean;
+    oldValue: unknown;
+    newValue: unknown;
+}
+
+export declare interface CellEditorContext {
+    /** 绑定到第三方组件 @keydown */
+    onKeydown: (event: Event | KeyboardEvent) => void;
+    /** 绑定到 @change；或 commitOnChange 时内部已处理 */
+    onChange: () => void;
+    commit: () => void;
+    cancel: () => void;
+}
+
+/** 列级编辑器配置：函数、内置名、或命名引用 */
+export declare type CellEditorDef = CellEditorFn | CellEditorRef;
+
+/**
+ * 自定义单元格编辑器
+ * - 返回 HTMLElement：由内核写入 mount 容器
+ * - 返回 void：表示已在 ctx.mountEl 内自行挂载（如 Vue 编辑器）
+ */
+export declare type CellEditorFn = (params: CellEditorParams, ctx: CellEditorMountContext) => HTMLElement | void | null | undefined;
+
+/** 内核键盘策略（由 Vue Composable 注册） */
+export declare interface CellEditorKeyboardPolicy {
+    /** 为 true 时内核捕获阶段不处理 Enter，交由编辑器组件确认后再提交 */
+    deferEnterCommit?: boolean;
+}
+
+/** 单元格编辑器呈现模式：overlay 进入编辑态；inline 常驻格内 */
+export declare type CellEditorMode = 'overlay' | 'inline';
+
+/** 编辑器挂载上下文（内核提供 mount 容器） */
+export declare interface CellEditorMountContext {
+    mountEl: HTMLElement;
+    clear(): void;
+}
+
+export declare interface CellEditorOptions<T> {
+    /** 交互策略，决定键盘与提交默认行为 */
+    strategy?: CellEditorStrategy;
+    /** 读取当前 draft 值 */
+    getValue: () => T;
+    /** 提交前序列化为字符串 */
+    formatValue?: (value: T) => string;
+    /** 进入编辑后 focus / 打开面板 */
+    onStart?: () => void | Promise<void>;
+    /** 值变更时自动提交（overlay 默认 true） */
+    commitOnChange?: boolean;
+}
+
+/** 自定义单元格编辑器入参（对称 CellRendererParams） */
+export declare interface CellEditorParams {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    colId: string;
+    value: unknown;
+    data: RowData;
+    formattedValue: string;
+    /** 提交(true) 或 取消(false)；块 5 起返回 Promise */
+    stopEditing: (commit?: boolean) => Promise<void>;
+    /** 中断进行中的 async 提交，保持编辑态 */
+    cancelCommit: () => void;
+    /** 当前编辑会话阶段 */
+    getEditPhase: () => EditSessionPhase;
+    /** Vue / 复合组件编辑器注册自定义取值（优先于 DOM 扫描） */
+    setGetValue?: (getValue: () => string) => void;
+    /** 注册键盘策略（如 deferEnterCommit、commitOnChange） */
+    setKeyboardPolicy?: (policy: CellEditorKeyboardPolicy) => void;
+    /** 是否执行编辑器 onStart（focus / 打开 overlay）。
+     * 行编辑时仅 focusColId 对应列为 true；省略时视为 true（单格编辑）。
+     */
+    autoFocus?: boolean;
+    /** 对当前 draft 值执行校验（可 async）；不触发 commit */
+    validate: (options?: {
+        signal?: AbortSignal;
+    }) => Promise< CellValidationOutcome>;
+    /** inline 模式：提交当前值（块 3 注入；走完整 commit 管线） */
+    commit?: (rawValue?: string) => Promise<void>;
+    /** 是否为常驻 inline 编辑器（块 2+ 注入） */
+    inline?: boolean;
+}
+
+/** 命名编辑器引用（内置名或 registerCellEditor 注册名） */
+export declare type CellEditorRef = BuiltInCellEditor | (string & {});
+
+/** 编辑器交互策略 */
+export declare type CellEditorStrategy = 'input' | 'overlay';
+
+/** 进入编辑态的触发方式（单击 / 双击） */
+export declare type CellEditType = 'singleClick' | 'doubleClick';
+
+export declare interface CellFocusedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+    rowNode: RowNode;
+}
+
+/** CellSelectionOptions 层 handle 模式；默认 off */
+export declare type CellHandleMode = 'off' | 'fill' | 'range';
+
+export declare interface CellPosition {
+    rowIndex: number;
+    colId: string;
+}
+
+/** 矩形选区（行列边界均为 display index + displayed colId） */
+export declare interface CellRange {
+    startRowIndex: number;
+    endRowIndex: number;
+    startColId: string;
+    endColId: string;
+}
+
+/**
+ * 自定义单元格渲染器
+ * - 返回 string / HTMLElement：由内核写入 mount 容器
+ * - 返回 void：表示已在 ctx.mountEl 内自行挂载（如 Vue 渲染器）
+ */
+export declare type CellRendererFn = (params: CellRendererParams, ctx: CellRendererMountContext) => string | HTMLElement | void | null | undefined;
+
+/** 渲染器挂载上下文（内核提供 mount 容器） */
+export declare interface CellRendererMountContext {
+    mountEl: HTMLElement;
+    clear(): void;
+}
+
+/** 自定义单元格渲染器入参 */
+export declare interface CellRendererParams {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    colId: string;
+    value: unknown;
+    data: RowData;
+    formattedValue: string;
+    /** true 表示当前为表尾汇总格 */
+    isSummaryRow?: boolean;
+}
+
+/** 选区聚合结果；无有效选区时由 API 层返回 null */
+export declare interface CellSelectionAggregation {
+    /** 非空单元格个数（含非数值） */
+    count: number;
+    /** 可解析为数值的单元格个数 */
+    numericCount: number;
+    /** 数值之和；numericCount === 0 时为 null */
+    sum: number | null;
+    /** 数值平均值；numericCount === 0 时为 null */
+    average: number | null;
+}
+
+export declare interface CellSelectionChangedEvent {
+    ranges: CellRange[];
+    source: CellSelectionSource;
+}
+
+export declare interface CellSelectionDeleteEndEvent {
+    ranges: CellRange[];
+    changedCellCount: number;
+}
+
+export declare interface CellSelectionDeleteStartEvent {
+    ranges: CellRange[];
+}
+
+export declare interface CellSelectionOptions {
+    /** true → 仅允许单个 range */
+    suppressMultiRanges?: boolean;
+    /** 点击表头选中整列；core 默认 false，MagicGrid 组件层默认 true */
+    enableColumnSelection?: boolean;
+    /** Fill 或 Range Handle；默认 off */
+    handleMode?: CellHandleMode;
+    /** handleMode 为 fill 时生效；默认 xy */
+    direction?: FillHandleDirection;
+    /** 默认 'copy' 始终复制源边值；'auto' 数字递增、非数字复制 */
+    fillStrategy?: FillStrategy;
+    /** 默认 'default'：反拖缩小不处理；'clear' 置空缩出初始选区的格 */
+    fillReverseStrategy?: FillReverseStrategy;
+    setFillValue?: (params: FillOperationParams) => unknown;
+}
+
+export declare type CellSelectionSource = 'ui' | 'api';
+
+/** 运行时 span 查询结果（只读） */
+export declare interface CellSpanInfo {
+    colId: string;
+    firstRowId: string;
+    lastRowId: string;
+    rowSpan: number;
+    colSpan: number;
+    /** 被本 span 覆盖的 rowId（含 head） */
+    rowIds: readonly string[];
+    /** 被本 span 覆盖的 colId（含 head） */
+    colIds: readonly string[];
+}
+
+/** colSpan / rowSpan 回调入参（表体与表尾共用） */
+export declare interface CellSpanParams {
+    rowId: string;
+    rowIndex: number;
+    data: RowData | null;
+    colId: string;
+    /** 表尾汇总行时为 true；此时 data 为 null，rowIndex 用 SUMMARY_ROW_INDEX */
+    isSummaryRow: boolean;
+    /** 当前列原始值（表体）；表尾为汇总结果值 */
+    value: unknown;
+}
+
+export declare interface CellSpanPosition {
+    rowId: string;
+    colId: string;
+}
+
+export declare type CellSpanRowKey = string | typeof SUMMARY_ROW_ID;
+
+/** 单元格 / 行 inline 样式（v1 仅开放 color 相关字段） */
+export declare interface CellStyle {
+    backgroundColor?: string;
+    color?: string;
+}
+
+export declare type CellStyleFn<TData = RowData> = (params: CellStyleParams<TData>) => CellStyle | null | undefined;
+
+export declare interface CellStyleParams<TData = RowData> {
+    data: TData;
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+    column: Pick<Column, 'colId' | 'prop'>;
+}
+
+export declare interface CellValidationFailedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    rowIndex: number;
+    errors: string[];
+    mode: InvalidEditValueMode;
+}
+
+export declare interface CellValidationFailure {
+    valid: false;
+    errors: string[];
+}
+
+export declare type CellValidationOutcome = CellValidationResult | CellValidationFailure;
+
+export declare interface CellValidationResult {
+    valid: true;
+}
+
+export declare type CellValidator = (params: CellEditorParams & {
+    parsedValue: unknown;
+    signal: AbortSignal;
+}) => ValidationErrors | Promise<ValidationErrors>;
+
+export declare interface CellValueChangedEvent {
+    rowId: BusinessRowId;
+    colId: string;
+    oldValue: unknown;
+    newValue: unknown;
+    rowNode: RowNode;
+}
+
+export declare interface ClearCellValidationOptions {
+    /** 待清除校验反馈的单元格列表 */
+    cells: GridCellPosition[];
+}
+
+export declare interface ClearRowValidationOptions {
+    /** 待清除校验反馈的行 id 列表 */
+    rowIds: RowId[];
+}
+
+export declare interface ClearValidationOptions {
+    /** 指定行 id；省略则清除全表校验反馈 */
+    rowIds?: RowId[];
+}
+
+/** 横向合并列数（≥1）；缺省视为 1 */
+export declare type ColSpanFn = (params: CellSpanParams) => number;
+
+/** 列运行时模型（由 ColumnDef 解析而来） */
+export declare interface Column {
+    /** 列唯一标识 */
+    readonly colId: string;
+    /** 数据字段 */
+    readonly prop?: string;
+    /** 表头文案 */
+    readonly label?: string;
+    /** 当前宽度（px） */
+    readonly width: number;
+    /** 列定义初始宽度（px）；缺省同 width */
+    readonly initialWidth?: number;
+    /** 最小宽度（px） */
+    readonly minWidth: number;
+    /** 最大宽度（px），缺省无上限 */
+    readonly maxWidth?: number;
+    /** flex 权重；仅 center 列生效 · 手动 resize 后清除 */
+    readonly flex: number | null;
+    /** 禁止参与 sizeColumnsToFit 比例分配 */
+    readonly suppressSizeToFit: boolean;
+    /** 相对表格左缘的累计偏移（px）；中心列相对中心滚动原点；右固定列另见 rightOffset */
+    readonly left: number;
+    /** 固定侧；缺省 null 表示中心可滚动列 */
+    readonly fixed: 'left' | 'right' | null;
+    /** 右固定列：距视口右缘的偏移（px）；仅 fixed === 'right' 时有值 */
+    readonly rightOffset?: number;
+    /** 是否允许表头 click 排序；默认 false */
+    readonly sortable: boolean;
+    /** 是否允许列筛选；默认 false */
+    readonly filterable: boolean;
+    /** 列筛选数据类型；默认 text */
+    readonly filterType: ColumnDataFilterType;
+    /** 已解析的列级 filter 参数 */
+    readonly filterParams: ResolvedFilterParams;
+    /** 筛选用取值；缺省 formatter → valueGetter → prop */
+    readonly filterFormatter?: ColumnFilterFormatter;
+    /** 自定义排序比较器；缺省使用默认 compareValues */
+    readonly comparator?: ColumnComparatorFn;
+    /** 是否允许表头拖拽重排；由 Grid columnMovable + 列 movable 解析 */
+    readonly movable: boolean;
+    /** 是否允许拖拽调整列宽；由 Grid resizable + 列 resizable 解析 */
+    readonly resizable: boolean;
+    /** 是否禁止 dblclick / API auto-size（对标 suppressAutoSize） */
+    readonly suppressAutoSize?: boolean;
+    /** 值读取器（来自 ColumnDef） */
+    readonly valueGetter?: (row: RowData, value: unknown) => unknown;
+    /** 值格式化（来自 ColumnDef） */
+    readonly formatter?: (row: RowData, value: unknown) => string;
+    /** 是否可编辑 */
+    readonly editable?: boolean | ((row: RowData) => boolean);
+    /** 自定义单元格渲染器 */
+    readonly cellRenderer?: CellRendererFn;
+    /** 单元格编辑器（函数、内置名、或命名引用） */
+    readonly cellEditor?: CellEditorDef;
+    /** 编辑器呈现：overlay 进编辑态；inline 常驻格内。默认 overlay */
+    readonly cellEditorMode?: CellEditorMode;
+    /** 提交前解析编辑值 */
+    readonly valueParser?: (value: unknown, params: CellEditorParams) => unknown;
+    /** 自定义写回逻辑，返回 false 拒绝提交；可 async（块 5） */
+    readonly valueSetter?: (params: CellEditorParams & {
+        newValue: unknown;
+        signal: AbortSignal;
+    }) => boolean | Promise<boolean>;
+    /** 编辑触发策略 */
+    readonly editType?: CellEditType;
+    /** 提交前校验（可 async）；返回错误消息数组表示拒绝 */
+    readonly cellValidator?: CellValidator;
+    /** Phase 24 块 12 · 禁止粘贴；默认 false */
+    readonly suppressPaste?: boolean | SuppressPasteFn;
+    /** Phase 24 块 12 · 粘贴是否走 valueParser；默认 true */
+    readonly useParserForClipboard?: boolean;
+    /** Phase 24 块 13 · 复制是否走 formatter；默认 true */
+    readonly useFormatterForClipboard?: boolean;
+    /** 必填列（表头始终标红） */
+    readonly validationRequired?: boolean;
+    /** 是否参与表尾汇总；缺省时：有 summaryAgg 则为 true */
+    readonly summary?: boolean;
+    /** 表尾汇总聚合：内置名或自定义函数 */
+    readonly summaryAgg?: SummaryAgg;
+    /** 汇总格专用 formatter；缺省复用 formatter */
+    readonly summaryFormatter?: (value: unknown) => string;
+    /** 表头水平对齐（已解析） */
+    readonly headerAlign: GridHorizontalAlign;
+    /** 表头垂直对齐（已解析） */
+    readonly headerValign: GridVerticalAlign;
+    /** 表体水平对齐（已解析） */
+    readonly align: GridHorizontalAlign;
+    /** 表体垂直对齐（已解析） */
+    readonly valign: GridVerticalAlign;
+    /** 表尾汇总水平对齐（已解析） */
+    readonly footerAlign: GridHorizontalAlign;
+    /** 表尾汇总垂直对齐（已解析） */
+    readonly footerValign: GridVerticalAlign;
+    /** 该列内容撑开行高（Phase 15） */
+    readonly autoHeight: boolean;
+    /** 该列作为行 drag 起点（Phase 15） */
+    readonly rowDrag: boolean;
+    /** Phase 16 · 横向合并；系统列为 undefined */
+    readonly colSpan?: ColSpanFn;
+    /** Phase 16 · 纵向合并回调；系统列为 undefined */
+    readonly rowSpan?: RowSpanFn;
+    /** Phase 16 · 等值自动纵向合并；系统列为 undefined */
+    readonly spanRows?: boolean | SpanRowsFunc;
+    /** Phase 17 · 在该列渲染 expand/collapse 控件；系统列为 false */
+    readonly rowExpand: boolean;
+    /** Phase 18 · 该列参与行分组；系统列为 false */
+    readonly rowGroup: boolean;
+    /** Phase 18 · 多级分组顺序；未参与分组时为 undefined */
+    readonly rowGroupIndex?: number;
+    /** Phase 18 · 分组 footer 聚合；系统列为 undefined */
+    readonly groupAgg?: SummaryAgg;
+    /** Phase 18 · 用户列渲染 groupHeader 单元格 */
+    readonly showGroupHeaderCell: boolean;
+    /** Phase 18 · 用户列渲染 groupFooter 标签 */
+    readonly showGroupFooterCell: boolean;
+    /** Phase 18 · 本列小计文案；缺省继承 Grid groupFooterLabel */
+    readonly groupFooterLabel?: string;
+    /** Phase 20 · 抑制批注新建/编辑/删除；已有批注仍可查看 */
+    readonly suppressCellComments?: boolean | SuppressCellCommentFn;
+    /** Phase 21 · 列级禁用：true 时该列全部数据行 disabled */
+    readonly disabled?: boolean;
+    /** Phase 21 · 格级禁用：按行判定 */
+    readonly cellDisabled?: boolean | CellDisabledFn;
+    /** Phase 26 · 列级静态背景 或 格级 cellStyle 回调 */
+    readonly cellStyle?: CellStyle | CellStyleFn;
+    /** Phase 22 · 是否隐藏（不渲染 · 不参与布局）；默认 false */
+    readonly hidden: boolean;
+    /** Phase 27 · 列 def 声明序（setColumns 解析 index）；用于重置列顺序 */
+    readonly defOrder: number;
+    /** Phase 23 · tooltip 字段 */
+    readonly tooltipField?: string;
+    readonly tooltipValueGetter?: TooltipValueGetter;
+    readonly headerTooltip?: string;
+    readonly headerTooltipValueGetter?: HeaderTooltipValueGetter;
+    /** Phase 23 · 是否抑制溢出 tooltip；系统列默认 true */
+    readonly suppressTooltip: boolean;
+    readonly tooltipComponent?: TooltipComponentType;
+    readonly tooltipComponentParams?: Record<string, unknown>;
+}
+
+/** 列级自定义排序比较器；返回 asc 语义（desc 由 SortStage 统一取反） */
+export declare type ColumnComparatorFn = (valueA: unknown, valueB: unknown, direction: SortDirection, rowA: RowData, rowB: RowData) => number;
+
+/** 列级筛选数据类型（决定菜单面板与 FilterStage 比较策略） */
+export declare type ColumnDataFilterType = 'text' | 'number' | 'date';
+
+/** 列定义；`TData` 为行数据类型，用于 prop / 回调参数类型推导 */
+export declare interface ColumnDef<TData extends RowData = RowData> {
+    /** 列唯一标识，缺省等于 prop */
+    key?: string;
+    /** 数据字段 */
+    prop?: Extract<keyof TData, string>;
+    /** 表头文案 */
+    label?: string;
+    /**
+     * 列是否有效；默认 true。
+     * 为 false 时该列不存在于表格中（不参与列模型与绘制）；
+     * 与 hidden 不同——hidden 仍保留列，仅不渲染。
+     */
+    available?: boolean;
+    /**
+     * 是否隐藏该列（不渲染 header/body/footer · 不参与布局）。
+     * 默认 false（可见）。系统列忽略此配置。
+     */
+    hidden?: boolean;
+    /** 尺寸 */
+    width?: number;
+    /** 列最小宽度（px） */
+    minWidth?: number;
+    /** 列最大宽度（px） */
+    maxWidth?: number;
+    /** flex 布局权重；与 width 互斥时 flex 参与剩余空间分配 */
+    flex?: number;
+    /** 是否允许表头排序；缺省继承 Grid `sortable`（默认 false） */
+    sortable?: boolean;
+    /**
+     * 自定义排序比较器；入参为两行的单元格原始值（经 valueGetter）。
+     * 须返回 asc 语义比较结果；desc 由 Grid 统一取反。
+     */
+    comparator?: ColumnComparatorFn;
+    /** 是否允许列筛选；缺省继承 Grid `filterable`（默认 false） */
+    filterable?: boolean;
+    /** 列筛选数据类型；默认 text */
+    filterType?: ColumnDataFilterType;
+    /** 列级 filter 参数（如 caseSensitive） */
+    filterParams?: FilterParams;
+    /** 筛选用取值；缺省 formatter → valueGetter → prop */
+    /** 筛选用取值；缺省 formatter → valueGetter → prop */
+    filterFormatter?: (row: TData) => unknown;
+    /** 是否可编辑；可函数按行判断 */
+    editable?: boolean | ((row: TData) => boolean);
+    /** 是否允许拖拽调整列宽；缺省继承 Grid `resizable`（默认 true） */
+    resizable?: boolean;
+    /** 禁止 resize 把柄 dblclick / API auto-size；对标 AG Grid suppressAutoSize */
+    suppressAutoSize?: boolean;
+    /** 禁止参与 sizeColumnsToFit；对标 AG Grid suppressSizeToFit */
+    suppressSizeToFit?: boolean;
+    /** 列固定：left / right；null 或不传为不固定 */
+    fixed?: 'left' | 'right' | null;
+    /** 是否允许表头拖拽重排；默认继承 grid.columnMovable */
+    movable?: boolean;
+    /** 该列单元格作为行拖拽起点；默认 false */
+    rowDrag?: boolean;
+    /**
+     * 在该列渲染 expand/collapse 控件；需 Grid `masterDetail: true`。
+     * 与 `showExpandColumn` 可并存（列级优先展示位置由列序决定）。
+     */
+    rowExpand?: boolean;
+    /**
+     * 该列参与行分组；需 Grid `rowGrouping: true`。
+     * 与 `rowGroupIndex` 控制多级顺序。
+     */
+    rowGroup?: boolean;
+    /** 多级分组顺序（小者优先）；缺省按列定义顺序 */
+    rowGroupIndex?: number;
+    /** 分组 footer 行的聚合；缺省不在该列展示 group 汇总 */
+    groupAgg?: SummaryAgg;
+    /**
+     * 在该用户列渲染 groupHeader 单元格（chevron / 缩进 / 键值）。
+     * 与系统 auto group 列二选一；不可用于系统列。
+     */
+    showGroupHeaderCell?: boolean;
+    /**
+     * 在该用户列渲染 groupFooter 标签（如「小计」）。
+     * 聚合数值仍由 `groupAgg` 列展示。
+     */
+    showGroupFooterCell?: boolean;
+    /** 覆盖 Grid `groupFooterLabel` 的本列小计文案 */
+    groupFooterLabel?: string;
+    /** 该列内容撑开行高（与其他 autoHeight 列取 max）；默认 false */
+    autoHeight?: boolean;
+    /**
+     * 横向合并列数（≥1）；表体与表尾共用，用 `params.isSummaryRow` 分支。
+     * 需 Grid `enableCellSpan: true`。系统列忽略。
+     */
+    colSpan?: ColSpanFn;
+    /**
+     * 纵向合并行数（≥1）；仅表体。与 `spanRows` 互斥（本字段优先）。
+     * 需 Grid `enableCellSpan: true`。系统列忽略。
+     */
+    rowSpan?: RowSpanFn;
+    /**
+     * 相邻等值自动纵向合并；`true` 或自定义比较函数。
+     * 需 Grid `enableCellSpan: true`。同列若同时配 `rowSpan` 则本字段不生效。
+     */
+    spanRows?: boolean | SpanRowsFunc;
+    /** 读取单元格展示值（优先于 prop 直读） */
+    valueGetter?: (row: TData, value: unknown) => unknown;
+    /** 格式化展示文案（不影响原始值） */
+    formatter?: (row: TData, value: unknown) => string;
+    /** 自定义单元格渲染器（函数；Vue 组件通过 MagicGrid 槽位注册） */
+    cellRenderer?: CellRendererFn;
+    /** 自定义单元格编辑器（函数、内置 text / number / checkbox、或命名引用） */
+    cellEditor?: CellEditorDef;
+    /** 编辑器呈现：overlay 进编辑态；inline 常驻格内。默认 overlay */
+    cellEditorMode?: CellEditorMode;
+    /** 提交前解析编辑值 */
+    valueParser?: (value: unknown, params: CellEditorParams) => unknown;
+    /** 自定义写回逻辑，返回 false 拒绝提交；可 async */
+    valueSetter?: (params: CellEditorParams & {
+        newValue: unknown;
+        signal: AbortSignal;
+    }) => boolean | Promise<boolean>;
+    /** 编辑触发策略，缺省继承 grid 级配置 */
+    editType?: CellEditType;
+    /** 手写校验（优先级高于 validationRules） */
+    cellValidator?: CellValidator;
+    /** 禁止粘贴；可函数按行判断 */
+    suppressPaste?: boolean | ((row: TData) => boolean);
+    /** 粘贴是否走 valueParser；默认 true */
+    useParserForClipboard?: boolean;
+    /** 复制是否走 formatter；默认 true */
+    useFormatterForClipboard?: boolean;
+    /** async-validator 规则；通过 magic-grid/validation enrichColumnsWithValidation 编译 */
+    validationRules?: ValidationRules;
+    /** 必填列标记（缺省由 validationRules.required 推导） */
+    validationRequired?: boolean;
+    /** 是否参与表尾汇总；缺省时：有 summaryAgg 则为 true，否则 false */
+    summary?: boolean;
+    /** 表尾汇总聚合：内置 sum / avg / min / max / count 或自定义函数 */
+    summaryAgg?: SummaryAgg;
+    /** 汇总格专用 formatter；缺省复用 formatter */
+    summaryFormatter?: (value: unknown) => string;
+    /** 表头水平对齐；默认 center */
+    headerAlign?: GridHorizontalAlign;
+    /** 表头垂直对齐；默认 center */
+    headerValign?: GridVerticalAlign;
+    /** 表体水平对齐；默认 center */
+    align?: GridHorizontalAlign;
+    /** 表体垂直对齐；默认 center */
+    valign?: GridVerticalAlign;
+    /** 表尾汇总水平对齐；默认 center */
+    footerAlign?: GridHorizontalAlign;
+    /** 表尾汇总垂直对齐；默认 center */
+    footerValign?: GridVerticalAlign;
+    /**
+     * 抑制该列（或特定行）的批注新建/编辑/删除。
+     * 已有批注仍可查看。
+     */
+    suppressCellComments?: boolean | SuppressCellCommentFn<TData>;
+    /** 列级禁用：true 时该列全部数据行 disabled */
+    disabled?: boolean;
+    /** 格级禁用：按行判定；与 disabled / isRowDisabled 叠加 */
+    cellDisabled?: boolean | CellDisabledFn<TData>;
+    /**
+     * 列级静态背景 或 格级 cellStyle 回调（二选一 · 同 AG Grid cellStyle）。
+     * 仅作用于表体用户数据列；表头/表尾/索引列/系统列不参与。
+     */
+    cellStyle?: CellStyle | CellStyleFn<TData>;
+    /** 读 row.data[field] 作为 tooltip */
+    tooltipField?: Extract<keyof TData, string>;
+    /** 自定义 tooltip 文案 */
+    tooltipValueGetter?: TooltipValueGetter<TData>;
+    /** 表头静态 tooltip */
+    headerTooltip?: string;
+    /** 表头动态 tooltip 文案 */
+    headerTooltipValueGetter?: HeaderTooltipValueGetter;
+    /** 抑制该列溢出 tooltip */
+    suppressTooltip?: boolean;
+    /** 自定义 tooltip 组件 */
+    tooltipComponent?: TooltipComponentType;
+    /** 自定义 tooltip 组件额外参数 */
+    tooltipComponentParams?: Record<string, unknown>;
+}
+
+export declare interface ColumnFilter {
+    type: FilterType;
+    filter?: string;
+    /** date inRange 第二端点（ISO 文本） */
+    filterTo?: string;
+    /** 多条件组合逻辑；缺省 AND */
+    operator?: ColumnFilterLogic;
+    /** 多条件算子列表；存在时优先于顶层 type/filter */
+    conditions?: ColumnFilterOperatorCondition[];
+    /** 值选择：选中 key；缺省表示全选（不约束） */
+    setValues?: string[];
+}
+
+export declare type ColumnFilterFormatter = (row: RowData) => unknown;
+
+/** 多条件过滤器之间的组合逻辑 */
+export declare type ColumnFilterLogic = 'AND' | 'OR';
+
+/** 单列过滤器中的一个算子条件 */
+export declare interface ColumnFilterOperatorCondition {
+    type: FilterType;
+    filter?: string;
+    filterTo?: string;
+}
+
+export declare interface ColumnFilterValueOption {
+    key: string;
+    label: string;
+    blank?: boolean;
+}
+
+/** 事件 payload */
+export declare interface ColumnHiddenChangedEvent {
+    colIds: readonly string[];
+    hidden: boolean;
+    source: 'api' | 'columnDefs' | 'menu';
+}
+
+export declare type ColumnHiddenChangedSource = ColumnHiddenChangedEvent['source'];
+
+export declare interface ColumnMovedEvent {
+    /** 移动后的完整 colId 顺序（含系统列） */
+    columnOrder: string[];
+    fromColId: string;
+    toIndex: number;
+    /** false：drag 中 live move；true：mouseup 最终提交 */
+    finished: boolean;
+    /** Phase 11.1 块 5 · 跨 lane 时移动列的新 fixed；lane 内移动时省略 */
+    toFixed?: 'left' | 'right' | null;
+}
+
+export declare interface ColumnPinnedEvent {
+    colId: string;
+    fixed: ColumnPinOption;
+    /** 改 pin 前 fixed；首 pin 时为 null */
+    fromFixed: ColumnPinOption;
+    source: ColumnPinSource;
+}
+
+export declare type ColumnPinOption = 'left' | 'right' | null;
+
+export declare type ColumnPinSource = 'menu' | 'api';
+
+export declare interface ColumnResizedColumnSnapshot {
+    colId: string;
+    width: number;
+}
+
+/** 对标 AG Grid ColumnResizedEvent（Phase 14 块 5） */
+export declare interface ColumnResizedEvent {
+    columns: ColumnResizedColumnSnapshot[];
+    /** 仅当 columns.length === 1 时便捷引用 */
+    column: ColumnResizedColumnSnapshot | null;
+    finished: boolean;
+    /** flex 被动调整的列；无 flex 变化时为 null */
+    flexColumns: ColumnResizedColumnSnapshot[] | null;
+    source: ColumnResizeSource;
+}
+
+export declare type ColumnResizeSource = 'uiColumnResized' | 'api' | 'autosizeColumns' | 'flex' | 'sizeColumnsToFit';
+
+export declare type ColumnSettingsMenuIconName = 'sliders-vertical' | 'list-restart' | 'sort' | 'filter' | 'width' | 'order' | 'pin' | 'all';
+
+/** Phase 27 · 表格设置「重置」作用域 */
+export declare type ColumnSettingsResetScope = 'sort' | 'filter' | 'width' | 'order' | 'pin' | 'all';
+
+export declare interface CustomColumnFilter {
+    predicate: (value: unknown, row: RowData) => boolean;
+}
+
+/** 日期列 v1：用户输入纯文本 ISO（如 2026-08-07） */
+export declare type DateFilterType = 'equals' | 'notEqual' | 'lessThan' | 'greaterThan' | 'inRange' | 'blank' | 'notBlank';
+
+/** 框选聚合平均值 / 求和默认小数位数 */
+export declare const DEFAULT_STATUS_BAR_RANGE_AGGREGATION_PRECISION = 2;
+
+export declare const DEFAULT_SUMMARY_SCOPE: SummaryScope;
+
+export declare type DetailCellRendererFn = (params: DetailRowRendererParams, ctx: DetailRowRendererMountContext) => string | HTMLElement | void | null | undefined;
+
+export declare type DetailRowHeightFn = (params: DetailRowHeightParams) => number;
+
+export declare interface DetailRowHeightParams {
+    rowId: BusinessRowId;
+    data: RowData;
+    masterRowId: BusinessRowId;
+}
+
+export declare interface DetailRowRendererMountContext {
+    mountEl: HTMLElement;
+    clear(): void;
+}
+
+/** 详情行渲染入参（插槽 / detailCellRenderer） */
+export declare interface DetailRowRendererParams {
+    /** detail 行 id */
+    rowId: BusinessRowId;
+    masterRowId: BusinessRowId;
+    data: RowData;
+    detailRowData: unknown;
+    loading: boolean;
+    /** getDetailRowData 失败时为 true */
+    loadFailed: boolean;
+    loadError?: unknown;
+}
+
+/** `#detail-row` 插槽 props */
+export declare interface DetailRowSlotParams<TData extends RowData = RowData> {
+    /** 主行数据 */
+    row: TData;
+    /** 主行 rowId */
+    rowId: string;
+    /** 与 rowId 相同（兼容别名） */
+    masterRowId: string;
+    /** 详情区数据（`getDetailRowData` 返回值） */
+    detailRowData: unknown;
+    /** 详情数据是否加载中 */
+    loading: boolean;
+    /** 详情数据是否加载失败 */
+    loadFailed: boolean;
+    /** 加载失败时的错误对象 */
+    loadError?: unknown;
+}
+
+export declare interface EditCommitAbortedEvent {
+    rowId?: BusinessRowId;
+    colId?: string;
+    rowIndex?: number;
+}
+
+export declare interface EditingCellPosition {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    colId: string;
+}
+
+/** 编辑会话阶段 */
+export declare type EditSessionPhase = 'idle' | 'editing' | 'committing' | 'cancelling';
+
+/**
+ * `ensureIndexVisible` 滚动对齐方式。
+ *
+ * - `'top'` — 目标行贴近视口顶部
+ * - `'bottom'` — 目标行贴近视口底部
+ * - `'middle'` — 目标行尽量居中（默认）
+ */
+export declare type EnsureIndexVisiblePosition = 'top' | 'bottom' | 'middle';
+
+export declare type FillHandleDirection = 'x' | 'y' | 'xy';
+
+export declare interface FillOperationParams {
+    rowNode: RowNode;
+    column: Column;
+    /** 填充源方向上的基准格值 */
+    baseValue: unknown;
+    /** 当前目标格相对扩展步长 */
+    step: number;
+    direction: 'x' | 'y';
+}
+
+/** Fill 反拖默认策略：不置空 */
+export declare type FillReverseStrategy = 'default' | 'clear';
+
+/** Fill 默认策略：数字递增、非数字复制 */
+export declare type FillStrategy = 'auto' | 'copy';
+
+export declare interface FilterChangedEvent {
+    filterModel: FilterModel;
+    /** Phase 12 · Grid 级 quick filter 文本；缺省 `''` */
+    quickFilterText: string;
+}
+
+export declare type FilterCondition = ColumnFilter | CustomColumnFilter;
+
+export declare type FilterModel = Record<string, FilterCondition>;
+
+export declare interface FilterParams {
+    /** 文本比较是否区分大小写；默认 true */
+    caseSensitive?: boolean;
+    /** 数字/日期解析 locale（可选） */
+    locale?: string;
+}
+
+/** 日期列值选择展示方式 */
+export declare type FilterSetDateLayoutMode = 'list' | 'tree';
+
+/** 值选择筛选模式：reserve 保留完整勾选 / current 搜索时仅当前结果 */
+export declare type FilterSetValueMode = 'reserve' | 'current';
+
+export declare type FilterType = TextFilterType | NumberFilterType | DateFilterType;
+
+export declare interface GetDataOptions {
+    /** true = source 顺序（默认）；false = 当前 display 顺序 */
+    sourceOrder?: boolean;
+}
+
+/** 对标 AG Grid getDataPath */
+export declare type GetDataPathFn = (params: GetDataPathParams) => string[];
+
+export declare interface GetDataPathParams {
+    data: RowData;
+}
+
+export declare type GetDetailRowDataFn = (params: GetDetailRowDataParams) => void | Promise<void>;
+
+export declare interface GetDetailRowDataParams {
+    rowId: BusinessRowId;
+    data: RowData;
+    successCallback: (detailRowData: unknown) => void;
+    failCallback?: (error?: unknown) => void;
+}
+
+/** 行级动态高度（无 DOM 测量）；返回 null/undefined 表示回退默认行高 */
+export declare type GetRowHeightFn = (params: GetRowHeightParams) => number | null | undefined;
+
+export declare interface GetRowHeightParams {
+    rowId: BusinessRowId;
+    data: RowData;
+    rowIndex: number;
+}
+
+/** Grid 验收阈值 */
+export declare interface GridAcceptanceThresholds {
+    maxDomRows: number;
+    maxSetDataMs: number;
+}
+
+/**
+ * Magic Grid 完整命令式 API（对照 AG Grid GridApi 子集）。
+ *
+ * 按职责分组：数据 / 排序筛选 / 视口 / 编辑 / 校验 / 行选 / 索引定位 / 生命周期。
+ */
+export declare interface GridApi extends RowMutationGridApi {
+    /**
+     * 全量替换表格数据（等价于清空后重新加载）。
+     *
+     * - 触发完整重绘与视口高度重算。
+     * - `reserveSelection: false`（默认）时清空选区；为 `true` 时保留仍存在的 rowId。
+     * - 始终清除索引定位与校验视觉反馈。
+     */
+    setData(rows: RowData[]): void;
+    /**
+     * 增量事务：add / update / remove。
+     *
+     * - `update` / `remove` 项可通过 `data[rowKey]` 或字符串 rowId 定位行。
+     * - 与 `addRows` / `removeRows` 共用同一刷新管线；大量连续操作建议包在 `beginUpdate` / `endUpdate` 中。
+     * - 配置 `asyncRowMutation` 时 await 对应钩子成功后再写入本地。
+     *
+     * @returns 本次事务影响的 RowNode 快照
+     */
+    applyTransaction(tx: RowTransaction): Promise<RowNodeTransaction>;
+    /** 设置排序模型并重算 `rowsToDisplay`。触发 `sortChanged`。 */
+    setSortModel(model: SortModelItem[]): void;
+    /** 读取当前排序模型（v1 至多 1 项） */
+    getSortModel(): SortModelItem[];
+    /** 设置筛选模型并重算 `rowsToDisplay`。触发 `filterChanged`。 */
+    setFilterModel(model: FilterModel): void;
+    /** 读取当前筛选模型。 */
+    getFilterModel(): FilterModel;
+    /** 读取单列筛选条件；未设置时 `null`。 */
+    getColumnFilter(colId: string): FilterCondition | null;
+    /** 单列是否有有效筛选条件（含 blank/notBlank · custom predicate）。 */
+    isColumnFilterActive(colId: string): boolean;
+    /** 任一列 filter 或 quick filter 是否 active。 */
+    isAnyFilterActive(): boolean;
+    /** 设置 Grid 级 quick filter 文本；触发 `filterChanged`（块 5 接入过滤语义）。 */
+    setQuickFilterText(text: string): void;
+    /** 读取当前 quick filter 文本。 */
+    getQuickFilterText(): string;
+    /**
+     * 清除全部筛选：列 filterModel + quickFilterText。
+     * 单次 filter 管线；无 active filter 时为 no-op。
+     */
+    clearAllFilters(): void;
+    /**
+     * 设置或清除单列筛选条件；`condition === null` 移除该 colId。
+     * 触发 `filterChanged`。
+     */
+    setColumnFilter(colId: string, condition: FilterCondition | null): void;
+    /**
+     * 编程式移动列；`toIndex` 为全局 columns 下标（含系统列占位）。
+     * 非法 move（跨 lane / 系统列）为 no-op；完整逻辑见 Phase 11 块 2。
+     */
+    moveColumn(colId: string, toIndex: number): void;
+    /** Phase 27 · 各 lane 内用户列恢复 defOrder；无变化时为 no-op */
+    resetColumnOrder(): boolean;
+    /** Phase 27 · 用户列恢复 defWidth / defFlex；无变化时为 no-op */
+    resetColumnWidths(): boolean;
+    /**
+     * 运行时改列 fixed（left / right / null）。
+     * 非法 colId 或系统列 no-op；与 `allowCrossLaneColumnMove` 无关。
+     */
+    setColumnFixed(colId: string, fixed: 'left' | 'right' | null): boolean;
+    /** Phase 22 · 批量设置列 hidden；触发 `columnHiddenChanged` */
+    setColumnsHidden(colIds: readonly string[], hidden: boolean): boolean;
+    /** Phase 22 · 列是否 hidden；未知 colId 返回 `undefined` */
+    isColumnHidden(colId: string): boolean | undefined;
+    /** Phase 22 · 当前 UI 展示的列 id（左→右） */
+    getDisplayedColumnIds(): readonly string[];
+    /** Phase 27 · 全量列（含 hidden · 含系统列） */
+    getColumns(): readonly Column[];
+    /** Phase 12 · 列 distinct 值（set filter 勾选列表） */
+    getColumnDistinctFilterValues(colId: string): readonly ColumnFilterValueOption[];
+    /** Phase 27 · 当前 UI 展示的列（不含 hidden） */
+    getDisplayedColumns(): readonly Column[];
+    /**
+     * 批量设置列宽（Phase 14）。
+     * 触发 `columnResized`；`finished: false` 用于拖拽过程，`true` 为最终提交。
+     */
+    setColumnWidths(payloads: readonly {
+        colId: string;
+        width: number;
+    }[], finished?: boolean, source?: ColumnResizeSource): void;
+    /** 设置单列宽度（Phase 14） */
+    setColumnWidth(colId: string, width: number, finished?: boolean, source?: ColumnResizeSource): void;
+    /** 读取列当前像素宽度（Phase 14） */
+    getColumnWidth(colId: string): number;
+    /** 按当前可见单元格内容自动调整列宽（Phase 14+ · 对标 autoSizeColumn） */
+    autoSizeColumn(colId: string, skipHeader?: boolean): void;
+    /** 批量 auto-size（Phase 14+ · 对标 autoSizeColumns） */
+    autoSizeColumns(colIds: readonly string[], skipHeader?: boolean): void;
+    /** 将列宽按比例分配至视口（或指定宽度）；对标 sizeColumnsToFit */
+    sizeColumnsToFit(params?: SizeColumnsToFitParams): void;
+    /**
+     * 设置单行高度并 pinned（Phase 15）。
+     *
+     * - 高度会 clamp 至 `rowHeightMin` / `rowHeightMax`。
+     * - `finished: false` 用于 resize 拖拽过程；`true`（默认）为最终提交。
+     * - 触发 `rowHeightChanged`（`source: 'api'`）。
+     */
+    setRowHeight(rowId: RowId, height: number, finished?: boolean): void;
+    /** 批量设置行高（Phase 15）；语义同 {@link setRowHeight} */
+    setRowHeights(changes: readonly {
+        rowId: RowId;
+        height: number;
+    }[], finished?: boolean): void;
+    /** 读取行当前有效高度（px）；行不存在时 `null` */
+    getRowHeight(rowId: RowId): number | null;
+    /**
+     * 清除 pinned 并重算行高（getRowHeight / autoHeight / 默认行高）。
+     *
+     * - 省略 `rowIds` 时重置全部 display 行。
+     * - 触发 `rowHeightChanged`（`source: 'api'` · `finished: true`）。
+     */
+    resetRowHeights(rowIds?: readonly RowId[]): void;
+    /**
+     * 热更新默认行高与 clamp 边界（Phase 15 · MagicGrid `rowHeight` prop）。
+     *
+     * 不销毁 Grid；pinned / getRowHeight / autoHeight 行保持既有规则。
+     */
+    updateDimensions(params: UpdateRowDimensionsParams): void;
+    /**
+     * 刷新指定行或列的单元格 DOM（不重跑全表 setData）。
+     *
+     * @param params.rowIds 限定行；省略则刷新当前虚拟窗口内可见行
+     * @param params.colIds 限定列 colId
+     * @param params.force 强制重绘，即使值未变
+     * @returns 实际刷新的行数
+     */
+    refreshCells(params?: RefreshCellsParams): number;
+    /**
+     * Phase 16 · 强制重建单元格合并 cache 并刷新可见行 / 表尾。
+     *
+     * 用于外部改写行数据后未走 `setData` / `applyTransaction`，
+     * 或 `spanRows` 自定义比较所依赖的外部状态变化。
+     * 需 Grid `enableCellSpan: true` 才有可见效果。
+     */
+    refreshCellSpans(): void;
+    /**
+     * Phase 16 · 只读查询 `(rowId, colId)` 所属 span。
+     *
+     * - 无合并 / 未开启 `enableCellSpan` / 位置无效 → `null`
+     * - `rowId` 接受业务主键或内核 id（number / string）
+     */
+    getCellSpan(rowId: RowId, colId: string): CellSpanInfo | null;
+    /**
+     * 滚动使指定**行下标**（`rowsToDisplay` 中的 index）进入视口。
+     *
+     * @param index 0-based 行下标，非 rowId
+     * @param position 对齐方式，默认 `'middle'`
+     */
+    ensureIndexVisible(index: number, position?: EnsureIndexVisiblePosition): void;
+    /**
+     * 按 rowId 获取行节点快照。
+     *
+     * @param id 业务主键或内核 id（number / string）；不存在时返回 `undefined`
+     */
+    getRowNode(id: RowId): RowNode | undefined;
+    /**
+     * 读取当前渲染与滚动指标（验收 / 调试用途）。
+     *
+     * 含视口行数、scrollTop、首末可见行下标、最近一次 setData 耗时等。
+     */
+    getMetrics(): GridMetrics;
+    /**
+     * 开启批量更新：多次 `applyTransaction` / `addRows` 合并为一次重绘。
+     *
+     * 须与 {@link endUpdate} 配对调用。
+     */
+    beginUpdate(): void;
+    /** 结束批量更新并 flush 累积的事务。 */
+    endUpdate(): void;
+    /**
+     * 编程式滚动视口。
+     *
+     * @param scrollTop 垂直滚动位置（px）
+     * @param scrollLeft 水平滚动位置（px）；省略则保持当前值
+     */
+    scrollTo(scrollTop: number, scrollLeft?: number): void;
+    /**
+     * 编程式进入单元格编辑。
+     *
+     * @param params.rowIndex `rowsToDisplay` 中的 0-based 行下标
+     * @param params.colKey 列 `colId` 或 `prop`
+     *
+     * 列不可编辑或该行正在行编辑模式时无效果。
+     */
+    startEditingCell(params: {
+        rowIndex: number;
+        colKey: string;
+    }): void;
+    /**
+     * 结束当前编辑会话。
+     *
+     * @param cancel `true` 丢弃修改并退出；`false`（默认）尝试提交。
+     * @returns 异步提交完成时 resolve；无编辑态时立即 resolve
+     */
+    stopEditing(cancel?: boolean): Promise<void>;
+    /** 是否存在任意单元格 / 行处于编辑态。 */
+    isEditing(): boolean;
+    /** 是否正在异步提交（commit 管线进行中）。提交期间 Tab 导航等行为受限。 */
+    isCommitting(): boolean;
+    /**
+     * 中断进行中的异步提交，保持编辑态与编辑器焦点。
+     *
+     * 触发 `editCommitAborted` 事件。
+     */
+    cancelCommit(): void;
+    /**
+     * 当前编辑会话阶段。
+     *
+     * - `'idle'` — 无编辑
+     * - `'editing'` — 编辑中
+     * - `'committing'` — 异步提交中
+     * - `'cancelling'` — 取消中
+     */
+    getEditSessionPhase(): EditSessionPhase;
+    /** 当前主编辑单元格；无编辑时 `null`。rowId 为业务类型（与 data[rowKey] 一致，临时行为 null）。 */
+    getEditingCell(): {
+        rowId: BusinessRowId;
+        colId: string;
+    } | null;
+    /** 行编辑模式下所有正在编辑的单元格位置列表。 */
+    getEditingCells(): EditingCellPosition[];
+    /**
+     * 向当前 Grid 实例注册命名单元格编辑器。
+     *
+     * 列定义 `cellEditor: 'myEditor'` 时优先解析实例级注册，再回退全局注册表。
+     */
+    registerCellEditor(name: string, editor: CellEditorFn): void;
+    /** 注销实例级编辑器；成功返回 `true`。 */
+    unregisterCellEditor(name: string): boolean;
+    /**
+     * 校验全表或指定行的持久化数据。
+     *
+     * 扫描可编辑列的 `cellValidator` 与 Grid 级 `rowValidator`；
+     * 默认更新 invalid 视觉反馈（`showFeedback: false` 可仅返回结果）。
+     */
+    validate(options?: ValidateGridOptions): Promise<GridValidationResult>;
+    /** 校验指定行列表（语义同 {@link validate} 的 `rowIds` 分支）。 */
+    validateRows(options: ValidateRowsOptions): Promise<GridValidationResult>;
+    /**
+     * 校验指定单元格列表（不跑 rowValidator）。
+     *
+     * `cells[].rowId` 接受 number / string。
+     */
+    validateCells(options: ValidateCellsOptions): Promise<GridValidationResult>;
+    /** 清除全表或指定行的校验视觉反馈。 */
+    clearValidation(options?: ClearValidationOptions): void;
+    /** 清除指定行的校验视觉反馈。 */
+    clearRowValidation(options: ClearRowValidationOptions): void;
+    /** 清除指定单元格的校验视觉反馈。 */
+    clearCellValidation(options: ClearCellValidationOptions): void;
+    /**
+     * 切换或设置行的 checkbox 选中状态（行选择列 / `SelectionService`）。
+     *
+     * @param rowIds 单个或批量 rowId（number / string）
+     * @param selected 省略时 **toggle**；`true` 选中；`false` 取消选中
+     * @param force `true` 时忽略 `isRowSelectable`：
+     *   - 选中：可操作 disabled 行；
+     *   - 取消：可强制取消 disabled 已选行；
+     *   - 已选中 + `selected: true` 时不重复 toggle
+     *
+     * 变更时 emit `selectionChanged`。disabled 行默认不可通过本 API 取消选中（须 force）。
+     */
+    toggleRowSelection(rowIds: RowIdInput, selected?: boolean, force?: boolean): void;
+    /**
+     * 表头全选 checkbox 操作（`rowSelection: 'multiple'` 时有效）。
+     *
+     * @param selected 省略时 **toggle**；
+     *   `true` 选中当前可见且可选的行；
+     *   `false` 取消可见可选行（**保留** disabled 已选行）
+     */
+    toggleAllSelection(selected?: boolean): void;
+    /**
+     * 设置索引列辅助定位（`IndexFocusService`），不触发鼠标拖拉。
+     *
+     * @param rowIds 单个或批量 rowId；传空数组 `[]` 清除定位
+     *
+     * - `focusMode: 'single'` 时仅保留首个有效 id。
+     * - 变更时 emit `indexFocusChanged`。
+     * - 若开启 `syncToSelectionColumn` 且模式兼容，会单向同步到行选择列（跳过不可选行）。
+     *
+     * 须启用 `showIndexColumn`；未启用时为 no-op。
+     */
+    setIndexFocus(rowIds: RowIdInput): void;
+    /** 展开主行；非 master 或未启用 `masterDetail` 时返回 `false`。 */
+    expandRow(rowId: RowId): boolean;
+    /** 折叠主行；未展开或未启用时返回 `false`。 */
+    collapseRow(rowId: RowId): boolean;
+    /** 主行是否已展开。 */
+    isRowExpanded(rowId: RowId): boolean;
+    /** 展开当前 display 中全部可展开 master 行。 */
+    expandAll(): void;
+    /** 折叠全部已展开主行 / 分组（取决于启用的能力）。 */
+    collapseAll(): void;
+    /** 设置分组列顺序；需 `rowGrouping: true`。触发 `rowGroupChanged`。 */
+    setRowGroupColumns(colIds: readonly string[]): void;
+    /** 当前分组列 colId 列表。 */
+    getRowGroupColumns(): readonly string[];
+    /** 展开分组节点；未启用 rowGrouping 或 groupId 无效时返回 `false`。 */
+    expandGroup(groupId: string): boolean;
+    /** 折叠分组节点。 */
+    collapseGroup(groupId: string): boolean;
+    /** 分组是否已展开。 */
+    isGroupExpanded(groupId: string): boolean;
+    /** 展开 tree 节点；未启用 tree 时返回 `false`。 */
+    expandNode(rowId: RowId): boolean;
+    /** 折叠 tree 节点。 */
+    collapseNode(rowId: RowId): boolean;
+    /** tree 节点是否已展开。 */
+    isNodeExpanded(rowId: RowId): boolean;
+    /** 查询行的 dataPath；未启用 tree 时返回 `undefined`。 */
+    getDataPath(rowId: RowId): string[] | undefined;
+    /** 读取批注；无则 `undefined`。 */
+    getCellComment(rowId: RowId, colId: string): CellComment | undefined;
+    /** 设置或删除批注（`comment=null/undefined`）；`source` 记为 `api`。 */
+    setCellComment(rowId: RowId, colId: string, comment: CellComment | null | undefined): Promise<void>;
+    /** 刷新可见 cell 批注角标；popup 不强制重建。 */
+    refreshCellComments(params?: RefreshCellCommentsParams): void;
+    /** 读取当前 cell range 列表（0..n）。 */
+    getCellRanges(): CellRange[];
+    /** Phase 24.1 · 当前框选聚合统计；无选区或未开框选时返回 null。 */
+    getCellSelectionAggregation(): CellSelectionAggregation | null;
+    /** 清除全部 cell range。 */
+    clearCellSelection(): void;
+    /** 追加一个 cell range（非法参数忽略）。 */
+    addCellRange(params: CellRange): void;
+    /** 复制当前选区到系统剪贴板（TSV）。 */
+    copySelectedRangeToClipboard(): void;
+    /** 从系统剪贴板粘贴到选区起点。 */
+    pasteFromClipboard(): Promise<void>;
+    /** 等价 `setGridOption('loading', true)`。 */
+    showLoadingOverlay(): void;
+    /** 强制显示 noRows overlay，直至 `hideOverlay()`。 */
+    showNoRowsOverlay(): void;
+    /**
+     * 隐藏当前 overlay。
+     * noMatchingRows 仅随 filter/数据恢复自动隐藏；loading=true 时无效。
+     */
+    hideOverlay(): void;
+    /** 是否有 overlay 正在显示。 */
+    isOverlayShowing(): boolean;
+    /** 当前 overlay 类型；无 overlay 时返回 `null`。 */
+    getOverlayType(): OverlayType | null;
+    /** Phase 21 · 重算可见单元格 disabled 投影（class · inline 控件 · aria） */
+    refreshDisabledState(params?: RefreshDisabledStateParams): void;
+    /** Phase 26 · 重算可见单元格 backgroundColor / color 投影 */
+    refreshCellStyles(params?: RefreshCellStylesParams): void;
+    /**
+     * 销毁 Grid 实例：解绑监听、取消编辑、清理 DOM。
+     *
+     * 组件 `onUnmounted` 时自动调用；手动调用后不可再使用 API。
+     */
+    destroy(): void;
+    /**
+     * 订阅 Grid 事件。
+     *
+     * @returns 取消订阅函数
+     *
+     * @example
+     * ```ts
+     * const off = api.on('selectionChanged', ({ selectedRowIds }) => { ... })
+     * off()
+     * ```
+     */
+    on<T extends GridEventType>(type: T, handler: GridEventHandler<T>): () => void;
+}
+
+/**
+ * 边框样式（默认 `border`）
+ * - `border`：表头 / 表体单元格全网格线
+ * - `none`：无单元格线；表头与表体保留底部分隔线
+ * - `linear`：表头 / 表体单元格仅底部分隔线
+ */
+export declare type GridBorder = 'border' | 'none' | 'linear';
+
+/** 单元格位置（rowId + colId） */
+export declare interface GridCellPosition {
+    rowId: RowId;
+    colId: string;
+}
+
+export declare type GridEventHandler<T extends GridEventType> = (event: GridEventMap[T]) => void;
+
+export declare interface GridEventMap {
+    bodyScroll: BodyScrollEvent;
+    sortChanged: SortChangedEvent;
+    filterChanged: FilterChangedEvent;
+    columnMoved: ColumnMovedEvent;
+    columnResized: ColumnResizedEvent;
+    columnPinned: ColumnPinnedEvent;
+    columnHiddenChanged: ColumnHiddenChangedEvent;
+    cellClicked: CellClickedEvent;
+    rowClicked: RowClickedEvent;
+    rowDoubleClicked: RowDoubleClickedEvent;
+    cellFocused: CellFocusedEvent;
+    selectionChanged: SelectionChangedEvent;
+    indexFocusChanged: IndexFocusChangedEvent;
+    cellValueChanged: CellValueChangedEvent;
+    cellEditingStarted: CellEditingStartedEvent;
+    cellEditingStopped: CellEditingStoppedEvent;
+    rowEditingStarted: RowEditingStartedEvent;
+    rowEditingStopped: RowEditingStoppedEvent;
+    rowValueChanged: RowValueChangedEvent;
+    cellCommitStarted: CellCommitStartedEvent;
+    cellCommitFinished: CellCommitFinishedEvent;
+    editCommitAborted: EditCommitAbortedEvent;
+    rowCommitStarted: RowCommitStartedEvent;
+    rowCommitFinished: RowCommitFinishedEvent;
+    cellValidationFailed: CellValidationFailedEvent;
+    rowValidationFailed: RowValidationFailedEvent;
+    rowsAdded: RowsAddedEvent;
+    rowsRemoved: RowsRemovedEvent;
+    rowIdPromoted: RowIdPromotedEvent;
+    rowMoved: RowMovedEvent;
+    rowDragEnd: RowDragEndEvent;
+    rowDragCommitStarted: RowDragCommitStartedEvent;
+    rowDragCommitFinished: RowDragCommitFinishedEvent;
+    rowHeightChanged: RowHeightChangedEvent;
+    rowExpanded: RowExpansionChangedEvent;
+    rowCollapsed: RowExpansionChangedEvent;
+    rowGroupOpened: RowGroupOpenedEvent;
+    rowGroupChanged: RowGroupChangedEvent;
+    treeNodeOpened: TreeNodeOpenedEvent;
+    treeChildrenLoading: TreeChildrenLoadingEvent;
+    treeChildrenLoaded: TreeChildrenLoadedEvent;
+    treeChildrenLoadFailed: TreeChildrenLoadFailedEvent;
+    cellCommentChanged: CellCommentChangedEvent;
+    cellSelectionChanged: CellSelectionChangedEvent;
+    cellSelectionDeleteStart: CellSelectionDeleteStartEvent;
+    cellSelectionDeleteEnd: CellSelectionDeleteEndEvent;
+    overlayShown: OverlayShownEvent;
+    overlayHidden: OverlayHiddenEvent;
+}
+
+export declare type GridEventType = 'bodyScroll' | 'sortChanged' | 'filterChanged' | 'columnMoved' | 'columnResized' | 'columnPinned' | 'cellClicked' | 'rowClicked' | 'rowDoubleClicked' | 'cellFocused' | 'selectionChanged' | 'indexFocusChanged' | 'cellValueChanged' | 'cellEditingStarted' | 'cellEditingStopped' | 'rowEditingStarted' | 'rowEditingStopped' | 'rowValueChanged' | 'cellCommitStarted' | 'cellCommitFinished' | 'editCommitAborted' | 'rowCommitStarted' | 'rowCommitFinished' | 'cellValidationFailed' | 'rowValidationFailed' | 'rowsAdded' | 'rowsRemoved' | 'rowIdPromoted' | 'rowMoved' | 'rowDragEnd' | 'rowDragCommitStarted' | 'rowDragCommitFinished' | 'rowHeightChanged' | 'rowExpanded' | 'rowCollapsed' | 'rowGroupOpened' | 'rowGroupChanged' | 'treeNodeOpened' | 'treeChildrenLoading' | 'treeChildrenLoaded' | 'treeChildrenLoadFailed' | 'cellCommentChanged' | 'cellSelectionChanged' | 'cellSelectionDeleteStart' | 'cellSelectionDeleteEnd' | 'columnHiddenChanged' | 'overlayShown' | 'overlayHidden';
+
+/** 水平对齐；默认 center */
+export declare type GridHorizontalAlign = 'left' | 'center' | 'right';
+
+/** Grid 运行时性能指标（Playground / 验收用） */
+export declare interface GridMetrics {
+    /** 数据总行数（过滤后显示行数） */
+    rowCount: number;
+    /** 源数据总行数（过滤前） */
+    sourceRowCount: number;
+    /** 列数 */
+    columnCount: number;
+    /** 活跃行 DOM 数（行池） */
+    activeDomRowCount: number;
+    /** 表体单元格 DOM 数 */
+    domCellCount: number;
+    /** 当前 scrollTop（px） */
+    scrollTop: number;
+    /** 当前 scrollLeft（px） */
+    scrollLeft: number;
+    /** 内容区总高度（px） */
+    totalHeight: number;
+    /** 内容区总宽度（px） */
+    totalWidth: number;
+    /** 渲染窗口首行索引 */
+    renderedFirstRow: number;
+    /** 渲染窗口末行索引 */
+    renderedLastRow: number;
+    /** 渲染窗口首列索引 */
+    renderedFirstCol: number;
+    /** 渲染窗口末列索引 */
+    renderedLastCol: number;
+    /** 最近一次 setData 耗时（ms） */
+    lastSetDataMs: number;
+}
+
+/** 圆角：false/0 无圆角；true 跟随 size；number 自定义 px。默认 false */
+export declare type GridRounded = number | boolean;
+
+/** 尺寸 preset；rowHeight / headerHeight 未显式传入时由 size 推导 */
+export declare type GridSize = 'mini' | 'small' | 'default' | 'large';
+
+/** 主题 preset：`light` 亮色（默认）；`dark` 暗色语义 token */
+export declare type GridTheme = 'light' | 'dark';
+
+export declare interface GridValidationCellError {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    colId: string;
+    errors: string[];
+}
+
+export declare interface GridValidationResult {
+    valid: boolean;
+    cellErrors: GridValidationCellError[];
+}
+
+/** 垂直对齐；默认 center */
+export declare type GridVerticalAlign = 'top' | 'center' | 'bottom';
+
+/** 分组 aggregate 单元格结果（与 SummaryCellResult 同形） */
+export declare interface GroupAggCellResult {
+    value: unknown;
+    formattedValue: string;
+}
+
+export declare type GroupAggValuesMap = Record<string, GroupAggCellResult>;
+
+export declare type GroupCellRendererFn = (params: GroupCellRendererParams, ctx: GroupCellRendererMountContext) => string | HTMLElement | void | null | undefined;
+
+export declare interface GroupCellRendererMountContext {
+    mountEl: HTMLElement;
+    clear(): void;
+}
+
+/** 分组单元格渲染入参（auto group 列 / groupCellRenderer） */
+export declare interface GroupCellRendererParams {
+    rowKind: 'groupHeader' | 'groupFooter';
+    groupId: string;
+    groupField: string;
+    groupKey: string;
+    groupLevel: number;
+    groupLeafCount: number;
+    expanded: boolean;
+    aggValues?: GroupAggValuesMap;
+}
+
+/** 同级 group 顺序比较器；缺省按 groupKey localeCompare（blank 置末） */
+export declare type GroupComparatorFn = (params: GroupComparatorParams) => number;
+
+/** 同级 group 节点排序入参（对标 AG initialGroupOrderComparator） */
+export declare interface GroupComparatorParams {
+    valueA: string;
+    valueB: string;
+    colId: string;
+    field: string;
+    level: number;
+}
+
+export declare type GroupDisplayType = 'singleColumn' | 'multipleColumns';
+
+export declare type GroupKeyCreatorFn = (params: GroupKeyCreatorParams) => string;
+
+/** 分组键归一化入参 */
+export declare interface GroupKeyCreatorParams {
+    field: string;
+    colId: string;
+    value: unknown;
+    data: RowData;
+}
+
+export declare type HasTreeChildrenFn = (params: HasTreeChildrenParams) => boolean;
+
+export declare interface HasTreeChildrenParams {
+    data: RowData;
+    dataPath: string[];
+    treeLevel: number;
+}
+
+export declare type HeaderTooltipValueGetter = (params: HeaderTooltipValueGetterParams) => string | null | undefined;
+
+export declare interface HeaderTooltipValueGetterParams {
+    colId: string;
+    column: Column;
+    headerLabel: string;
+}
+
+/**
+ * CellSpanService 窄接口（块 5 实现）。
+ * 块 0 仅定义契约，供后续渲染 / 焦点 / API 依赖。
+ */
+export declare interface ICellSpanService {
+    readonly active: boolean;
+    refresh(): void;
+    getColSpan(rowId: CellSpanRowKey, colId: string): number;
+    getCellSpan(rowId: string, colId: string): CellSpanInfo | null;
+    /** 该格是否被其它 head 覆盖（不应渲染） */
+    isCovered(rowId: string, colId: string): boolean;
+    /** 导航/编辑：将被盖位置映射到 head */
+    normalizePosition(rowId: string, colId: string): CellSpanPosition;
+    /** 渲染用：解析纵向 span（rowSpan 优先于 spanRows） */
+    resolveVerticalSpan(rowNode: RowNode, column: Column): RowSpanHeadInfo;
+}
+
+/** 索引列配置 */
+export declare interface IndexColumnOptions {
+    /** 表头文案；默认空字符串 */
+    label?: string;
+    /** 列宽 px；默认 40；小于 40 时钳制为 40 */
+    width?: number;
+    /** 起始序号（1-based 展示 = rowIndex + start）；默认 1 */
+    start?: number;
+    /**
+     * 辅助定位模式：single / multiple（multiple 支持 Ctrl/Shift/拖拉范围）
+     * 默认 multiple（Excel 行号式交互）
+     */
+    focusMode?: 'single' | 'multiple';
+    /**
+     * 索引列定位是否单向同步到行选择列（业务选中）；core 默认 false，MagicGrid 组件层默认 true。
+     * 仅当 indexColumn.focusMode 与 rowSelection 同为 single 或同为 multiple 时生效。
+     * 仅用户在索引列上操作（点击/拖选/再次点击取消）时同步；点击其他区域清除索引定位不同步行选择列。
+     */
+    syncToSelectionColumn?: boolean;
+    /** 表头水平对齐；默认 center */
+    headerAlign?: GridHorizontalAlign;
+    /** 表头垂直对齐；默认 center */
+    headerValign?: GridVerticalAlign;
+    /** 表体水平对齐；默认 center */
+    align?: GridHorizontalAlign;
+    /** 表体垂直对齐；默认 center */
+    valign?: GridVerticalAlign;
+    /** footer 水平对齐；默认 center */
+    footerAlign?: GridHorizontalAlign;
+    /** footer 垂直对齐；默认 center */
+    footerValign?: GridVerticalAlign;
+    /**
+     * 自定义序号展示；入参为 rowsToDisplay 下标。
+     * 缺省：(rowIndex) => String(rowIndex + start)
+     */
+    index?: (rowIndex: number) => number | string;
+    /**
+     * 在索引列 cell 内显示行拖拽把柄；默认 false。
+     * 需配合 Grid `rowDragManaged` 或监听 `rowDragEnd` 自行改序。
+     */
+    showRowDragHandle?: boolean;
+    /**
+     * 索引列底边可拖拽调整行高；默认 false。
+     * 对标 AG Grid Row Numbers `enableRowResizer`。
+     */
+    enableRowResizer?: boolean;
+}
+
+export declare interface IndexFocusChangedEvent {
+    focusedRowIds: BusinessRowId[];
+}
+
+export declare type InvalidEditValueMode = 'block' | 'revert' | 'keep';
+
+/** 自定义 overlay 组件协议（对标 AG IOverlayComp） */
+export declare interface IOverlayComp {
+    getGui(): HTMLElement;
+    init?(params: IOverlayParams): void;
+    refresh?(params: IOverlayParams): boolean;
+    destroy?(): void;
+}
+
+export declare interface IOverlayParams {
+    overlayType: OverlayType;
+    api: GridApi;
+    /** 无数据 / 无匹配 / 加载文案（默认中文 · 可被 template/组件覆盖） */
+    overlayText?: string;
+}
+
+export declare type IsRowDisabledFn<TData = RowData> = (params: IsRowDisabledParams<TData>) => boolean;
+
+/** 行级禁用判定参数 */
+export declare interface IsRowDisabledParams<TData = RowData> {
+    data: TData;
+    rowId: BusinessRowId;
+    /** display 行索引（可选 · 便于 UI 规则） */
+    rowIndex?: number;
+}
+
+export declare type IsRowMasterFn = (params: IsRowMasterParams) => boolean;
+
+/** 是否为主行（可展示 expand 控件） */
+export declare interface IsRowMasterParams {
+    rowId: BusinessRowId;
+    data: RowData;
+    rowIndex: number;
+}
+
+/** 自定义 tooltip 组件协议（对标 AG ITooltipComp · 块 9 挂载） */
+export declare interface ITooltipComp {
+    getGui(): HTMLElement;
+    init?(params: ITooltipParams): void;
+    refresh?(params: ITooltipParams): boolean;
+    destroy?(): void;
+}
+
+export declare interface ITooltipParams {
+    location: TooltipLocation;
+    value: unknown;
+    valueFormatted: string | null;
+    colId?: string;
+    rowId?: string;
+    data?: Record<string, unknown>;
+    hideTooltipCallback: () => void;
+    api: GridApi;
+}
+
+export declare type LoadTreeChildrenFn = (params: LoadTreeChildrenParams) => Promise<RowData[] | void> | RowData[] | void;
+
+export declare interface LoadTreeChildrenParams {
+    parentRowId: BusinessRowId;
+    parentData: RowData;
+    dataPath: string[];
+    treeLevel: number;
+    signal: AbortSignal;
+}
+
+/** MagicGrid 组件实例暴露的方法（通过 ref 调用） */
+export declare interface MagicGridExpose {
+    /** GridApi 响应式引用；挂载后可用 */
+    api: Ref<GridApi | undefined>;
+    /** 读取 Grid 运行时性能指标 */
+    getMetrics: () => GridMetrics | undefined;
+    /** 滚动到指定 scrollTop / scrollLeft（px） */
+    scrollTo: (scrollTop: number, scrollLeft?: number) => void;
+    /** 设置排序模型并重算 rowsToDisplay */
+    setSortModel: (model: SortModelItem[]) => void;
+    /** 读取当前排序模型 */
+    getSortModel: () => SortModelItem[];
+    /** 设置筛选模型并重算 rowsToDisplay */
+    setFilterModel: (model: FilterModel) => void;
+    /** 导出当前表格业务数据；等价于 `api.getData()` */
+    getData: (options?: GetDataOptions) => RowData[];
+    /** 批量增删改行；返回本次事务影响的 RowNode 快照 */
+    applyTransaction: (transaction: RowTransaction) => Promise<RowNodeTransaction | undefined>;
+    /** 开启批量更新（合并多次 DOM 刷新） */
+    beginUpdate: () => void;
+    /** 结束批量更新并刷新 */
+    endUpdate: () => void;
+    /** 滚动使指定 display 行可见 */
+    ensureIndexVisible: (index: number, position?: 'top' | 'bottom' | 'middle') => void;
+    /** 立即刷新待处理的动画帧任务 */
+    flushFrames: () => void;
+}
+
+/** MagicGrid 组件 props；`TData` 为行数据类型，用于列定义与回调参数推导 */
+export declare interface MagicGridProps<TData extends RowData = RowData> {
+    /** 列定义 */
+    columns: ColumnDef<TData>[];
+    /** 行数据 */
+    data: TData[];
+    /** Grid 实例级命名编辑器（colId 引用 cellEditor: 'name' 时解析；优先于全局注册表） */
+    cellEditorRegistry?: Record<string, CellEditorFn>;
+    /** 行数据主键字段名（PK），用于行池复用与增量更新 */
+    rowKey?: string;
+    /** 斑马纹 */
+    stripe?: boolean;
+    /**
+     * 边框样式（默认 `border`）
+     * - border：表头 / 表体单元格全网格线（1px）
+     * - none：无单元格线；表头与表体保留底部分隔线
+     * - linear：表头 / 表体单元格仅底部分隔线
+     */
+    border?: GridBorder;
+    /**
+     * 主题 preset；默认 `light`（亮色）。
+     * `dark` 切换暗色语义 token（`--mg-color-*`）。
+     */
+    theme?: GridTheme;
+    /**
+     * 尺寸 preset；默认 `default`。
+     * rowHeight / headerHeight 未显式传入时，由 size 推导。
+     */
+    size?: GridSize;
+    /**
+     * 容器圆角（px）；默认 `false`（无圆角）
+     * - `false` / `0`：圆角为 0
+     * - `true`：使用当前 size preset 的圆角
+     * - `number`：自定义圆角像素值
+     */
+    rounded?: GridRounded;
+    /** 固定行高（px）；显式传入时覆盖 size preset */
+    rowHeight?: number;
+    /** 表头高度（px）；显式传入时覆盖 size preset */
+    headerHeight?: number;
+    /** 是否显示最左侧索引列；默认 false */
+    showIndexColumn?: boolean;
+    /** 索引列配置；showIndexColumn=true 时生效；MagicGrid 层 syncToSelectionColumn 默认 true */
+    indexColumn?: IndexColumnOptions;
+    /** 是否展示表尾汇总行；默认 false */
+    showSummary?: boolean;
+    /**
+     * 汇总计算范围；默认 `displayed`（rowsToDisplay，尊重 filter / sort）
+     * - displayed：当前可见行集
+     * - all：sourceRows 全量（忽略 filter）
+     */
+    summaryScope?: SummaryScope;
+    /** 汇总行高度（px）；未传时跟随 rowHeight / size preset */
+    summaryRowHeight?: number;
+    /**
+     * 全局汇总方法（优先级高于列级 summaryAgg）
+     * 返回 colId → 展示值；首列缺省可显示「合计」
+     */
+    summaryMethod?: SummaryMethod;
+    /** 表头水平对齐（全局默认）；默认 center */
+    headerAlign?: GridHorizontalAlign;
+    /** 表头垂直对齐（全局默认）；默认 center */
+    headerValign?: GridVerticalAlign;
+    /** 表体水平对齐（全局默认）；默认 center */
+    align?: GridHorizontalAlign;
+    /** 表体垂直对齐（全局默认）；默认 center */
+    valign?: GridVerticalAlign;
+    /** 表尾汇总水平对齐（全局默认）；默认 center */
+    footerAlign?: GridHorizontalAlign;
+    /** 表尾汇总垂直对齐（全局默认）；默认 center */
+    footerValign?: GridVerticalAlign;
+    /** 是否允许键盘/鼠标将焦点导航到表头；默认 false */
+    navigateHeader?: boolean;
+    /** 是否允许键盘/鼠标将焦点导航到表尾汇总行；默认 false（需 showSummary: true） */
+    navigateFooter?: boolean;
+    /** 行虚拟化缓冲行数 */
+    rowBuffer?: number;
+    /** 行选择模式，false 禁用；对象形式支持 groupSelectsChildren */
+    rowSelection?: RowSelectionInput;
+    /** 行选择列配置；rowSelection !== false 时生效 */
+    selectionColumn?: SelectionColumnOptions;
+    /**
+     * 行选择列：行 checkbox 是否可勾选；函数入参含 `data` / `rowId` / `rowIndex`。
+     * 省略时全部可选。
+     */
+    selectable?: SelectableFn;
+    /** 行选择列：数据刷新后是否保留选中行；默认 false */
+    reserveSelection?: boolean;
+    /** Grid 级 quick filter 文本 */
+    quickFilterText?: string;
+    /**
+     * 是否允许列筛选；默认 `false`。
+     * 列级 `columns[].filterable` **优先于**本配置；系统列（索引 / 行选择等）恒为 false。
+     */
+    filterable?: boolean;
+    /** 表头下方 Floating Filter 行；默认 `false` */
+    floatingFilter?: boolean;
+    /** 值选择搜索时的勾选投影模式；默认 `current` */
+    filterSetValueMode?: FilterSetValueMode;
+    /** 日期列值选择展示方式；默认 `tree` */
+    filterSetDateLayoutMode?: FilterSetDateLayoutMode;
+    /** 编辑范围：cell 单格 / row 整行 */
+    editBehavior?: CellEditBehavior;
+    /** 进入编辑态的触发方式，默认 singleClick */
+    editType?: CellEditType;
+    /** 校验失败后：block 保持编辑 / revert 退出并恢复旧值 */
+    invalidEditValueMode?: InvalidEditValueMode;
+    /** 行编辑跨字段校验 */
+    rowValidator?: RowValidator;
+    /** 异步行 CRUD 持久化钩子 */
+    asyncRowMutation?: AsyncRowMutationHandlers;
+    /** 容器高度 */
+    height?: string | number;
+    /** 容器宽度 */
+    width?: string | number;
+    /**
+     * 初始排序（Grid 挂载 / initGrid 时应用一次）；当前仅使用首项
+     */
+    defaultSort?: SortModelItem[];
+    /**
+     * 是否允许用户点击表头排序；默认 `false`。
+     * 列级 `columns[].sortable` **优先于**本配置；系统列（索引 / 行选择）恒为 false。
+     */
+    sortable?: boolean;
+    /** 是否允许用户列表头拖拽重排；默认 true（对齐 AG Grid；`:column-movable="false"` 关闭） */
+    columnMovable?: boolean;
+    /**
+     * 是否允许用户拖拽调整列宽；默认 `true`（对齐 AG Grid `defaultColDef.resizable`）。
+     * 列级 `columns[].resizable` **优先于**本配置；系统列（索引 / 行选择）恒为 false。
+     */
+    resizable?: boolean;
+    /**
+     * 默认 Shift 模式：拖拽列宽时相邻列反向补偿，总宽不变。
+     * 对标 AG Grid `colResizeDefault: 'shift'`。
+     */
+    colResizeDefault?: 'shift';
+    /** 双击 resize 把柄 auto-size 时跳过表头宽度；对标 AG Grid skipHeaderOnAutoSize */
+    skipHeaderOnAutoSize?: boolean;
+    /** auto-size 内容测量额外 padding（px）；对标 AG Grid autoSizePadding */
+    autoSizePadding?: number;
+    /** 挂载 / 首屏 auto-size 策略；对标 AG Grid autoSizeStrategy */
+    autoSizeStrategy?: AutoSizeStrategy;
+    /** 默认 false（drag 过程中 live move，对齐 AG Grid）。
+     * true → 仅 mouseup 提交列序。
+     */
+    suppressMoveWhenColumnDragging?: boolean;
+    /** 默认 false；true 关闭列移动 transition */
+    suppressColumnMoveAnimation?: boolean;
+    /**
+     * 默认 false。
+     * true → 允许 drag / API 跨 fixed lane 并更新列 `fixed`。
+     */
+    allowCrossLaneColumnMove?: boolean;
+    /** 默认 false；true → 未排序 sortable 列 hover 显示 faint 双三角 */
+    showUnsortedSortHintOnHover?: boolean;
+    /** 是否显示底部状态栏；默认 true */
+    showStatusBar?: boolean;
+    /**
+     * 状态栏高度：`'auto'` 跟随 size preset（默认）；number 为自定义 px。
+     */
+    statusBarHeight?: StatusBarHeightInput;
+    /** 框选时在状态栏展示平均值/计数/求和；cellSelection 开时默认 true */
+    showStatusBarRangeAggregation?: boolean;
+    /** 框选聚合 panel 位置；默认 `right`（右栏内侧） */
+    statusBarRangeAggregationPosition?: StatusBarRangeAggregationPosition;
+    /**
+     * 平均值 / 求和展示小数位数。
+     * 传 number 时同时作用于两者；默认 2。
+     */
+    statusBarRangeAggregationPrecision?: StatusBarRangeAggregationPrecisionInput;
+    /**
+     * 启用 managed 行拖拽：拖拽过程中实时改 source 顺序；默认 true。
+     * 设为 false 时仅 emit `rowDragEnd`，由业务自行改序。
+     * 对标 AG Grid `rowDragManaged`。
+     */
+    rowDragManaged?: boolean;
+    /**
+     * managed 模式 commit 策略：`sync`（默认 live move）| `deferred`（mouseup 后 await onRowDragCommit）。
+     */
+    rowDragCommitMode?: RowDragCommitMode;
+    /**
+     * deferred 模式：mouseup 后、apply 前调用；返回 false 则不写 source。
+     * MagicGrid 亦支持 `:on-row-drag-commit` prop（与 Grid option 等价）。
+     */
+    onRowDragCommit?: RowDragCommitHandler;
+    /**
+     * 行级动态高度（无 DOM）；优先于默认 rowHeight，低于手动 setRowHeight。
+     * 对标 AG Grid `getRowHeight`。
+     */
+    getRowHeight?: GetRowHeightFn;
+    /** 行高下限（px）；未传时跟随 size preset / rowHeight */
+    rowHeightMin?: number;
+    /** 行高上限（px）；未传时无上限 */
+    rowHeightMax?: number;
+    /**
+     * 启用单元格合并。默认 `false`。
+     * `true` 时解析列级 `colSpan` / `rowSpan` / `spanRows`，且行定位改用 `style.top`。
+     * 对标 AG Grid `enableCellSpan`。
+     */
+    enableCellSpan?: boolean;
+    /**
+     * 启用主从展开行。默认 `false`。
+     * 对标 AG Grid `masterDetail`。
+     */
+    masterDetail?: boolean;
+    /** 是否为主行（可展示 expand 控件）；缺省全部 data 行可展开 */
+    isRowMaster?: IsRowMasterFn;
+    /** 默认展开层级：0 = 无；1 = 第一层；-1 = 全部 */
+    masterDefaultExpanded?: number;
+    /** 详情行固定高度（px）；与 detailRowAutoHeight 并存时本字段优先 */
+    detailRowHeight?: number | DetailRowHeightFn;
+    /** 详情行按内容自动撑高 */
+    detailRowAutoHeight?: boolean;
+    /**
+     * false（默认）：详情 overlay 不随 center 横滚。
+     * true：详情嵌入 center lane。
+     */
+    embedFullWidthRows?: boolean;
+    /** 最左展示专用展开列（fixed=left） */
+    showExpandColumn?: boolean;
+    /** 异步提供详情区数据 */
+    getDetailRowData?: GetDetailRowDataFn;
+    /** 自定义详情行渲染器（与 `#detail-row` 插槽二选一） */
+    detailCellRenderer?: DetailCellRendererFn;
+    /**
+     * 启用行分组。默认 `false`。
+     * `true` 且存在 ≥1 个分组字段时生效。
+     */
+    rowGrouping?: boolean;
+    /** 默认展开分组层级：0 = 全折叠；1 = 第一层；-1 = 全部展开。默认 `-1` */
+    groupDefaultExpanded?: number;
+    /** 是否展示 groupHeader 分组标题行。默认 `false` */
+    showGroupHeader?: boolean;
+    /** 是否为每个已展开的分组展示 footer 汇总行。默认 `false` */
+    showGroupFooter?: boolean;
+    /**
+     * 分组展示模式。当前仅支持 `singleColumn`。
+     * 默认 `singleColumn`。
+     */
+    groupDisplayType?: GroupDisplayType;
+    /** 是否展示 auto group 系统列；默认 false */
+    showGroupColumn?: boolean;
+    /** 覆盖 auto group 列的 colDef */
+    autoGroupColumnDef?: Partial<ColumnDef<TData>>;
+    /** 分组键归一化（可选） */
+    groupKeyCreator?: GroupKeyCreatorFn;
+    /**
+     * 同级 group 节点排序。缺省按 groupKey 升序（blank 置末）。
+     * 自定义时全权负责（含 blank）；不改变展示键。
+     */
+    groupComparator?: GroupComparatorFn;
+    /** groupFooter 首列展示标签 */
+    groupFooterLabel?: string;
+    /** 自定义分组单元格渲染器 */
+    groupCellRenderer?: GroupCellRendererFn;
+    /**
+     * 启用树形表格。默认 `false`。
+     * 与 `rowGrouping` 互斥。
+     */
+    tree?: boolean;
+    /** 树形路径回调；`tree: true` 时必填 */
+    getDataPath?: GetDataPathFn;
+    /**
+     * 树形 managed 行拖拽范围。默认 `siblings`（仅同 parent 兄弟换序）；
+     * `hierarchy` 允许跨层级改父节点（需 `setDataPath` 写回路径）。
+     */
+    treeDragScope?: TreeDragScope;
+    /** hierarchy 模式下写回 dataPath；缺省时若 data.pathSegments 为数组则自动更新 */
+    setDataPath?: SetDataPathFn;
+    /** 是否展示 tree 系统列。默认 `true` */
+    showTreeColumn?: boolean;
+    /** 覆盖 tree 系统列 colDef */
+    autoTreeColumnDef?: Partial<ColumnDef<TData>>;
+    /** 自定义 tree 列展示值 */
+    treeValueGetter?: TreeValueGetterFn;
+    /** 树节点展示列模式。当前仅支持 `singleColumn` */
+    treeDisplayType?: TreeDisplayType;
+    /** 启用树形懒加载 */
+    treeLazyLoad?: boolean;
+    /** lazy 模式：节点是否可能有未加载子行 */
+    hasTreeChildren?: HasTreeChildrenFn;
+    /** lazy 模式：首次展开时拉取子数据 */
+    loadTreeChildren?: LoadTreeChildrenFn;
+    /** 单元格批注数据源；提供即启用 */
+    cellCommentsDataSource?: CellCommentsDataSource;
+    /** 全局抑制批注交互；API 仍可 bypass */
+    suppressCellComments?: boolean;
+    /** 查看已有批注的触发方式；默认 click（点角标 toggle） */
+    cellCommentTrigger?: CellCommentTrigger;
+    /** hover 模式展示延迟 ms；默认 180 */
+    cellCommentShowDelay?: number;
+    /** 离开 cell/popup 后隐藏延迟 ms；默认 220 */
+    cellCommentHideDelay?: number;
+    /** 复制单格时自定义导出值（最高优先级） */
+    processCellForClipboard?: ProcessCellForClipboardFn;
+    /** 粘贴单格时预处理 clipboard 字符串 */
+    processCellFromClipboard?: ProcessCellFromClipboardFn;
+    /** 整表粘贴前处理 TSV 矩阵；return null 取消粘贴 */
+    processDataFromClipboard?: ProcessDataFromClipboardFn;
+    /** 单元格框选；MagicGrid 默认 true（含 enableColumnSelection，handleMode 默认 off），Grid API 未传时为 false */
+    cellSelection?: boolean | CellSelectionOptions;
+    /** 框选复制；cellSelection 开启时默认 true */
+    enableCellCopy?: boolean;
+    /** 框选粘贴；cellSelection 开启时默认 false */
+    enableCellPaste?: boolean;
+    /** 选区涉及列的表头底色；默认 true */
+    enableHeaderHighlight?: boolean;
+    /** 选区行跨度内索引列高亮；默认 true */
+    enableIndexColumnHighlight?: boolean;
+    /** 是否启用溢出 tooltip；默认 true */
+    enableTooltips?: boolean;
+    /** 溢出 tooltip 显示策略；默认 whenTruncated */
+    tooltipShowMode?: TooltipShowMode;
+    /** 首次 hover 展示延迟 ms；默认 500 */
+    tooltipShowDelay?: number;
+    /** 格间切换展示延迟 ms；默认 200 */
+    tooltipSwitchShowDelay?: number;
+    /** 离开后隐藏延迟 ms；默认 3000 */
+    tooltipHideDelay?: number;
+    /** tooltip 内容是否可交互；默认 false */
+    tooltipInteraction?: boolean;
+    /** tooltip 是否跟随鼠标；默认 false */
+    tooltipMouseTrack?: boolean;
+    /** 是否显示 loading overlay；undefined 为挂载后首次 setData 前自动 loading */
+    loading?: boolean;
+    /** 逐项抑制内置 overlay */
+    suppressOverlays?: OverlayType[];
+    /** 抑制 loading overlay */
+    suppressLoadingOverlay?: boolean;
+    /** 抑制无数据 overlay */
+    suppressNoRowsOverlay?: boolean;
+    /** 抑制无匹配行 overlay（filter 后为空） */
+    suppressNoMatchingRowsOverlay?: boolean;
+    /** loading overlay 内置 HTML 模板 */
+    overlayLoadingTemplate?: string;
+    /** 无数据 overlay 内置 HTML 模板 */
+    overlayNoRowsTemplate?: string;
+    /** 无匹配行 overlay 内置 HTML 模板 */
+    overlayNoMatchingRowsTemplate?: string;
+    /** 自定义 loading overlay 组件 */
+    loadingOverlayComponent?: OverlayComponentType;
+    /** loading overlay 组件额外参数 */
+    loadingOverlayComponentParams?: Record<string, unknown>;
+    /** 自定义无数据 overlay 组件 */
+    noRowsOverlayComponent?: OverlayComponentType;
+    /** 无数据 overlay 组件额外参数 */
+    noRowsOverlayComponentParams?: Record<string, unknown>;
+    /** 自定义无匹配行 overlay 组件 */
+    noMatchingRowsOverlayComponent?: OverlayComponentType;
+    /** 无匹配行 overlay 组件额外参数 */
+    noMatchingRowsOverlayComponentParams?: Record<string, unknown>;
+    /** 通用 overlay 组件（按类型分发） */
+    overlayComponent?: OverlayComponentType;
+    /** 通用 overlay 组件额外参数 */
+    overlayComponentParams?: Record<string, unknown>;
+    /** overlay 内容是否可交互（默认可穿透） */
+    overlayInteraction?: boolean;
+    /**
+     * 行级禁用：true 时该行全部数据列 disabled。
+     * 不影响 index / selection / expand / tree / group 系统列。
+     */
+    isRowDisabled?: boolean | IsRowDisabledFn<TData>;
+    /**
+     * 行级样式：对象 = 全表同色；函数 = 按行。
+     * 作用于表体用户数据列与行选择列；表头/表尾/索引列不参与。
+     */
+    rowStyle?: RowStyle<TData>;
+}
+
+/** magic-grid 扩展：validationRules.validator 可为 async */
+export declare interface MagicValidationRule {
+    validator?: (rule: unknown, value: unknown, callback: (error?: string | Error) => void, source: unknown, options: unknown) => void | Promise<void>;
+    message?: string;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    type?: string;
+    [key: string]: unknown;
+}
+
+export declare interface MoveRowOptions {
+    /** 内部 rowId */
+    rowId: string;
+    /** 目标下标 */
+    toIndex: number;
+    /** 下标基准，默认 `source` */
+    indexMode?: RowIndexMode;
+    /** live drag 中间态为 false；mouseup 收尾为 true（默认 true） */
+    finished?: boolean;
+}
+
+/** 数字列算子集 */
+export declare type NumberFilterType = 'equals' | 'notEqual' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'blank' | 'notBlank';
+
+/** 自定义 overlay 工厂（对标 tooltipComponentHost · 块 7 挂载） */
+export declare type OverlayComponentFactory = (params: IOverlayParams, mountEl: HTMLElement) => IOverlayComp | void;
+
+export declare type OverlayComponentType = OverlayComponentFactory;
+
+export declare interface OverlayHiddenEvent {
+    overlayType: OverlayType;
+}
+
+export declare interface OverlayShownEvent {
+    overlayType: OverlayType;
+}
+
+/** `#loading` / `#no-rows` / `#no-matching-rows` 插槽 props */
+export declare interface OverlaySlotParams {
+    /** 当前 overlay 类型 */
+    overlayType: OverlayType;
+    /** GridApi 实例 */
+    api: GridApi;
+    /** 内置 overlay 默认文案（自定义组件可忽略） */
+    overlayText?: string;
+}
+
+/** 内置 overlay 类型（v1） */
+export declare type OverlayType = 'loading' | 'noRows' | 'noMatchingRows';
+
+/** 复制/粘贴 processCell* 回调共享参数 */
+export declare interface ProcessCellClipboardParamsBase {
+    rowIndex: number;
+    colId: string;
+    rowNode: RowNode;
+    column: Column;
+    /** 复制：formatter/raw 候选值；粘贴：clipboard 字符串 */
+    value: unknown;
+    /** 辅助：对任意 raw 值套列 formatter */
+    formatValue: (value: unknown) => string;
+    /** 辅助：对 clipboard 字符串走 valueParser（拒绝时返回 CELL_EDIT_REJECTED） */
+    parseValue: (text: string) => unknown;
+}
+
+export declare type ProcessCellForClipboardFn = (params: ProcessCellForClipboardParams) => unknown;
+
+export declare type ProcessCellForClipboardParams = ProcessCellClipboardParamsBase;
+
+export declare type ProcessCellFromClipboardFn = (params: ProcessCellFromClipboardParams) => unknown;
+
+export declare type ProcessCellFromClipboardParams = ProcessCellClipboardParamsBase & {
+    oldValue: unknown;
+};
+
+export declare type ProcessDataFromClipboardFn = (params: ProcessDataFromClipboardParams) => string[][] | null;
+
+export declare interface ProcessDataFromClipboardParams {
+    data: string[][];
+    anchor: CellPosition;
+}
+
+export declare interface PromoteRowIdOptions {
+    /** 当前 RowNode.id（通常为 __mg_tmp_*） */
+    rowId: RowId;
+    /** 正式业务主键，写入 data[rowKey] 并更新 RowNode.id */
+    businessId: string | number;
+}
+
+export declare type PromoteRowIdResult = {
+    ok: true;
+    rowId: BusinessRowId;
+} | {
+    ok: false;
+    reason: string;
+};
+
+export declare interface RefreshCellCommentsParams {
+    rowIds?: readonly BusinessRowId[];
+    colIds?: readonly string[];
+}
+
+/** refreshCells 定向刷新参数 */
+export declare interface RefreshCellsParams {
+    rowIds?: string[];
+    colIds?: string[];
+    /** 忽略单元格值缓存，强制重绘 */
+    force?: boolean;
+}
+
+export declare interface RefreshCellStylesParams {
+    rowIds?: readonly BusinessRowId[];
+    colIds?: readonly string[];
+}
+
+export declare interface RefreshDisabledStateParams {
+    rowIds?: readonly BusinessRowId[];
+    colIds?: readonly string[];
+}
+
+export declare interface RemoveRowsOptions {
+    /** 内部 rowId 或业务 rowKey 值（number / string） */
+    rowIds?: RowId[];
+    /** 批量下标 */
+    indexes?: number[];
+    indexMode?: RowIndexMode;
+}
+
+/** 列模型上已解析的 filterParams */
+export declare interface ResolvedFilterParams {
+    readonly caseSensitive: boolean;
+    readonly locale?: string;
+}
+
+/** 归一化后的框选聚合小数位数（average / sum 分别指定） */
+export declare interface ResolvedStatusBarRangeAggregationPrecision {
+    /** 平均值展示小数位数 */
+    average: number;
+    /** 求和展示小数位数 */
+    sum: number;
+}
+
+/** 表体数据行单击（不含分组头/详情行/表尾汇总） */
+export declare interface RowClickedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    rowNode: RowNode;
+    /** 触发点击的列 colId */
+    colId: string;
+}
+
+export declare interface RowCommitFinishedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    committed: boolean;
+    aborted?: boolean;
+}
+
+export declare interface RowCommitStartedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    editableColIds: string[];
+}
+
+/** 用户行数据：保持普通对象，禁止 reactive 深代理 */
+export declare type RowData = Record<string, unknown>;
+
+/** 表体数据行双击（不含分组头/详情行/表尾汇总） */
+export declare interface RowDoubleClickedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    rowNode: RowNode;
+    /** 触发双击的列 colId */
+    colId: string;
+}
+
+/** deferred row drag · 传给 onRowDragCommit 的上下文 */
+export declare interface RowDragCommitContext {
+    signal: AbortSignal;
+    commitId: number;
+    rowIds: readonly string[];
+    leaderRowId: string;
+    moves: readonly RowMoveItem[];
+    displayIndex: number;
+    parentRowId?: string | null;
+    siblingIndex?: number;
+    treeLevel?: number;
+    nestUnderRowId?: string | null;
+}
+
+/** deferred row drag · commit 结束（成功时随后 emit rowMoved + rowDragEnd） */
+export declare interface RowDragCommitFinishedEvent {
+    commitId: number;
+    rowId: BusinessRowId;
+    leaderRowId: BusinessRowId;
+    committed: boolean;
+    aborted?: boolean;
+    reason?: string;
+}
+
+export declare type RowDragCommitHandler = (context: RowDragCommitContext) => Promise<RowDragCommitHandlerResult> | RowDragCommitHandlerResult;
+
+export declare type RowDragCommitHandlerResult = boolean | void | {
+    ok: boolean;
+    reason?: string;
+};
+
+/** managed 行拖拽 commit 策略 */
+export declare type RowDragCommitMode = 'sync' | 'deferred';
+
+/** deferred row drag · commit 开始 */
+export declare interface RowDragCommitStartedEvent {
+    rowId: BusinessRowId;
+    rowIds: readonly BusinessRowId[];
+    leaderRowId: BusinessRowId;
+    displayIndex: number;
+    parentRowId?: BusinessRowId | null;
+    siblingIndex?: number;
+    treeLevel?: number;
+}
+
+/** 对标 Phase 15 rowDragEnd 事件 */
+export declare interface RowDragEndEvent {
+    rowId: BusinessRowId;
+    /** 多行 drag 时包含全部 rowId；单行时可省略 */
+    rowIds?: readonly BusinessRowId[];
+    /** drop 时指针所在的 display 插入位（0…rowCount）；-1 表示无效区域 */
+    displayIndex: number;
+    finished: boolean;
+    /**
+     * Phase 19 · 树形 drop 后 leader 行的新父节点 rowId；根层为 `null`。
+     * 仅树形且 drop 有效时提供。
+     */
+    parentRowId?: BusinessRowId | null;
+    /**
+     * Phase 19 · 树形 drop 后在 `parentRowId` 下同级兄弟中的序号（0-based）。
+     * 仅树形且 drop 有效时提供。
+     */
+    siblingIndex?: number;
+    /** Phase 19 · 树形 drop 后 leader 行的 treeLevel（根层 0）；仅树形且 drop 有效时提供 */
+    treeLevel?: number;
+}
+
+export declare interface RowEditChange {
+    colId: string;
+    oldValue: unknown;
+    newValue: unknown;
+}
+
+export declare interface RowEditingStartedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    editableColIds: string[];
+}
+
+export declare interface RowEditingStoppedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    committed: boolean;
+    changes?: RowEditChange[];
+}
+
+/** 对标 Phase 17 rowExpanded / rowCollapsed 事件 */
+export declare interface RowExpansionChangedEvent {
+    rowId: BusinessRowId;
+    expanded: boolean;
+    source: RowExpansionSource;
+}
+
+export declare type RowExpansionSource = 'api' | 'ui';
+
+/** 分组列变更事件 */
+export declare interface RowGroupChangedEvent {
+    columns: string[];
+    source: RowGroupingSource;
+}
+
+export declare type RowGroupingSource = 'api' | 'ui';
+
+/** 对标 Phase 18 rowGroupOpened 事件 */
+export declare interface RowGroupOpenedEvent {
+    groupId: string;
+    expanded: boolean;
+    field: string;
+    key: string;
+    level: number;
+    source: RowGroupingSource;
+}
+
+/** 对标 Phase 15 rowHeightChanged 事件 */
+export declare interface RowHeightChangedEvent {
+    rows: RowHeightChangeItem[];
+    finished: boolean;
+    source: RowHeightChangeSource;
+}
+
+export declare interface RowHeightChangeItem {
+    rowId: string;
+    rowHeight: number;
+}
+
+export declare type RowHeightChangeSource = 'api' | 'uiRowResized' | 'autoHeight' | 'dimensions';
+
+/** 行主键 API 入参：与 data[rowKey] 一致，可为 number / string；内核统一规范为 string */
+export declare type RowId = string | number;
+
+/** 单个 rowId 或 rowId 数组（toggleRowSelection / setIndexFocus 等） */
+export declare type RowIdInput = RowId | readonly RowId[];
+
+export declare interface RowIdPromotedEvent {
+    oldRowId: BusinessRowId;
+    newRowId: BusinessRowId;
+    data: RowData;
+}
+
+/** 行插入/删除下标基准：source = 存储顺序；display = 当前可见顺序（含 sort/filter） */
+export declare type RowIndexMode = 'source' | 'display';
+
+export declare type RowKind = 'data' | 'detail' | 'groupHeader' | 'groupFooter';
+
+/** 对标 Phase 15 rowMoved 事件 */
+export declare interface RowMovedEvent {
+    rowId: BusinessRowId;
+    fromIndex: number;
+    toIndex: number;
+    source: RowMoveSource;
+    /** live drag 中间态为 false；mouseup 收尾为 true（默认 true） */
+    finished?: boolean;
+    /** UI drag 时指针所在的 display 插入位；非 drag 或未提供时省略 */
+    displayIndex?: number;
+    /** 树形 drop 后新父节点 rowId；根层为 null；非树形时省略 */
+    parentRowId?: BusinessRowId | null;
+    /** 树形 drop 后在 parentRowId 下同级兄弟序号（0-based）；非树形时省略 */
+    siblingIndex?: number;
+    /** 树形 drop 后 treeLevel（根层 0）；非树形时省略 */
+    treeLevel?: number;
+}
+
+export declare interface RowMoveItem {
+    rowId: string;
+    fromIndex: number;
+    toIndex: number;
+}
+
+export declare interface RowMoveResult {
+    moved: boolean;
+    fromIndex?: number;
+    toIndex?: number;
+    reason?: string;
+    moves?: readonly RowMoveItem[];
+}
+
+export declare type RowMoveSource = 'api' | 'uiRowDrag';
+
+/**
+ * Phase 6 行 CRUD API 面。
+ *
+ * 负责增删行、导出用户数据、临时行 ID 提升；与 `applyTransaction` 共享同一事务管线。
+ *
+ * @see docs/10-phase6-row-crud.md
+ */
+export declare interface RowMutationGridApi {
+    /**
+     * 在指定位置插入一行或多行。
+     *
+     * - 省略 `data[rowKey]` 或值为 `null` 时生成**临时行**（`RowNode.id = __mg_tmp_*`）；
+     *   `getData()` 导出时对应字段为 `null`。
+     * - 带有效 `rowKey` 的新增行视为持久化行，须保证主键唯一。
+     * - 配置 `asyncRowMutation.add` 时 await 服务端成功后再写入本地。
+     *
+     * @returns 本次变更涉及的 RowNode 快照（add / remove / update）
+     */
+    addRows(options: AddRowsOptions): Promise<RowNodeTransaction>;
+    /**
+     * 按 rowId 和/或行下标删除行。
+     *
+     * - `rowIds`：内核 id 或业务主键值（number / string 均可）。
+     * - `indexes`：配合 `indexMode` 使用 `'source'`（存储顺序）或 `'display'`（排序/filter 后可见顺序）。
+     * - 删除正在编辑的行会先取消编辑；选区 / 索引定位 / 校验反馈会同步清理。
+     * - 配置 `asyncRowMutation.remove` 时 await 服务端成功后再删除本地。
+     *
+     * @returns 本次删除的 RowNode 快照
+     */
+    removeRows(options: RemoveRowsOptions): Promise<RowNodeTransaction>;
+    /**
+     * 导出当前表格数据为业务层 `RowData[]`。
+     *
+     * - 默认 `sourceOrder: true`，按 source 存储顺序返回。
+     * - 临时行的 `data[rowKey]` 固定为 `null`（不暴露 `__mg_tmp_*`）。
+     *
+     * @param options.sourceOrder `false` 时按当前 display 顺序（含 sort/filter 结果）
+     */
+    getData(options?: GetDataOptions): RowData[];
+    /**
+     * 将临时行的内部 id 提升为正式业务主键。
+     *
+     * - `rowId`：当前 `RowNode.id`（通常为 `__mg_tmp_*`）。
+     * - `businessId`：写入 `data[rowKey]` 并更新 `RowNode.id` 的值（number / string）。
+     * - 目标 id 已存在或行正在编辑时返回 `{ ok: false, reason }`。
+     *
+     * 成功时 emit `rowIdPromoted` 事件。
+     */
+    promoteRowId(options: PromoteRowIdOptions): PromoteRowIdResult;
+    /**
+     * 编程式移动行（Phase 15）。
+     *
+     * - `indexMode: 'source'`（默认）按 source 存储顺序移动。
+     * - `indexMode: 'display'` 按当前 display 顺序移动；sort 激活时拒绝。
+     * - managed UI drag 成功时 emit `rowMoved`（`source: 'uiRowDrag'`）；API 调用为 `'api'`。
+     */
+    moveRow(rowId: RowId, toIndex: number, indexMode?: RowIndexMode): RowMoveResult;
+}
+
+export declare interface RowMutationRemovedSnapshot {
+    rowId: BusinessRowId;
+    data: RowData;
+}
+
+/** 行变更事件中的行快照 */
+export declare interface RowMutationRowSnapshot {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    data: RowData;
+    isTransient: boolean;
+}
+
+/** 行节点：数据层与渲染层的统一单元 */
+export declare interface RowNode {
+    /** 池化复用键（必须稳定） */
+    id: string;
+    /** 用户数据（普通对象，禁止 reactive 深代理） */
+    data: RowData;
+    /** true = 尚未分配业务 rowKey；getData 导出时 rowKey 为 null */
+    isTransient?: boolean;
+    /** 由 positionRows 累计计算（不变量） */
+    rowTop: number;
+    /** 固定行高或实测行高 */
+    rowHeight: number;
+    /** 行高是否为估算值（v1 固定行高时为 false） */
+    estimated: boolean;
+    /** 在 rowsToDisplay 中的下标 */
+    rowIndex: number;
+    /** Phase 17 · 行种类；缺省 `data` */
+    rowKind?: RowKind;
+    /** Phase 17 · detail 行：指向主行 id */
+    masterRowId?: string;
+    /** Phase 17 · master 行：getDetailRowData 结果缓存（内核字段） */
+    __detailRowData?: unknown;
+    /** Phase 17 · master 行：详情加载态 */
+    __detailLoading?: boolean;
+    /** Phase 17 · master 行：详情加载失败原因 */
+    __detailLoadError?: unknown;
+    /** 用户/API 手动锁定行高后，autoHeight 不再覆盖（Phase 15） */
+    rowHeightPinned?: boolean;
+    /** autoHeight 各列实测高度缓存（Phase 15 · 内核字段） */
+    __autoHeights?: Record<string, number>;
+    /** 排序阶段产物（后续 M5 启用） */
+    childrenAfterSort?: RowNode[];
+    /** Phase 18 · 是否为分组树节点（非用户 leaf 数据） */
+    group?: boolean;
+    /** Phase 18 · 分组字段 colId */
+    groupField?: string;
+    /** Phase 18 · 分组键展示值 */
+    groupKey?: string;
+    /** Phase 18 · 分组层级 0..n-1 */
+    groupLevel?: number;
+    /** Phase 18 · 稳定分组 id */
+    groupId?: string;
+    /** Phase 18 · 从根到本 group 的路径键（drag 守卫） */
+    groupPathKey?: string;
+    /** Phase 18 · leaf 行：所属 group 路径键 */
+    leafGroupPathKey?: string;
+    /** Phase 18 · group 阶段子节点 */
+    childrenAfterGroup?: RowNode[];
+    /** Phase 18 · filter 阶段后子节点 */
+    childrenAfterFilter?: RowNode[];
+    /** Phase 18 · 本组可见 leaf 数（filter 后） */
+    groupLeafCount?: number;
+    /** Phase 18 · aggregate 阶段产物 */
+    __groupAggValues?: GroupAggValuesMap;
+    /** Phase 18 · display 合成行：指向源 group 节点 id */
+    sourceGroupId?: string;
+    /** Phase 19 · getDataPath 返回值 */
+    dataPath?: string[];
+    /** Phase 19 · 树深度：根 = 0 */
+    treeLevel?: number;
+    /** Phase 19 · 父节点 rowId；根节点 undefined */
+    parentRowId?: string;
+    /** Phase 19 · treeBuild 后子节点 */
+    childrenAfterTree?: RowNode[];
+    /** Phase 19 · 是否叶节点（无更长路径前缀的其他行） */
+    treeLeaf?: boolean;
+}
+
+/** 应用事务后的节点级 diff */
+export declare interface RowNodeTransaction {
+    add: RowNode[];
+    remove: RowNode[];
+    update: RowNode[];
+}
+
+export declare interface RowsAddedEvent {
+    rows: RowMutationRowSnapshot[];
+}
+
+/** 行选择配置（Phase 19 · groupSelectsChildren） */
+export declare interface RowSelectionConfig {
+    mode: RowSelectionMode;
+    /**
+     * tree 模式下选中父节点是否级联选中子孙。默认 `true`。
+     * 对标 AG Grid rowSelection.groupSelectsChildren。
+     */
+    groupSelectsChildren?: boolean;
+}
+
+export declare type RowSelectionInput = RowSelectionMode | false | RowSelectionConfig;
+
+export declare type RowSelectionMode = 'single' | 'multiple';
+
+/** 纵向合并行数（≥1）；缺省视为 1；仅表体 */
+export declare type RowSpanFn = (params: CellSpanParams) => number;
+
+/** 纵向 span 解析结果（head / 覆盖态） */
+export declare interface RowSpanHeadInfo {
+    head: RowNode;
+    rowSpan: number;
+    /** true = 当前格被上方 head 覆盖，不应渲染 */
+    covered: boolean;
+}
+
+export declare interface RowsRemovedEvent {
+    rows: RowMutationRemovedSnapshot[];
+}
+
+/** Grid 级：对象 = 全表每行同一样式；函数 = 按行 */
+export declare type RowStyle<TData = RowData> = CellStyle | RowStyleFn<TData>;
+
+export declare type RowStyleFn<TData = RowData> = (params: RowStyleParams<TData>) => CellStyle | null | undefined;
+
+export declare interface RowStyleParams<TData = RowData> {
+    data: TData;
+    rowId: BusinessRowId;
+    rowIndex: number;
+    /** display 行 kind · 合成行 fn 不应被调用（管线内 guard） */
+    rowKind?: RowKind;
+}
+
+/** 用户侧事务输入 */
+export declare interface RowTransaction {
+    add?: RowTransactionAddItem[];
+    remove?: RowData[] | string[];
+    update?: RowData[];
+}
+
+export declare type RowTransactionAddItem = RowData | AddRowPayload;
+
+export declare interface RowValidationFailedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    failedColId: string;
+    cellErrors?: Array<{
+        colId: string;
+        errors: string[];
+    }>;
+    rowErrors?: string[];
+    mode: InvalidEditValueMode;
+}
+
+/** rowValidator 结构化返回：指定错误应标红的列 */
+export declare interface RowValidationResult {
+    errors: string[];
+    colIds?: string[];
+}
+
+export declare type RowValidator = (params: RowValidatorParams) => ValidationErrors | RowValidationResult | Promise<ValidationErrors | RowValidationResult>;
+
+export declare interface RowValidatorParams {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    data: RowData;
+    draftValues: ReadonlyMap<string, unknown>;
+    signal: AbortSignal;
+}
+
+export declare interface RowValueChangedEvent {
+    rowId: BusinessRowId;
+    rowIndex: number;
+    rowNode: RowNode;
+    data: RowNode['data'];
+    changes: RowEditChange[];
+}
+
+/** 行选择列行级可选判定；省略时全部可选 */
+export declare type SelectableFn = (params: SelectableParams) => boolean;
+
+/** 判定行 checkbox 是否可勾选时传入的上下文 */
+export declare interface SelectableParams {
+    /** 当前行数据（RowData 快照） */
+    data: RowData;
+    rowId: BusinessRowId;
+    rowIndex: number;
+}
+
+export declare interface SelectionChangedEvent {
+    selectedRowIds: BusinessRowId[];
+}
+
+/** 行选择列配置 */
+export declare interface SelectionColumnOptions {
+    /** 列宽 px；默认 40；小于 40 时钳制为 40 */
+    width?: number;
+    /** 表头全选 checkbox 的 aria-label；默认「全选」 */
+    selectAllLabel?: string;
+    /** 行 checkbox 的 aria-label 工厂 */
+    rowLabel?: (rowIndex: number) => string;
+    /** 表头水平对齐；默认 center */
+    headerAlign?: GridHorizontalAlign;
+    /** 表头垂直对齐；默认 center */
+    headerValign?: GridVerticalAlign;
+    /** 表体水平对齐；默认 center */
+    align?: GridHorizontalAlign;
+    /** 表体垂直对齐；默认 center */
+    valign?: GridVerticalAlign;
+    /** footer 水平对齐；默认 center */
+    footerAlign?: GridHorizontalAlign;
+    /** footer 垂直对齐；默认 center */
+    footerValign?: GridVerticalAlign;
+}
+
+export declare interface SetCellCommentParams<TData = RowData, TMetadata = unknown> extends CellCommentParams<TData> {
+    /** undefined → 删除批注 */
+    comment: CellComment<TMetadata> | undefined;
+}
+
+/** hierarchy 模式下 managed drag 将新路径写回 row.data */
+export declare type SetDataPathFn = (params: SetDataPathParams) => void;
+
+export declare interface SetDataPathParams {
+    data: RowData;
+    dataPath: string[];
+    treeLevel: number;
+    previousPath: readonly string[];
+}
+
+export declare interface SetRowHeightChange {
+    rowId: string;
+    height: number;
+}
+
+export declare interface SizeColumnsToContentColumnLimit {
+    colId: string;
+    minWidth?: number;
+    maxWidth?: number;
+}
+
+export declare interface SizeColumnsToContentStrategy {
+    type: 'fitCellContents';
+    skipHeader?: boolean;
+    colIds?: readonly string[];
+    defaultMinWidth?: number;
+    defaultMaxWidth?: number;
+    columnLimits?: SizeColumnsToContentColumnLimit[];
+    /** auto-size 后按比例放大以填满视口 */
+    scaleUpToFitGridWidth?: boolean;
+}
+
+export declare interface SizeColumnsToFitColumnLimit {
+    colId: string;
+    minWidth?: number;
+    maxWidth?: number;
+}
+
+export declare interface SizeColumnsToFitGridStrategy {
+    type: 'fitGridWidth';
+    defaultMinWidth?: number;
+    defaultMaxWidth?: number;
+    columnLimits?: SizeColumnsToFitColumnLimit[];
+}
+
+/** 对标 AG Grid ISizeColumnsToFitParams */
+export declare interface SizeColumnsToFitParams {
+    /** 显式目标宽度（px）；缺省为视口宽度 */
+    gridWidth?: number;
+    defaultMinWidth?: number;
+    defaultMaxWidth?: number;
+    columnLimits?: SizeColumnsToFitColumnLimit[];
+    /** 仅调整指定列；缺省为全部非 suppressSizeToFit 用户列 */
+    colIds?: readonly string[];
+    /** 仅放大列宽以填满视口，不缩小 */
+    onlyScaleUp?: boolean;
+}
+
+export declare interface SizeColumnsToFitProvidedWidthStrategy {
+    type: 'fitProvidedWidth';
+    width: number;
+    defaultMinWidth?: number;
+    defaultMaxWidth?: number;
+    columnLimits?: SizeColumnsToFitColumnLimit[];
+}
+
+export declare interface SortChangedEvent {
+    sortModel: SortModelItem[];
+}
+
+export declare type SortDirection = 'asc' | 'desc';
+
+export declare interface SortModelItem {
+    colId: string;
+    sort: SortDirection;
+}
+
+/**
+ * 相邻两行是否应合并进同一纵向 span。
+ * 返回 true 表示合并。
+ */
+export declare type SpanRowsFunc = (params: SpanRowsParams) => boolean;
+
+/** spanRows 自定义比较入参 */
+export declare interface SpanRowsParams {
+    nodeA: {
+        rowId: string;
+        data: RowData;
+        rowIndex: number;
+    };
+    nodeB: {
+        rowId: string;
+        data: RowData;
+        rowIndex: number;
+    };
+    valueA: unknown;
+    valueB: unknown;
+    colId: string;
+}
+
+/** 传给 #status-bar 等插槽的 scoped context */
+export declare interface StatusBarContext {
+    /** GridApi 实例（与 expose 一致） */
+    api: GridApi | undefined;
+    /** 源数据总行数（过滤前） */
+    totalRowCount: number;
+    /** 当前展示行数（rowsToDisplay · 同 getMetrics().rowCount） */
+    displayedRowCount: number;
+    /** 是否处于过滤态 */
+    isFiltered: boolean;
+    /** 当前选中行数；rowSelection=false 时为 0 */
+    selectedRowCount: number;
+    /** 是否启用行选择 */
+    rowSelectionEnabled: boolean;
+    /** cellSelection 是否启用 */
+    cellSelectionEnabled: boolean;
+    /** 当前选区聚合；无选区或未启用时为 null */
+    cellSelectionAggregation: CellSelectionAggregation | null;
+    /** 平均值 / 求和展示小数位数（已归一） */
+    statusBarRangeAggregationPrecision: ResolvedStatusBarRangeAggregationPrecision;
+    /** 最近一次 metrics（Playground / 高级自定义用） */
+    metrics: GridMetrics | undefined;
+}
+
+/** 状态栏高度：`'auto'` 跟随 size preset；number 为自定义 px */
+export declare type StatusBarHeightInput = 'auto' | number;
+
+/** 框选聚合 panel 在状态栏中的位置；默认 `right` */
+export declare type StatusBarRangeAggregationPosition = 'left' | 'right';
+
+/** 简写 number 同时作用于平均值 / 求和；对象可分别指定 */
+export declare type StatusBarRangeAggregationPrecisionInput = number | {
+    average?: number;
+    sum?: number;
+};
+
+/** 表尾汇总行稳定 rowId（CellRendererParams / 池化键） */
+export declare const SUMMARY_ROW_ID = "__mg_summary__";
+
+/** 表尾汇总行 rowIndex 占位（非 rowsToDisplay 下标） */
+export declare const SUMMARY_ROW_INDEX = -1;
+
+export declare type SummaryAgg = SummaryAggBuiltin | SummaryAggFn;
+
+/** 内置列级聚合函数名 */
+export declare type SummaryAggBuiltin = 'sum' | 'avg' | 'min' | 'max' | 'count';
+
+/** 列级自定义聚合 */
+export declare type SummaryAggFn = (rows: readonly RowNode[], column: Column) => unknown;
+
+/** 全局汇总方法：返回 colId → 展示值（优先级高于列级 summaryAgg） */
+export declare type SummaryMethod = (params: SummaryMethodParams) => Record<string, string | number | null | undefined>;
+
+/** 全局汇总方法入参 */
+export declare interface SummaryMethodParams {
+    columns: readonly Column[];
+    /** 按 summaryScope 选取的 RowData 快照 */
+    data: RowData[];
+    rows: readonly RowNode[];
+}
+
+/** 汇总计算范围 */
+export declare type SummaryScope = 'displayed' | 'all';
+
+export declare type SuppressCellCommentFn<TData = RowData> = (params: SuppressCellCommentParams<TData>) => boolean;
+
+export declare interface SuppressCellCommentParams<TData = RowData> {
+    data: TData;
+    rowId: BusinessRowId;
+    colId: string;
+}
+
+export declare type SuppressPasteFn = (row: RowData) => boolean;
+
+/** 文本列默认算子集 */
+export declare type TextFilterType = 'contains' | 'notContains' | 'equals' | 'notEqual' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank';
+
+/** 自定义 tooltip 工厂（对标 CellRendererFn · 块 9） */
+export declare type TooltipComponentFactory = (params: ITooltipParams, mountEl: HTMLElement) => ITooltipComp | void;
+
+export declare type TooltipComponentType = TooltipComponentFactory;
+
+export declare type TooltipLocation = 'cell' | 'header' | 'footer' | 'statusBar';
+
+export declare type TooltipShowMode = 'whenTruncated' | 'always' | 'never';
+
+export declare type TooltipValueGetter<TData = RowData> = (params: TooltipValueGetterParams<TData>) => string | null | undefined;
+
+export declare interface TooltipValueGetterParams<TData = RowData> {
+    rowId: string;
+    colId: string;
+    data: TData | undefined;
+    value: unknown;
+    valueFormatted: string;
+    column: Column;
+    location: TooltipLocation;
+}
+
+export declare interface TreeChildrenLoadedEvent {
+    parentRowId: BusinessRowId;
+    children: RowData[];
+    childCount: number;
+    source: TreeTableSource;
+}
+
+export declare interface TreeChildrenLoadFailedEvent {
+    parentRowId: BusinessRowId;
+    reason?: string;
+    aborted?: boolean;
+}
+
+export declare interface TreeChildrenLoadingEvent {
+    parentRowId: BusinessRowId;
+    dataPath: string[];
+    treeLevel: number;
+    source: TreeTableSource;
+}
+
+export declare type TreeDisplayType = 'singleColumn';
+
+/** 树形行拖拽范围：默认仅同级；hierarchy 允许跨父级改挂 */
+export declare type TreeDragScope = 'siblings' | 'hierarchy';
+
+export declare interface TreeNodeOpenedEvent {
+    rowId: BusinessRowId;
+    expanded: boolean;
+    level: number;
+    dataPath: string[];
+    source: TreeTableSource;
+}
+
+export declare type TreeTableSource = 'api' | 'ui';
+
+export declare type TreeValueGetterFn = (params: TreeValueGetterParams) => string;
+
+export declare interface TreeValueGetterParams {
+    data: RowData;
+    dataPath: string[];
+    treeLevel: number;
+}
+
+/** Grid 默认行高热更新参数（MagicGrid `rowHeight` prop 等） */
+export declare interface UpdateRowDimensionsParams {
+    rowHeight?: number;
+    rowHeightMin?: number;
+    rowHeightMax?: number;
+}
+
+export declare interface ValidateCellsOptions {
+    /** 待校验的单元格列表 */
+    cells: GridCellPosition[];
+    signal?: AbortSignal;
+    /** 是否更新 invalid 视觉反馈，默认 true */
+    showFeedback?: boolean;
+}
+
+export declare interface ValidateGridOptions {
+    /** 指定行 id；省略则校验全表 */
+    rowIds?: RowId[];
+    signal?: AbortSignal;
+    /** 是否更新 invalid 视觉反馈，默认 true */
+    showFeedback?: boolean;
+}
+
+export declare interface ValidateRowsOptions {
+    /** 待校验的行 id 列表 */
+    rowIds: RowId[];
+    signal?: AbortSignal;
+    /** 是否更新 invalid 视觉反馈，默认 true */
+    showFeedback?: boolean;
+}
+
+/** 校验错误：null/undefined 表示通过；字符串数组表示失败 */
+export declare type ValidationErrors = string[] | null | undefined;
+
+/** async-validator 规则 */
+export declare type ValidationRule = Rule;
+
+export declare type ValidationRules = ValidationRule | MagicValidationRule | (ValidationRule | MagicValidationRule)[];
+
+export { }