@rickcedwhat/playwright-smart-table 6.20.1 → 6.21.0

package/dist/plugins/index.d.ts

@@ -1,13 +1,32 @@
 /**
  * @deprecated Use `presets` instead. Plugins will be removed in v7.0.0.
- * Presets for specific table/grid libraries. Each plugin exposes:
- * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Presets.MUI, maxPages: 5 }).
- * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Presets.MUI.Strategies }).
+ *
+ * Compatibility shim over official presets:
+ * - `Plugins.MUI` → `presets.muiDataGrid` (**DataGrid only** — not `presets.muiTable`)
+ * - `Plugins.RDG` → `presets.rdg`
+ * - `Plugins.Glide` → `presets.glide`
+ *
+ * Prefer: `useTable(loc, { ...presets.muiDataGrid, maxPages: 5 })`.
+ * Strategies only: `useTable(loc, { rowSelector: '...', strategies: presets.muiDataGrid.strategies })`.
  */
 export declare const Plugins: {
     /** @deprecated Use `presets.rdg` */
     RDG: {
-        Strategies: import("../types").TableStrategies | undefined;
+        Strategies: {
+            header: (context: import("..").TableContext) => Promise<string[]>;
+            getCellLocator: ({ row, columnIndex }: {
+                row: import("@playwright/test").Locator;
+                columnIndex: number;
+            }) => import("@playwright/test").Locator;
+            navigation: {
+                goRight: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goLeft: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goDown: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goUp: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goHome: ({ root }: import("..").StrategyContext) => Promise<void>;
+            };
+            pagination: import("..").PaginationPrimitives;
+        };
         headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
         rowSelector?: string | undefined;
         cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
@@ -22,14 +41,33 @@ export declare const Plugins: {
         autoScroll?: boolean | undefined;
         debug?: import("..").DebugConfig | undefined;
         onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
-        strategies?: import("../types").TableStrategies | undefined;
+        strategies?: import("..").TableStrategies | undefined;
         columnOverrides?: Partial<Record<string | number | symbol, import("..").ColumnOverride<any>>> | undefined;
         syntheticColumns?: Record<string, import("..").SyntheticColumnDef<any>> | undefined;
         emptyState?: import("@playwright/test").Locator | undefined;
     };
     /** @deprecated Use `presets.glide` */
     Glide: {
-        Strategies: import("../types").TableStrategies | undefined;
+        Strategies: {
+            fillSimple: import("..").FillStrategy;
+            fill: import("..").FillStrategy;
+            pagination: import("..").PaginationPrimitives;
+            header: (context: import("..").StrategyContext, options?: {
+                limit?: number;
+                selector?: string;
+                scrollAmount?: number;
+            }) => Promise<string[]>;
+            viewport: import("..").ViewportStrategy;
+            loading: {
+                isHeaderLoading: () => Promise<boolean>;
+            };
+            getCellLocator: ({ row, columnIndex }: any) => any;
+            getActiveCell: ({ page }: any) => Promise<{
+                rowIndex: number;
+                columnIndex: number;
+                locator: any;
+            } | null>;
+        };
         headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
         rowSelector?: string | undefined;
         cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
@@ -44,14 +82,17 @@ export declare const Plugins: {
         autoScroll?: boolean | undefined;
         debug?: import("..").DebugConfig | undefined;
         onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
-        strategies?: import("../types").TableStrategies | undefined;
+        strategies?: import("..").TableStrategies | undefined;
         columnOverrides?: Partial<Record<string | number | symbol, import("..").ColumnOverride<any>>> | undefined;
         syntheticColumns?: Record<string, import("..").SyntheticColumnDef<any>> | undefined;
         emptyState?: import("@playwright/test").Locator | undefined;
     };
-    /** @deprecated Use `presets.muiDataGrid` */
+    /**
+     * @deprecated Use `presets.muiDataGrid`.
+     * DataGrid only — for MUI `<Table>` use `presets.muiTable`.
+     */
     MUI: {
-        Strategies: import("../types").TableStrategies | undefined;
+        Strategies: import("..").TableStrategies | undefined;
         headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
         rowSelector?: string | undefined;
         cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
@@ -66,7 +107,7 @@ export declare const Plugins: {
         autoScroll?: boolean | undefined;
         debug?: import("..").DebugConfig | undefined;
         onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
-        strategies?: import("../types").TableStrategies | undefined;
+        strategies?: import("..").TableStrategies | undefined;
         columnOverrides?: Partial<Record<string | number | symbol, import("..").ColumnOverride<any>>> | undefined;
         syntheticColumns?: Record<string, import("..").SyntheticColumnDef<any>> | undefined;
         emptyState?: import("@playwright/test").Locator | undefined;

package/dist/plugins/index.js

@@ -4,15 +4,23 @@ exports.Plugins = void 0;
 const presets_1 = require("../presets");
 /**
  * @deprecated Use `presets` instead. Plugins will be removed in v7.0.0.
- * Presets for specific table/grid libraries. Each plugin exposes:
- * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Presets.MUI, maxPages: 5 }).
- * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Presets.MUI.Strategies }).
+ *
+ * Compatibility shim over official presets:
+ * - `Plugins.MUI` → `presets.muiDataGrid` (**DataGrid only** — not `presets.muiTable`)
+ * - `Plugins.RDG` → `presets.rdg`
+ * - `Plugins.Glide` → `presets.glide`
+ *
+ * Prefer: `useTable(loc, { ...presets.muiDataGrid, maxPages: 5 })`.
+ * Strategies only: `useTable(loc, { rowSelector: '...', strategies: presets.muiDataGrid.strategies })`.
  */
 exports.Plugins = {
     /** @deprecated Use `presets.rdg` */
-    RDG: Object.assign(Object.assign({}, presets_1.rdg), { Strategies: presets_1.rdg.strategies }),
+    RDG: Object.assign(Object.assign({}, presets_1.rdg), { Strategies: presets_1.rdg.Strategies }),
     /** @deprecated Use `presets.glide` */
-    Glide: Object.assign(Object.assign({}, presets_1.glide), { Strategies: presets_1.glide.strategies }),
-    /** @deprecated Use `presets.muiDataGrid` */
+    Glide: Object.assign(Object.assign({}, presets_1.glide), { Strategies: presets_1.glide.Strategies }),
+    /**
+     * @deprecated Use `presets.muiDataGrid`.
+     * DataGrid only — for MUI `<Table>` use `presets.muiTable`.
+     */
     MUI: Object.assign(Object.assign({}, presets_1.muiDataGrid), { Strategies: presets_1.muiDataGrid.strategies }),
 };

package/dist/presets/glide/index.d.ts

@@ -12,7 +12,7 @@ export declare const GlideStrategies: {
         selector?: string;
         scrollAmount?: number;
     }) => Promise<string[]>;
-    viewport: import("../../types").ViewportStrategy;
+    viewport: import("../..").ViewportStrategy;
     loading: {
         isHeaderLoading: () => Promise<boolean>;
     };

package/dist/presets/glide/index.js

@@ -123,8 +123,8 @@ function createGlide(options = {}) {
 }
 /**
  * Full preset for Glide Data Grid (selectors + default strategies only).
- * Spread: useTable(loc, { ...Plugins.Glide, maxPages: 5 }).
- * Strategies only (including fillSimple): useTable(loc, { rowSelector: '...', strategies: Plugins.Glide.Strategies }).
+ * Spread: `useTable(loc, { ...presets.glide, maxPages: 5 })`.
+ * Strategies only (including fillSimple): `useTable(loc, { rowSelector: '...', strategies: presets.glide.Strategies })`.
  * For a non-64-column grid, use `createGlide({ columnCount })` instead.
  */
 const GlidePreset = {

package/dist/presets/rdg.d.ts

@@ -1,6 +1,6 @@
 import type { Locator } from '@playwright/test';
 import { TableContext, TableConfig, ViewportStrategy, StrategyContext } from '../types';
-/** Full strategies for React Data Grid. Use when you want to supply your own selectors: strategies: Plugins.RDG.Strategies */
+/** Full strategies for React Data Grid. Use when you want to supply your own selectors: `strategies: presets.rdg.Strategies` */
 export declare const RDGStrategies: {
     header: (context: TableContext) => Promise<string[]>;
     getCellLocator: ({ row, columnIndex }: {

package/dist/presets/rdg.js

@@ -92,20 +92,20 @@ const rdgNavigation = {
         });
     }
 };
-/** Default strategies for the RDG preset (used when you spread Plugins.RDG). */
+/** Default strategies for the RDG preset (used when you spread `presets.rdg`). */
 const RDGDefaultStrategies = {
     header: scrollRightHeaderRDG,
     getCellLocator: rdgGetCellLocator,
     navigation: rdgNavigation,
     pagination: rdgPaginationStrategy
 };
-/** Full strategies for React Data Grid. Use when you want to supply your own selectors: strategies: Plugins.RDG.Strategies */
+/** Full strategies for React Data Grid. Use when you want to supply your own selectors: `strategies: presets.rdg.Strategies` */
 // fallow-ignore-next-line unused-export
 exports.RDGStrategies = RDGDefaultStrategies;
 /**
  * Full preset for React Data Grid (selectors + default strategies).
- * Spread: useTable(loc, { ...Plugins.RDG, maxPages: 5 }).
- * Strategies only: useTable(loc, { rowSelector: '...', strategies: Plugins.RDG.Strategies }).
+ * Spread: `useTable(loc, { ...presets.rdg, maxPages: 5 })`.
+ * Strategies only: `useTable(loc, { rowSelector: '...', strategies: presets.rdg.Strategies })`.
  */
 const RDGPreset = {
     rowSelector: '[role="row"].rdg-row',

package/dist/smartRow.d.ts

@@ -1,4 +1,4 @@
-import type { Locator, Page } from '@playwright/test';
+import { type Locator, type Page } from '@playwright/test';
 import { SmartRow as SmartRowType, FinalTableConfig, TableResult } from './types';
 import { NavigationBarrier } from './utils/navigationBarrier';
 /**
@@ -9,5 +9,5 @@ import { NavigationBarrier } from './utils/navigationBarrier';
  * @internal Internal factory for creating SmartRow objects.
  * Not part of the public package surface; tests and consumers should use public APIs.
  */
-declare const createSmartRow: <T = any>(rowLocator: Locator, map: Map<string, number>, rowIndex: number | undefined, config: FinalTableConfig<T>, rootLocator: Locator, resolve: (item: any, parent: Locator | Page) => Locator, table: TableResult<T> | null, tablePageIndex?: number, barrier?: NavigationBarrier) => SmartRowType<T>;
+declare const createSmartRow: <T = any>(rowLocator: Locator, map: Map<string, number>, rowIndex: number | undefined, config: FinalTableConfig<T>, rootLocator: Locator, resolve: (item: any, parent: Locator | Page) => Locator, table: TableResult<T> | null, tablePageIndex?: number, barrier?: NavigationBarrier, renderWindowPosition?: boolean) => SmartRowType<T>;
 export default createSmartRow;

package/dist/smartRow.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("@playwright/test");
 const rowResolution_1 = require("./engine/rowResolution");
 const fill_1 = require("./strategies/fill");
 const stringUtils_1 = require("./utils/stringUtils");
@@ -12,7 +13,7 @@ const sentinel_1 = require("./utils/sentinel");
  * Returns the target cell locator after navigation.
  */
 const _navigateToCell = async (params) => {
-    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier } = params;
+    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier, allowMissingCell } = params;
     const rowLabel = typeof rowIndex === 'number' ? `row ${rowIndex}` : 'row ?';
     (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: resolving column "${column}" (colIndex ${index}), ${rowLabel}`);
     // Get active cell if strategy is available
@@ -65,7 +66,18 @@ const _navigateToCell = async (params) => {
                     ? await viewport.getVisibleRowRange(context)
                     : null;
                 const rowVisible = !rowRange || (rowIndex >= rowRange.first && rowIndex <= rowRange.last);
-                if (rowVisible && await targetReached()) {
+                let cellAttached = rowVisible && await targetReached();
+                if (rowVisible && !cellAttached) {
+                    try {
+                        await getCellLocator().waitFor({ state: 'attached', timeout: 500 });
+                        cellAttached = true;
+                    }
+                    catch (error) {
+                        if (!(error instanceof test_1.errors.TimeoutError))
+                            throw error;
+                    }
+                }
+                if (cellAttached) {
                     (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} in visible range [${knownColRange.first}-${knownColRange.last}], reading directly`);
                     // Check in to the barrier without a moveAction — peers that need the scroll
                     // still supply their own action and will trigger it when all rows arrive.
@@ -124,6 +136,8 @@ const _navigateToCell = async (params) => {
         }
         // Cell still not accessible — fall through to navigation primitives if configured.
         if (!config.strategies.navigation) {
+            if (allowMissingCell)
+                return getCellLocator();
             const colRange = viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
             const rowRange = viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
             let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex}.\n`;
@@ -144,15 +158,17 @@ const _navigateToCell = async (params) => {
     // Use navigation primitives if available
     if (config.strategies.navigation) {
         const nav = config.strategies.navigation;
-        if (typeof rowIndex !== 'number') {
-            throw new Error('Row index is required for navigation');
-        }
         if (await targetReached()) {
             // Already there. If we have a barrier, check-in to stay in lock-step.
             if (barrier)
                 await barrier.sync(index);
             return getCellLocator();
         }
+        if (typeof rowIndex !== 'number') {
+            if (allowMissingCell)
+                return getCellLocator();
+            throw new Error('Row index is required for navigation');
+        }
         // If getActiveCell is present but returns null (no focus), and cell is in DOM,
         // try to focus it once before entering navigation loop.
         if (config.strategies.getActiveCell) {
@@ -196,6 +212,8 @@ const _navigateToCell = async (params) => {
                     currCol = ac.columnIndex;
                 }
             }
+            // Column-0 snap is owned by the navigation primitive (scrollLeft=0, Home, etc.).
+            // Core must not special-case canvas/Home — that was pre-viewport Glide glue.
             if (index === 0 && nav.snapFirstColumnIntoView) {
                 (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: snapFirstColumnIntoView for column index 0');
                 await nav.snapFirstColumnIntoView(context);
@@ -206,27 +224,6 @@ const _navigateToCell = async (params) => {
                         currCol = ac.columnIndex;
                     }
                 }
-                // Home moves a11y focus within the current row to column 0. If focus row !== target row
-                // (e.g. still on previous row), Home jumps to grid origin and breaks `tr.nth(k)` reads.
-                if (typeof rowIndex === 'number' && currRow === rowIndex) {
-                    await rootLocator.evaluate((el) => {
-                        var _a;
-                        const canvas = el.closest('canvas') || ((_a = el.parentElement) === null || _a === void 0 ? void 0 : _a.querySelector('canvas'));
-                        if (canvas instanceof HTMLCanvasElement) {
-                            canvas.tabIndex = 0;
-                            canvas.focus();
-                        }
-                    });
-                    await page.keyboard.press('Home');
-                    await page.waitForTimeout(120);
-                    if (config.strategies.getActiveCell) {
-                        const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-                        if (ac) {
-                            currRow = ac.rowIndex;
-                            currCol = ac.columnIndex;
-                        }
-                    }
-                }
             }
             let cDiff = index - currCol;
             if (Math.abs(cDiff) > 12 && nav.seekColumnIndex) {
@@ -253,8 +250,8 @@ const _navigateToCell = async (params) => {
                 const settleMs = (Number.isFinite(nav.settleMs) && nav.settleMs >= 0) ? nav.settleMs : computed;
                 await page.waitForTimeout(settleMs);
             }
-            // Wait for active cell to match target: poll getActiveCell or fallback to fixed delay
-            // This is the "Midas Touch" buffer needed for Glide's async accessibility updates.
+            // After horizontal steps, poll until getActiveCell / DOM presence confirms the target
+            // (a11y trees and virtual mounts often lag the scroll). Tune via navigation.maxWaitMs.
             const pollIntervalMs = 10;
             const computedMax = Math.min(6000, 250 + horizontalSteps * 25);
             const maxWaitMs = (Number.isFinite(nav.maxWaitMs) && nav.maxWaitMs >= 0) ? nav.maxWaitMs : computedMax;
@@ -290,6 +287,8 @@ const _navigateToCell = async (params) => {
         const finalCell = getCellLocator();
         if (await finalCell.count() > 0)
             return finalCell;
+        if (allowMissingCell)
+            return finalCell;
         const colRange = viewport && viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
         const rowRange = viewport && viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
         let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex} after exhausting navigation strategies. Ensure navigation primitives are correctly implemented.\n`;
@@ -313,7 +312,7 @@ const _navigateToCell = async (params) => {
  * @internal Internal factory for creating SmartRow objects.
  * Not part of the public package surface; tests and consumers should use public APIs.
  */
-const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex, barrier) => {
+const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex, barrier, renderWindowPosition = false) => {
     const smart = rowLocator;
     // Attach State
     smart.rowIndex = rowIndex;
@@ -406,12 +405,22 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, [...map.keys(), ...Object.keys((_b = config.syntheticColumns) !== null && _b !== void 0 ? _b : {})]));
         }
         const columnOverride = (_c = config.columnOverrides) === null || _c === void 0 ? void 0 : _c[colName];
-        const cell = config.strategies.getCellLocator
-            ? config.strategies.getCellLocator({
-                row: rowLocator, root: rootLocator, columnName: colName,
-                columnIndex: idx, rowIndex, page: rootLocator.page(), config,
-            })
-            : resolve(config.cellSelector, rowLocator).nth(idx);
+        const page = rootLocator.page();
+        // Same nav pipeline as toJSON / getCell().bringIntoView() (#430) so virtualized
+        // off-screen columns don't return empty/stale text.
+        const cell = await _navigateToCell({
+            config,
+            rootLocator,
+            page,
+            resolve,
+            getHeaders: table === null || table === void 0 ? void 0 : table.getHeaders,
+            column: colName,
+            index: idx,
+            rowLocator,
+            rowIndex,
+            barrier: smart._barrier,
+            allowMissingCell: !!(columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read),
+        });
         if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) {
             const getCell = (name) => {
                 const ci = map.get(name);
@@ -424,7 +433,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         return (await cell.innerText()).trim();
     };
     smart.toJSON = async (options) => {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         // Atomic mode: snapshot the row in a single evaluate, then apply column overrides
         // against a frozen reconstruction. Zero inter-column stagger — even in-place React
         // re-renders can't affect it because overrides read from a detached clone.
@@ -434,10 +443,84 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 throw new Error('[SmartTable] toJSON({ atomic: true }) requires cellSelector to be a CSS string, not a function.');
             }
             const page = rootLocator.page();
+            // Re-pin: the row locator is a positional nth-child from the iteration loop.
+            // On recycling virtualizers, elements can shift between SmartRow creation and
+            // this clone — the nth element may now show a different row's content.
+            // Verify via resolveRowIndex and rescan if drifted.
+            let cloneTarget = rowLocator;
+            const resolveRI = config.strategies.resolveRowIndex;
+            const isSelfHealing = smart._selfHealing === true;
+            const rescanForRow = resolveRI && typeof rowIndex === 'number' && !isSelfHealing
+                ? async () => {
+                    const rows = await resolve(config.rowSelector, rootLocator).all();
+                    for (const r of rows) {
+                        try {
+                            const rResult = await resolveRI(r);
+                            if (rResult !== undefined && (0, rowResolution_1.normalizeRowIndexResult)(rResult).index === rowIndex)
+                                return r;
+                        }
+                        catch ( /* element may have detached during scan */_a) { /* element may have detached during scan */ }
+                    }
+                    return null;
+                }
+                : null;
+            if (rescanForRow) {
+                let drifted = false;
+                try {
+                    const curResult = await resolveRI(rowLocator);
+                    const curIndex = curResult !== undefined
+                        ? (0, rowResolution_1.normalizeRowIndexResult)(curResult).index
+                        : undefined;
+                    drifted = curIndex !== rowIndex;
+                }
+                catch (_k) {
+                    drifted = true;
+                }
+                if (drifted) {
+                    const inBatch = smart._inBatch === true || !!smart._barrier;
+                    let recovered = await rescanForRow();
+                    if (!recovered && !inBatch && ((_a = config.strategies.viewport) === null || _a === void 0 ? void 0 : _a.scrollToRow)) {
+                        await config.strategies.viewport.scrollToRow({ root: rootLocator, config, page, resolve }, rowIndex);
+                        const deadline = Date.now() + 500;
+                        while (!recovered && Date.now() < deadline) {
+                            recovered = await rescanForRow();
+                            if (!recovered)
+                                await page.waitForTimeout(50);
+                        }
+                    }
+                    if (!recovered) {
+                        throw new Error(`[SmartTable] toJSON({ atomic: true }): row ${rowIndex} recycled out of the DOM and could not be recovered. ` +
+                            (inBatch
+                                ? `(During a map/forEach batch, scroll-back recovery is disabled to avoid disrupting sibling rows.)`
+                                : `Ensure a viewport.scrollToRow strategy can restore the row.`));
+                    }
+                    cloneTarget = recovered;
+                }
+            }
+            // Wait for async content renders to settle before cloning.
+            if (config.strategies.contentReady) {
+                await config.strategies.contentReady(cloneTarget, page);
+                // Revalidate: the element may have recycled during the await.
+                if (rescanForRow) {
+                    let postIdx;
+                    try {
+                        const r = await resolveRI(cloneTarget);
+                        postIdx = r !== undefined ? (0, rowResolution_1.normalizeRowIndexResult)(r).index : undefined;
+                    }
+                    catch (_l) {
+                        postIdx = undefined;
+                    }
+                    if (postIdx !== rowIndex) {
+                        const reFound = await rescanForRow();
+                        if (reFound)
+                            cloneTarget = reFound;
+                    }
+                }
+            }
             // Step 1: clone row in browser memory (NOT in the DOM), extract text + row HTML.
             // Uses textContent (not innerText) because the clone is detached — innerText
             // falls back to textContent on detached nodes per HTML spec, so be explicit.
-            const cloneHandle = await rowLocator.evaluateHandle(el => el.cloneNode(true));
+            const cloneHandle = await cloneTarget.evaluateHandle(el => el.cloneNode(true));
             let snapshot;
             try {
                 snapshot = await cloneHandle.evaluate((row, sel) => {
@@ -491,7 +574,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                     await materializeRow();
                 const result = {};
                 for (const [col, idx] of columnsToProcess) {
-                    const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col];
+                    const columnOverride = (_b = config.columnOverrides) === null || _b === void 0 ? void 0 : _b[col];
                     const mapper = columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read;
                     if (mapper) {
                         const cell = page.locator(`#${snapId}`).locator(cellSel).nth(idx);
@@ -508,7 +591,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                         result[col] = snapshot.cells[idx].text;
                     }
                 }
-                for (const [name, def] of Object.entries((_b = config.syntheticColumns) !== null && _b !== void 0 ? _b : {})) {
+                for (const [name, def] of Object.entries((_c = config.syntheticColumns) !== null && _c !== void 0 ? _c : {})) {
                     if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(name))
                         continue;
                     const snapshotRow = Object.create(smart);
@@ -607,7 +690,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             // Re-pin to the correct logical row before reading this column (#366).
             const stableRow = await resolveStableRow();
             // Check if we have a column override for this column
-            const columnOverride = (_c = config.columnOverrides) === null || _c === void 0 ? void 0 : _c[col];
+            const columnOverride = (_d = config.columnOverrides) === null || _d === void 0 ? void 0 : _d[col];
             const mapper = columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read;
             // --- Navigation Logic Start ---
             const cell = config.strategies.getCellLocator
@@ -634,7 +717,8 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 index: idx,
                 rowLocator: stableRow,
                 rowIndex,
-                barrier: smart._barrier
+                barrier: smart._barrier,
+                allowMissingCell: !!mapper,
             });
             if (navigatedCell) {
                 targetCell = navigatedCell;
@@ -654,15 +738,29 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 });
             }
             // Cell loading wait (if configured)
-            const isCellLoading = (_d = config.strategies.loading) === null || _d === void 0 ? void 0 : _d.isCellLoading;
-            const rawCellTimeout = (_e = config.strategies.loading) === null || _e === void 0 ? void 0 : _e.cellLoadingTimeout;
+            const isCellLoading = (_e = config.strategies.loading) === null || _e === void 0 ? void 0 : _e.isCellLoading;
+            const rawCellTimeout = (_f = config.strategies.loading) === null || _f === void 0 ? void 0 : _f.cellLoadingTimeout;
             // undefined = unset (read as-is immediately); 0 = no wait (immediate check); >0 = wait up to N ms
             const cellLoadingTimeout = rawCellTimeout !== undefined && Number.isFinite(rawCellTimeout) && rawCellTimeout >= 0
                 ? rawCellTimeout
                 : undefined;
-            const onCellLoadingTimeout = (_g = (_f = config.strategies.loading) === null || _f === void 0 ? void 0 : _f.onCellLoadingTimeout) !== null && _g !== void 0 ? _g : 'read-as-is';
-            if (isCellLoading && await isCellLoading(targetCell, col, smart)) {
-                if (cellLoadingTimeout !== undefined) {
+            const onCellLoadingTimeout = (_h = (_g = config.strategies.loading) === null || _g === void 0 ? void 0 : _g.onCellLoadingTimeout) !== null && _h !== void 0 ? _h : 'read-as-is';
+            if (isCellLoading) {
+                let loading = await isCellLoading(targetCell, col, smart);
+                // First-paint race: the cell node can attach a tick before the loading
+                // indicator mounts. A single false-negative then reads "" and skips
+                // onCellLoadingTimeout. Only grace when the cell still looks empty.
+                if (!loading && cellLoadingTimeout !== undefined && cellLoadingTimeout > 0) {
+                    const peek = await targetCell.evaluate((el) => (el.textContent || '').trim()).catch(() => '');
+                    if (peek === '') {
+                        const graceDeadline = Date.now() + Math.min(250, cellLoadingTimeout);
+                        while (!loading && Date.now() < graceDeadline) {
+                            await page.waitForTimeout(25);
+                            loading = await isCellLoading(targetCell, col, smart);
+                        }
+                    }
+                }
+                if (loading && cellLoadingTimeout !== undefined) {
                     (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — waiting up to ${cellLoadingTimeout}ms`);
                     const deadline = Date.now() + cellLoadingTimeout;
                     let cellResolved = !(await isCellLoading(targetCell, col, smart)); // immediate check (handles timeout=0)
@@ -699,7 +797,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 result[col] = (text || '').trim();
             }
         }
-        for (const [name, def] of Object.entries((_h = config.syntheticColumns) !== null && _h !== void 0 ? _h : {})) {
+        for (const [name, def] of Object.entries((_j = config.syntheticColumns) !== null && _j !== void 0 ? _j : {})) {
             if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(name))
                 continue;
             const snapshotRow = Object.create(smart);
@@ -775,6 +873,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         (0, debugUtils_1.logDebug)(config, 'info', 'Row fill complete');
     };
     smart.bringIntoView = async () => {
+        var _a;
         if (rowIndex === undefined) {
             (0, debugUtils_1.logDebug)(config, 'info', 'bringIntoView called on a row with unknown rowIndex (e.g. from getRow()). ' +
                 'Page navigation and scrolling will proceed, but virtual-scroll keyboard navigation will be skipped. ' +
@@ -821,8 +920,20 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         }
         // Delay after pagination/finding before scrolling
         await (0, debugUtils_1.debugDelay)(config, 'findRow');
-        // Scroll row into view using Playwright's built-in method
-        await rowLocator.scrollIntoViewIfNeeded();
+        // Prefer viewport.scrollToRow when configured (#430). scrollIntoViewIfNeeded adjusts
+        // both axes and can evict sibling rows on recycling virtualizers.
+        const viewport = config.strategies.viewport;
+        const logicalRowIndex = (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow) && renderWindowPosition
+            ? (_a = (await (0, rowResolution_1.resolveLogicalRowIndex)(rowLocator, config, () => undefined))) === null || _a === void 0 ? void 0 : _a.index
+            : rowIndex;
+        if ((viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow) && typeof logicalRowIndex === 'number') {
+            const page = rootLocator.page();
+            (0, debugUtils_1.logDebug)(config, 'verbose', `bringIntoView: viewport.scrollToRow(${logicalRowIndex})`);
+            await viewport.scrollToRow({ root: rootLocator, config, page, resolve, getHeaders: parentTable === null || parentTable === void 0 ? void 0 : parentTable.getHeaders }, logicalRowIndex);
+        }
+        else {
+            await rowLocator.scrollIntoViewIfNeeded();
+        }
     };
     return smart;
 };

package/dist/strategies/columns.d.ts

@@ -12,7 +12,9 @@ export interface NavigationPrimitives {
     goHome?: (context: StrategyContext) => Promise<void>;
     /**
      * After vertical moves, run before horizontal steps when the target column index is 0.
-     * Use for horizontally virtualized a11y tables (e.g. Glide) so `td[aria-colindex="1"]` exists again.
+     * Use for horizontally virtualized tables so the first column exists in the DOM again
+     * (e.g. set scrollLeft = 0). If the table needs keyboard `Home` or canvas focus, put that
+     * here — the core orchestrator does not special-case those behaviors.
      * Do not reset vertical scroll here — RDG-style `goHome` is often unsuitable.
      */
     snapFirstColumnIntoView?: (context: StrategyContext) => Promise<void>;
@@ -33,7 +35,8 @@ export interface NavigationPrimitives {
     maxWaitMs?: number;
 }
 /**
- * @deprecated Use NavigationPrimitives instead. This will be removed in a future version.
+ * @deprecated Use NavigationPrimitives (`strategies.navigation`) instead. Removed from
+ * the public `Strategies` namespace in #428; this type remains for transitional typings.
  * Defines the contract for a cell navigation strategy.
  */
 export type CellNavigationStrategy = (context: StrategyContext & {
@@ -46,10 +49,3 @@ export type CellNavigationStrategy = (context: StrategyContext & {
         locator: Locator;
     } | null;
 }) => Promise<void>;
-export declare const CellNavigationStrategies: {
-    /**
-     * Default strategy: Assumes column is accessible or standard scrolling works.
-     * No specific action taken other than what Playwright's default locator handling does.
-     */
-    default: () => Promise<void>;
-};

package/dist/strategies/columns.js

@@ -1,12 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CellNavigationStrategies = void 0;
-exports.CellNavigationStrategies = {
-    /**
-     * Default strategy: Assumes column is accessible or standard scrolling works.
-     * No specific action taken other than what Playwright's default locator handling does.
-     */
-    default: async () => {
-        // No-op
-    }
-};

package/dist/strategies/contentReady.d.ts

@@ -0,0 +1,20 @@
+import type { ContentReadyStrategy } from '../types';
+export type { ContentReadyStrategy };
+export declare const ContentReadyStrategies: {
+    /**
+     * Polls the row's text content until two consecutive reads match.
+     */
+    textStable: (options?: {
+        timeout?: number;
+        interval?: number;
+    }) => ContentReadyStrategy;
+    /**
+     * Uses MutationObserver to wait for DOM mutations on the row's subtree
+     * to settle. Resolves when no mutations occur for `quietPeriod` ms, or
+     * when `timeout` expires.
+     */
+    mutationSettled: (options?: {
+        timeout?: number;
+        quietPeriod?: number;
+    }) => ContentReadyStrategy;
+};