arthub-table 0.2.2 → 0.2.3

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

@@ -2083,14 +2083,29 @@ declare class DataGrid {
         match: boolean;
     }>;
     /**
-     * Get info for all visible nested grids.
+     * Get info for all nested grids in the current viewport rows.
      * Used by E2E tests to discover and interact with nested grids.
+     *
+     * ⚠️ 实现细节（避免 e2e 探测假阴性）：
+     *   1. `body.rows` 由虚拟滚动只缓存视口内的行，所以"完全滚出视口的行"
+     *      上的嵌套表无法被报告 —— 这是必然损耗，e2e 端需要先 scroll 到目标行附近。
+     *   2. `cell.nestedGrid` 是 **延迟创建** 的（见 Cell.ts:createNestedGridLazy()），
+     *      只有 cell 被 `draw()` 至少一次才会实例化。横向滚动到刚露出的 cell
+     *      在第一次 draw 之前 nestedGrid 仍是 null，但 `cell.hasNestedData=true`
+     *      已经设好。这里用 `hasNestedData` 当判据，未实例化的也报告出来，
+     *      让 e2e 端能正确识别"该列存在嵌套表，只是当前还没 draw"。
+     *      对于这种 cell，`dataRowCount/columnCount` 等字段从 `nestedConfig`
+     *      或 `column.nestedColumns` 推导，bounds 仍由 cell 几何 + scroll 计算。
+     *   3. 触发实际 draw：调用方拿到这个 list 后若需要交互，可用 `triggerNestedGridDraw`
+     *      或者先 scrollToCell 让目标 cell 进入绘制流程，nestedGrid 就会被创建。
      */
     testGetNestedGridInfoList(): Array<{
         parentRowId: string | number;
         parentRowIndex: number;
         parentColKey: string;
         parentColIndex: number;
+        /** Parent column display name（取自 column.name / title / label，便于 spec 按"配置/美宣"等业务名匹配） */
+        parentColName: string;
         bounds: {
             x: number;
             y: number;
@@ -2121,6 +2136,8 @@ declare class DataGrid {
             col: number;
         } | null;
         rowHeight: number;
+        /** NestedGrid 实例是否已 lazy-create（false=配置存在但还没 draw 过） */
+        rendered: boolean;
     }>;
     /**
      * Get nested grid info for a specific parent cell.
@@ -2364,6 +2381,167 @@ declare class DataGrid {
             rowId: string;
         };
     } | null;
+    /**
+     * Get the row checkbox area for a normal (non-group) data row, in canvas coordinates.
+     *
+     * 这是 LRN-20260512-001 约定的"长期稳定 e2e 锚点 API"：批量下载 / 多选等
+     * spec 在 canvas 模式下需要点击行 checkbox。原本依赖 e2e 端按"index 列宽度的
+     * 一半"近似估算 click point，在分组模式 / 不同 originFixedWidth 下会偏移到
+     * 行号区，触发 onRowClick 而不是 checkbox toggle，导致 selectFirst5Tasks 失败。
+     *
+     * 这里直接复用 RowHeader 内部已有的 checkbox 偏移规则（与
+     * `RowHeader.isInsideCheckboxBoundary` 完全对齐），保证 e2e 点中的位置就是
+     * 业务运行时判定 checkbox 命中的位置。
+     *
+     * @param rowId - Row identifier
+     * @returns 16×16px checkbox 矩形 + 行内 y 中心坐标 + 元数据；行不存在 / 关闭了
+     *          showTableIndex / showCheckbox / 是组头行 → 返回 null。
+     */
+    testGetRowCheckboxArea(rowId: string | number): {
+        canvasX: number;
+        canvasY: number;
+        width: number;
+        height: number;
+        meta: {
+            rowIndex: number;
+            checked: boolean;
+            maxGroupLevel: number;
+            parentGroupLevel: number | null;
+        };
+    } | null;
+    /**
+     * Find a row's stable user-facing id (`row[rowKey]`) by a name-like field value.
+     *
+     * 这是 LRN-20260512-001 约定的"长期稳定 e2e 锚点 API"，专门给 AmE2ETest 在 canvas
+     * 模式下做"按任务名找 row"用——之前 helper 端 `findRowIdByTaskName` 自己在
+     * `getAllVisibleCells` / `grid.body.data` / `controller.tableTaskList` 三层 fallback
+     * 各 evaluate 一次，每次都序列化深拷贝整张表，刚 setExtraTableData 后还有 hooks
+     * 短暂返回 null 的窗口期；这里把"name → rowId"映射收敛进表本体的 `body.data`，
+     * 不依赖任何视口状态、也不需要 row 在 rowCache 中实例化。
+     *
+     * 匹配规则（默认）：
+     *   - 候选字段：`name`, `task_name`, `taskName`, `title`
+     *     · 优先精确相等；找不到才退到 includes 匹配。
+     *     · 字段值是对象时（自定义 viewer，例如交付物列返回 `{ files: [...] }`），
+     *       展开 `value.name / value.task_name / value.taskName / value.title /
+     *             value.value / value.label / value.text` 再匹配字符串。
+     *   - 跳过组头行 / 分隔行 / 加任务行（这些行的 rowKey 通常不是真实任务 id）。
+     *
+     * 搜索范围（iter#3 加固，覆盖 batch-download spec 在上传/分组场景的命中失败）：
+     *   1) 先扫 `this.body.data`（视口内 + 当前 filter 后的数据，最常见路径）
+     *   2) 没命中再扫 `this._fullData`（包含被折叠组隐藏的子行 / filter 过滤掉的行）
+     *   - 这样上传文件触发的"行临时移出 body.data"窗口期、以及 grouped 模式下查
+     *     找折叠组子任务时不再返回 null，spec 端 retry 次数显著下降。
+     *   - 返回的 id 仍然是 `row[rowKey]`，与 body.data 路径完全一致；不会因为
+     *     fallback 出现"id 形态不一致 → checkbox 命中比较失败"的二次问题。
+     *
+     * 返回的是 `row[rowKey]`（与 `getAllVisibleCells().rowId` / `getCheckedRowIds()`
+     * 严格对齐），不是内部的 `_rowId` string——这样 spec 端 `===` 比较不会因
+     * `'string' === 1234` 失败。
+     *
+     * @param name - 任务名 / 显示名（不区分精确匹配 vs 包含匹配，由内部判定）
+     * @param options.fields - 自定义候选字段数组（默认 `['name','task_name','taskName','title']`）
+     * @param options.exact - true 时仅做精确相等匹配；默认 false（fallback 到 includes）
+     * @returns row[rowKey] 或 null（找不到 / data 为空）
+     */
+    testFindRowIdByName(name: string, options?: {
+        fields?: string[];
+        exact?: boolean;
+    }): string | number | null;
+    /**
+     * E2E 诊断 hook：返回当前 DataGrid 的关键状态摘要（不含完整 row dump，避免序列化爆炸）。
+     *
+     * iter#4 新增（task=cdc1b0da）：spec 在 canvas 模式下连续 3 轮出现 0/10 task 命中，
+     * 但既有 hook 全是"找不到就返回 null"——观察侧拿不到任何中间状态信息。本 hook 给
+     * spec / observation 一个轻量的"实地探查"入口，可以快速判断：
+     *   - 当前 grid 是不是空的（data.length === 0）
+     *   - rowKey 是不是预期值（业务侧默认 'id'，task 池常用 'task_id'）
+     *   - 任务名是否真的存在于 body.data / _fullData 但被规则筛掉了（broadScan 命中数）
+     *   - 前 3 行的字段集合是什么样（用于人工核对 task name 落在哪个字段）
+     *
+     * 返回结构刻意保持小（前 3 行 sample, 字段名列表）—— 便于 console.log 整段直接 dump。
+     *
+     * @param name - 可选；提供时会做一次 case-insensitive includes 扫描，返回命中数和首批样本
+     * @returns 诊断对象，永不抛错
+     */
+    testGetDiagnostics(name?: string): {
+        rowKey: string;
+        bodyDataLength: number;
+        fullDataLength: number;
+        columnsCount: number;
+        sampleRowFieldNames: string[];
+        sampleRows: Array<Record<string, any>>;
+        nameProbe: {
+            query: string;
+            bodyMatchCount: number;
+            fullMatchCount: number;
+            bodyHits: Array<{
+                rowIndex: number;
+                matchedField: string;
+                matchedValue: string;
+                rowKeyValue: any;
+            }>;
+        } | null;
+    };
+    /**
+     * Look up a column's business `key` by header text / column title.
+     *
+     * 与 `testFindRowIdByName` 互补：解决 LRN-20260512-002 描述的
+     * "column.key vs header.colId（数字字符串）混淆"——AmE2ETest helper
+     * `findCanvasDeliverableColumnKey('交付物')` 在 iter-1 主要走 host
+     * controller 的 `e2eFindCanvasColumnKey`，但 host 没就绪 / 业务列正在重建时
+     * 会 fallback 到 `grid.columns[i].title.includes(...)`，多次 evaluate 命中率低。
+     *
+     * 现在表格本体直接给一个稳定 entry：从 `this.columns[i].title / name / label`
+     * 里反查到第一个匹配项的 `key`。
+     *
+     * @param displayName - 列的显示名（如 "交付物"）
+     * @param options.exact - 默认 false：includes 匹配；true 时仅做精确相等
+     * @returns column.key（业务字段名）或 null
+     */
+    testGetColumnKeyByName(displayName: string, options?: {
+        exact?: boolean;
+    }): string | null;
+    /**
+     * Atomic"按任务名 + 列显示名一次性拿到 cell interactive areas"hook。
+     *
+     * iter#2 加固（task=3f7204c0/iter#2）：解决 batch-download spec 在 canvas 模式下
+     * 的"多次 page.evaluate 之间存在重渲染窗口期"问题——
+     *   旧路径 = ① findRowIdByName → ② getColumnKeyByName → ③ scrollToRow
+     *           → ④ getCellInteractiveAreas，每一步都跨一次浏览器 tick；上传完文件后
+     *           setExtraTableData 会触发部分 row 临时重排，第 ① 步拿到的 rowId 在第
+     *           ④ 步前可能已经从 body.data 里移走，导致 getCellInteractiveAreas 返回
+     *           null，spec 端判定"找不到 cell"。
+     *
+     * 这里把 4 步压成单次同步调用：name → rowId（含 _fullData fallback） →
+     * displayName → columnKey → 自动 scrollIntoView → 直接复用
+     * `testGetCellInteractiveAreas` 拿区域信息。spec / helper 只需要一次 evaluate。
+     *
+     * 不能命中的情况：
+     *   - taskName 在 body.data 与 _fullData 都查不到 → 返回 { ok: false, reason: 'row-not-found' }
+     *   - column displayName 找不到对应 column.key → 返回 { ok: false, reason: 'column-not-found', rowId }
+     *   - rowId 找到了但 row 不在 body.data（被分组折叠）+ scrollIntoView 后仍未进入
+     *     视口 → 返回 { ok: false, reason: 'row-not-visible', rowId, columnKey }
+     *
+     * 完全命中时返回 testGetCellInteractiveAreas 的全部输出 + 解析出的 rowId/columnKey。
+     *
+     * @param taskName - 任务名（与 testFindRowIdByName 的入参语义一致）
+     * @param columnDisplayName - 列显示名（与 testGetColumnKeyByName 的入参语义一致）
+     * @param options.scrollIfNeeded - 默认 true：如果 row 不在视口内，先调
+     *        scrollRowIntoViewById 让它进入视口再取 areas；false 时跳过
+     *        scrollIntoView（保持当前 scroll 状态，直接用上一次绘制的 cell 几何）
+     * @param options.exact - 透传给 findRowIdByName / getColumnKeyByName 的 exact 标志
+     */
+    testFindCellAreasByName(taskName: string, columnDisplayName: string, options?: {
+        scrollIfNeeded?: boolean;
+        exact?: boolean;
+    }): {
+        ok: boolean;
+        reason?: 'row-not-found' | 'column-not-found' | 'row-not-visible' | 'cell-not-found';
+        rowId?: string | number;
+        columnKey?: string;
+        areas?: ReturnType<DataGrid['testGetCellInteractiveAreas']>;
+    };
     /**
      * Get all visible group rows.
      */

package/dist/types/core/viewers/RelatedTaskViewer.d.ts

@@ -17,6 +17,8 @@ declare class RelatedTaskViewer implements CellViewer<RelatedTaskViewerData> {
     private get LABEL_COLOR();
     private get EMPTY_TEXT_COLOR();
     private get DASHED_BORDER_COLOR();
+    /** Color for trailing "..." indicating overflow content — uses link/brand color so users notice the cell has more content. */
+    private get OVERFLOW_HINT_COLOR();
     constructor();
     /**
      * Calculate thumbnail height for single-line mode.
@@ -39,8 +41,32 @@ declare class RelatedTaskViewer implements CellViewer<RelatedTaskViewerData> {
     draw(context: ViewerRenderContext, data: RelatedTaskViewerData): void;
     private drawSingleLine;
     /**
-     * Draw a single inline thumbnail at the given position (for single-line mode).
-     * @returns The X position after the thumbnail(s)
+     * Single file-type field branch: draws label + all thumbnails proportionally scaled to fit.
+     * Mirrors ImageViewer.drawMultipleImages scaling logic so all images stay visible whenever possible.
+     * Drops trailing thumbnails (and shows trailing "...") only when scaled width would fall below MIN_THUMBNAIL_WIDTH.
+     */
+    private drawSingleFileFieldLine;
+    /**
+     * Compute scaled-thumbnail layout for "single file-type field" mode.
+     * Algorithm:
+     *   1. Each thumbnail's ideal size starts from thumbHeight × aspectRatio.
+     *      Then cap by MAX_THUMBNAIL_WIDTH: if idealWidth > MAX, scale that thumbnail's
+     *      ideal height down so its width = MAX. (Keeps aspect ratio, prevents wide images
+     *      from dominating the row.)
+     *   2. Row drawHeight = min(all per-thumbnail ideal heights). All thumbnails align to
+     *      this height; per-thumbnail width = drawHeight × aspectRatio (≤ MAX_THUMBNAIL_WIDTH).
+     *   3. If total width + gaps > availableWidth → uniform scale-down on drawHeight.
+     *   4. After scaling, drop trailing thumbnails whose width < MIN_THUMBNAIL_WIDTH;
+     *      retry on remaining items.
+     */
+    private computeSingleFileFieldLayout;
+    /**
+     * Draw a single inline thumbnail at the given position (for single-line mode, multi-field branch).
+     * Reuses computeSingleFileFieldLayout so behavior matches the single-file-field branch:
+     *   - All thumbnails proportionally scale into available width
+     *   - Trailing thumbnails dropped only when scaled width < MIN_THUMBNAIL_WIDTH
+     *   - When n === 1, accepts whatever width to keep at least one image visible
+     * @returns The X position after the thumbnail(s) and whether any thumbnails were dropped
      */
     private drawInlineThumbnail;
     private drawMultiLine;

package/dist/types/index.d.ts

@@ -49,3 +49,5 @@ export { DataGridEventAdapter, EventCategory, extractEventContext, mapDomEventTo
 export type { EventContext, } from './adapters/DataGridEventAdapter';
 export { buildDataGridInitParams, refreshDataGridRows, refreshDataGridColumns, refreshDataGridColumnByKeys, refreshDataGridColumnByKeysAsync, refreshDataGridColumnByKeysFast, refreshDataGridRowByIndex, } from './adapters/DataGridIntegration';
 export type { DataGridInitOptions, DataGridCallbacks, DataGridInitResult, } from './adapters/DataGridIntegration';
+export { installTestHooks, removeTestHooks, SnapshotManager, } from './testing';
+export type { TestHooksAPI, TestHooksRegistry, NestedGridTestInfo, } from './testing';

package/dist/types/testing/TestHooks.d.ts

@@ -334,6 +334,19 @@ export interface TestHooksAPI {
      * Returns expand arrow and checkbox bounds.
      */
     getGroupRowAreas: (rowId: string) => GroupRowAreas | null;
+    /**
+     * 获取普通数据行 checkbox 的精确 canvas 坐标（与 RowHeader 的命中检测严格对齐）。
+     *
+     * LRN-20260512-001 约定的"长期稳定 e2e 锚点 API"：批量下载 / 多选 spec 必须能
+     * 在 canvas 模式下点中行 checkbox 而不是行号。原本 e2e 端按"index 列宽度的一半"
+     * 估算坐标，在分组 / 不同 originFixedWidth 下会偏到行号区，触发 onRowClick
+     * 而不是 checkbox toggle。
+     *
+     * @param rowId - 行标识
+     * @returns 16×16 px 的 checkbox 区域（canvas 相对坐标），关闭索引列 / checkbox /
+     *          组头行 / 行不存在时返回 null。
+     */
+    getRowCheckboxArea: (rowId: string | number) => RowCheckboxArea | null;
     /**
      * Get all visible group rows with their expand/collapse state.
      */
@@ -342,6 +355,183 @@ export interface TestHooksAPI {
      * Get current selection, editing, and checked-row state.
      */
     getSelectionState: () => SelectionState;
+    /**
+     * 仅返回当前已勾选行（checkbox-selected）的 rowId 列表。
+     *
+     * 与 `getSelectionState().checkedRowIds` 等价，但作为独立的稳定 hook 暴露，
+     * 给 E2E 单点查询用，避免上层为了"行勾选状态"再读完整 SelectionState。
+     *
+     * 这是按 LRN-20260512-001 约定的"长期稳定 e2e 锚点 API"——业务侧 / 表格侧
+     * 重构时不要随手隐藏。
+     */
+    getCheckedRowIds: () => (string | number)[];
+    /**
+     * 按"任务名 / 显示名"反查 row 的 user-facing rowKey 值（一般是 task id）。
+     *
+     * LRN-20260512-001 + LRN-20260512-005 衍生需求：之前 AmE2ETest 端
+     * `findRowIdByTaskName` 自己分三层 evaluate（visibleCells → grid.body.data
+     * → controller.tableTaskList），每一层都做一次完整深拷贝，刚 setExtraTableData
+     * 后还存在 hooks 短暂返回 null 的窗口。表格本体直接给一个稳定 entry，
+     * 走 `body.data` 全量扫描（不依赖 rowCache 是否实例化），开销小且与
+     * `getCheckedRowIds` 的 id 类型严格对齐。
+     *
+     * 匹配规则：
+     * - 默认候选字段：`name`, `task_name`, `taskName`, `title`
+     *   （可经 `options.fields` 自定义）
+     * - 字段值是对象时（自定义 viewer，如交付物列返回 `{ files: [...] }`），
+     *   展开 `value.name / .task_name / .taskName / .title / .value / .label / .text`
+     *   再匹配字符串。
+     * - 优先精确相等，其次 `includes` 子串匹配（设 `options.exact = true` 关闭子串）。
+     * - 跳过组头 / 分隔行 / 加任务行（这些 row 的 rowKey 通常不是真实 id）。
+     *
+     * @returns 找到时返回 `row[rowKey]`（保留 number/string 原始类型）；未找到返回 null。
+     */
+    findRowIdByName: (name: string, options?: {
+        fields?: string[];
+        exact?: boolean;
+    }) => string | number | null;
+    /**
+     * 按列显示名（header text / title）反查列的业务 `key`（即 `column.key`）。
+     *
+     * LRN-20260512-002：column.key 是业务字段名（如 `'deliverable_v2'`），
+     * 而 `getHeaderInfo()[i].colId` 是数字字符串——很多 e2e helper 把两者混用，
+     * `getCellLayout` / `getCellInteractiveAreas` 入参拿到 colId 永远 null。
+     *
+     * 这里把"displayName → column.key"映射收敛进表本体，e2e 端不再需要先打到
+     * 宿主 controller。
+     *
+     * @param displayName - 列的显示名（如 "交付物"）
+     * @param options.exact - 默认 false：includes 匹配；true 时仅做精确相等
+     * @returns column.key 或 null
+     */
+    getColumnKeyByName: (displayName: string, options?: {
+        exact?: boolean;
+    }) => string | null;
+    /**
+     * 程序化滚动让指定 rowId 的行进入可见视口。
+     *
+     * 仅做"垂直方向"滚动，水平滚动位置保持不变（避免破坏 e2e 中已对齐到目标列的滚动状态）。
+     * 行不存在 / rowId 找不到 → 返回 false；已可见或滚动到位 → 返回 true。
+     *
+     * 用于替代 e2e helper 里 N 次 wheel-scroll 的循环——直接 jump 到目标行，
+     * 避开"刚上传/刚刷新"导致 visibleCells 短时间没有目标行的窗口。
+     */
+    scrollToRow: (rowId: string | number) => boolean;
+    /**
+     * 一次性把"任务名 + 列显示名 → cell interactive areas"全套查清楚的复合 hook。
+     *
+     * task=3f7204c0/iter#2 加固：把 spec 端的多步 evaluate 压成单次浏览器 tick，
+     * 避免 batch-download / deliverable-upload-download 等 spec 在每两步之间被
+     * setExtraTableData 触发的 row-reorder / re-layout 打断（旧路径需要 ① findRowIdByName
+     * → ② getColumnKeyByName → ③ scrollToRow → ④ getCellInteractiveAreas，每一步都
+     * 跨一个 tick）。
+     *
+     * 内部行为：
+     *   1) `findRowIdByName(taskName)` 拿 rowId（含 body.data → _fullData fallback）
+     *   2) `getColumnKeyByName(columnDisplayName)` 拿 column.key
+     *   3) 若 `scrollIfNeeded !== false`，自动调 `scrollRowIntoViewById` 让行进入视口
+     *   4) `getCellInteractiveAreas(rowId, columnKey)` 取交互区域（cell / editIcon /
+     *      linkIcon / errorIcon / reminderTriangle / viewerAreas / meta）
+     *
+     * 失败时返回 `{ ok: false, reason }`，reason 详细分类：
+     *   - `'row-not-found'`     : taskName 在 body.data 与 _fullData 都查不到
+     *   - `'column-not-found'`  : 列显示名找不到对应 column.key
+     *   - `'row-not-visible'`   : rowId 在 _fullData 里有但被分组折叠隐藏（spec 应先展开分组）
+     *   - `'cell-not-found'`    : 极端情况（cell 在 row.allCells 里缺失，通常是 rowCache 异步未就绪）
+     *
+     * 成功时返回 `{ ok: true, rowId, columnKey, areas }`，areas 字段格式与
+     * `getCellInteractiveAreas` 完全一致。
+     */
+    /**
+     * 诊断 hook：返回 grid 内部状态摘要。
+     *
+     * task=cdc1b0da/iter#4 加固：spec 在 canvas 模式下连续 3 轮出现 `findRowIdByName`
+     * 0/10 命中——既有 hook 全部"找不到就返回 null"，观察侧拿不到中间状态。本 hook 给
+     * spec / verify 一个"实地探查"入口：可以快速判断 grid 是不是空、rowKey 是不是预期、
+     * 任务名是否真的存在但被字段白名单筛掉、前 3 行字段集合是什么样。
+     *
+     * 返回结构刻意保持小（前 3 行 sample, 字段名列表）—— 整段 console.log 也不会爆。
+     *
+     * @param name - 可选；提供时做一次 case-insensitive includes 扫描，返回命中数 + 首批样本
+     */
+    getDiagnostics: (name?: string) => {
+        rowKey: string;
+        bodyDataLength: number;
+        fullDataLength: number;
+        columnsCount: number;
+        sampleRowFieldNames: string[];
+        sampleRows: Array<Record<string, any>>;
+        nameProbe: {
+            query: string;
+            bodyMatchCount: number;
+            fullMatchCount: number;
+            bodyHits: Array<{
+                rowIndex: number;
+                matchedField: string;
+                matchedValue: string;
+                rowKeyValue: any;
+            }>;
+        } | null;
+    };
+    findCellAreasByName: (taskName: string, columnDisplayName: string, options?: {
+        scrollIfNeeded?: boolean;
+        exact?: boolean;
+    }) => {
+        ok: boolean;
+        reason?: 'row-not-found' | 'column-not-found' | 'row-not-visible' | 'cell-not-found';
+        rowId?: string | number;
+        columnKey?: string;
+        areas?: {
+            cell: {
+                canvasX: number;
+                canvasY: number;
+                width: number;
+                height: number;
+            };
+            editIcon: {
+                canvasX: number;
+                canvasY: number;
+                width: number;
+                height: number;
+            } | null;
+            linkIcon: {
+                canvasX: number;
+                canvasY: number;
+                width: number;
+                height: number;
+            } | null;
+            errorIcon: {
+                canvasX: number;
+                canvasY: number;
+                width: number;
+                height: number;
+            } | null;
+            reminderTriangle: {
+                canvasX: number;
+                canvasY: number;
+                width: number;
+                height: number;
+            } | null;
+            viewerAreas: Array<{
+                type: string;
+                bounds: {
+                    canvasX: number;
+                    canvasY: number;
+                    width: number;
+                    height: number;
+                };
+                value?: any;
+            }>;
+            meta: {
+                viewerType: string;
+                readonly: boolean;
+                isLink: boolean;
+                hasError: boolean;
+                hasReminder: boolean;
+                hasNestedGrid: boolean;
+            };
+        } | null;
+    };
 }
 /**
  * Test info for a single nested grid instance
@@ -355,6 +545,11 @@ export interface NestedGridTestInfo {
     parentColKey: string;
     /** Parent column index */
     parentColIndex: number;
+    /**
+     * Parent column display name（取自 column.name / title / label，便于 spec 按"配置/美宣"等业务名匹配）。
+     * 如果都没配置，可能是空字符串。
+     */
+    parentColName: string;
     /** Nested grid position/size relative to canvas */
     bounds: {
         x: number;
@@ -396,6 +591,13 @@ export interface NestedGridTestInfo {
     } | null;
     /** Row height */
     rowHeight: number;
+    /**
+     * 该嵌套表的 NestedGrid 实例是否已创建（即至少 draw 过一次）。
+     *   - true ：所有字段（bounds/selectionRange/...）来自实例，可直接交互
+     *   - false：实例尚未 lazy-create，bounds/dataRowCount/columnCount 由配置推导，
+     *           交互前需要让 cell 进入视口并触发一次 draw
+     */
+    rendered: boolean;
 }
 /**
  * Bounding box in canvas coordinates (can be converted to viewport coords)
@@ -492,6 +694,32 @@ export interface GroupRowAreas {
         rowId: string;
     };
 }
+/**
+ * Row checkbox area for normal (non-group) data rows.
+ *
+ * 与 `GroupRowAreas.checkbox` 区分：那个是组头行的 checkbox；本接口是普通数据
+ * 行 RowHeader 内部的 checkbox。两者命中检测代码各走一套路径，几何也不一样。
+ */
+export interface RowCheckboxArea {
+    /** Canvas-relative X coordinate (16×16 px square). */
+    canvasX: number;
+    /** Canvas-relative Y coordinate. */
+    canvasY: number;
+    /** Width — always 16 (CHECKBOX_SIZE). */
+    width: number;
+    /** Height — always 16 (CHECKBOX_SIZE). */
+    height: number;
+    meta: {
+        /** Row index in body.data. */
+        rowIndex: number;
+        /** Whether the checkbox is currently rendered as checked. */
+        checked: boolean;
+        /** Grid maxGroupLevel snapshot (for diagnostic purposes only). */
+        maxGroupLevel: number;
+        /** Parent group level if this row is inside a group, null otherwise. */
+        parentGroupLevel: number | null;
+    };
+}
 /**
  * Current selection/editing state of the table
  */

package/dist/types/testing/index.d.ts

@@ -1,3 +1,3 @@
-export type { CellLayout, VisibleCell, TestColumnConfig, ScrollPosition, TableDimensions, SnapshotDifference, SnapshotCompareResult, TableSnapshot, TestHooksAPI, AreaBounds, ViewerArea, CellInteractiveAreas, HeaderInteractiveAreas, GroupRowAreas, SelectionState, VisibleGroupRowInfo, TestHooksRegistry, } from './TestHooks';
+export type { CellLayout, VisibleCell, TestColumnConfig, ScrollPosition, TableDimensions, SnapshotDifference, SnapshotCompareResult, TableSnapshot, TestHooksAPI, AreaBounds, ViewerArea, CellInteractiveAreas, HeaderInteractiveAreas, GroupRowAreas, SelectionState, VisibleGroupRowInfo, TestHooksRegistry, NestedGridTestInfo, } from './TestHooks';
 export { installTestHooks, removeTestHooks } from './installTestHooks';
 export { SnapshotManager } from './SnapshotManager';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arthub-table",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "High-performance canvas-based table/grid component for Vue 3 with TypeScript support, featuring virtual scrolling, cell viewers, grouped rows, and nested grids.",
   "main": "dist/arthub-table.common.js",
   "module": "dist/arthub-table.umd.min.js",