@rickcedwhat/playwright-smart-table 6.17.0 → 6.18.0

package/dist/engine/rowFinder.js

@@ -47,7 +47,7 @@ class RowFinder {
         const tracker = new elementTracker_1.ElementTracker('findRows');
         try {
             const collectMatches = async () => {
-                var _a, _b, _c, _d, _e;
+                var _a, _b, _c, _d, _e, _f;
                 let rowLocators = this.resolve(this.config.rowSelector, this.rootLocator);
                 // Only apply filters if we have them
                 if (Object.keys(filtersRecord).length > 0) {
@@ -69,7 +69,13 @@ class RowFinder {
                 const useBarrier = this.config.concurrency === 'synchronized' && newIndices.length > 1;
                 const barrier = useBarrier ? new navigationBarrier_1.NavigationBarrier(newIndices.length) : undefined;
                 for (const idx of newIndices) {
-                    const smartRow = this.makeSmartRow(currentRows[idx], map, allRows.length, this.tableState.currentPageIndex, barrier);
+                    // Use the configured strategy (O(1), e.g. MUI data-rowindex) when available.
+                    // Without a strategy, fall back to sequential position to avoid the O(n)
+                    // elementHandle scan that resolveRowIndex() would otherwise perform per row.
+                    const rowIndex = this.config.strategies.resolveRowIndex
+                        ? ((_f = await this.config.strategies.resolveRowIndex(currentRows[idx])) !== null && _f !== void 0 ? _f : allRows.length)
+                        : allRows.length;
+                    const smartRow = this.makeSmartRow(currentRows[idx], map, rowIndex, this.tableState.currentPageIndex, barrier);
                     if (isRowLoading && await isRowLoading(smartRow)) {
                         if (rowLoadingTimeout === undefined) {
                             // No timeout configured (or invalid value) — legacy skip behavior
@@ -110,7 +116,11 @@ class RowFinder {
             await collectMatches();
             // Pagination Loop
             while (pagesScanned < effectiveMaxPages && this.config.strategies.pagination) {
-                const useBulk = (options === null || options === void 0 ? void 0 : options.useBulkPagination) !== false && !!((_c = this.config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNextBulk);
+                // Default to single-step goNext; bulk is opt-in via useBulkPagination: true (#349).
+                // Bulk-by-default made findRows jump N pages per advance and silently skip the
+                // rows on intermediate pages. When only a bulk primitive exists, _advancePage
+                // still falls back to it.
+                const useBulk = (options === null || options === void 0 ? void 0 : options.useBulkPagination) === true && !!((_c = this.config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNextBulk);
                 const prevPage = this.tableState.currentPageIndex;
                 const didPaginate = await this.advancePage(useBulk);
                 if (!didPaginate) {
@@ -174,7 +184,9 @@ class RowFinder {
                 return matchedRows.first();
             if (pagesScanned < effectiveMaxPages) {
                 (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Not found. Attempting pagination...`);
-                const useBulk = options.useBulkPagination !== false && !!((_c = this.config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNextBulk);
+                // Default to single-step goNext; bulk is opt-in via useBulkPagination: true (#349).
+                // Bulk-by-default made findRow jump past the page holding the target row.
+                const useBulk = options.useBulkPagination === true && !!((_c = this.config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNextBulk);
                 const prevPage = this.tableState.currentPageIndex;
                 const didLoadMore = await this.advancePage(useBulk);
                 if (didLoadMore) {
@@ -192,17 +204,29 @@ class RowFinder {
         }
     }
     async resolveRowIndex(rowLocator) {
-        const allRows = await this.resolve(this.config.rowSelector, this.rootLocator).all();
+        if (this.config.strategies.resolveRowIndex) {
+            const result = await this.config.strategies.resolveRowIndex(rowLocator);
+            if (result !== undefined)
+                return result;
+            // Strategy returned undefined — fall through to DOM scan below.
+        }
+        // Fallback: find the row's position in the current DOM order in a SINGLE roundtrip.
+        // Previously this looped over every row calling elementHandle() + evaluate() per row
+        // (O(n) CDP roundtrips, and elementHandle() is soft-deprecated). We now resolve the
+        // target once and let evaluateAll compare it against the full row set in the browser.
+        // The row set is resolved through the same selector/scope as everywhere else, so a
+        // string, function, or Locator rowSelector all behave identically. (#350)
         const targetHandle = await rowLocator.elementHandle();
         if (!targetHandle)
             return undefined;
-        for (let i = 0; i < allRows.length; i++) {
-            const handle = await allRows[i].elementHandle();
-            if (handle && await handle.evaluate((el, t) => el === t, targetHandle)) {
-                return i;
-            }
+        try {
+            const rowsLocator = this.resolve(this.config.rowSelector, this.rootLocator);
+            const index = await rowsLocator.evaluateAll((rows, target) => rows.indexOf(target), targetHandle);
+            return index >= 0 ? index : undefined;
+        }
+        finally {
+            await targetHandle.dispose();
         }
-        return undefined;
     }
 }
 exports.RowFinder = RowFinder;

package/dist/engine/tableIteration.js

@@ -20,7 +20,7 @@ async function runForEach(env, callback, options = {}) {
  * Concurrency: `parallel` | `synchronized` | `sequential` (see RowIterationOptions).
  */
 async function runMap(env, callback, options = {}, label = 'map') {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     const map = env.getMap();
     const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : env.config.maxPages;
     const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : env.config.strategies.dedupe;
@@ -34,6 +34,21 @@ async function runMap(env, callback, options = {}, label = 'map') {
     const useMutex = concurrency === 'sequential';
     const useBulk = (_e = options.useBulkPagination) !== null && _e !== void 0 ? _e : false;
     const tracker = new elementTracker_1.ElementTracker(label);
+    // Row-level loading gate (Bug #355). Must run BEFORE the dedupe strategy so
+    // content-based dedupe keys are computed on the row's final loaded state — a key
+    // computed on a skeleton changes once the row loads, and the ElementTracker
+    // re-flags the row (text signature changed), producing duplicates.
+    // Semantics mirror findRows (rowFinder.ts), with one deliberate difference:
+    // findRows drops loading rows when no timeout is set (legacy skip), but map/forEach
+    // historically visited every row — so without a timeout we process the row as-is.
+    const isRowLoading = (_f = env.config.strategies.loading) === null || _f === void 0 ? void 0 : _f.isRowLoading;
+    const rawRowTimeout = (_g = env.config.strategies.loading) === null || _g === void 0 ? void 0 : _g.rowLoadingTimeout;
+    // undefined = unset (process as-is); 0 = no wait (immediate re-check); >0 = wait up to N ms
+    // Non-finite values are treated as unset (defensive guard against Infinity/NaN)
+    const rowLoadingTimeout = rawRowTimeout !== undefined && Number.isFinite(rawRowTimeout) && rawRowTimeout >= 0
+        ? rawRowTimeout
+        : undefined;
+    const onRowLoadingTimeout = (_j = (_h = env.config.strategies.loading) === null || _h === void 0 ? void 0 : _h.onRowLoadingTimeout) !== null && _j !== void 0 ? _j : 'read-as-is';
     log(env.config, `${label}: starting (maxPages=${effectiveMaxPages}, mode=${concurrency}, dedupe=${!!dedupeStrategy})`);
     const results = [];
     try {
@@ -73,6 +88,25 @@ async function runMap(env, callback, options = {}, label = 'map') {
                         if (stopped && row.rowIndex > stoppedIndex) {
                             return SKIP;
                         }
+                        // Wait for the row to finish loading BEFORE evaluating its dedupe key (Bug #355).
+                        if (isRowLoading && rowLoadingTimeout !== undefined && await isRowLoading(row)) {
+                            log(env.config, `${label}: row ${row.rowIndex} — waiting up to ${rowLoadingTimeout}ms for row to load`);
+                            const deadline = Date.now() + rowLoadingTimeout;
+                            let resolved = !(await isRowLoading(row)); // immediate check (handles timeout=0)
+                            while (!resolved && Date.now() < deadline) {
+                                await env.getPage().waitForTimeout(100);
+                                resolved = !(await isRowLoading(row));
+                            }
+                            if (!resolved) {
+                                log(env.config, `${label}: row ${row.rowIndex} — still loading after ${rowLoadingTimeout}ms, action: ${onRowLoadingTimeout}`);
+                                if (onRowLoadingTimeout === 'skip')
+                                    return SKIP;
+                                if (onRowLoadingTimeout === 'throw') {
+                                    throw new Error(`[SmartTable] Row ${row.rowIndex} did not finish loading within ${rowLoadingTimeout}ms`);
+                                }
+                                // 'read-as-is': fall through and process the row
+                            }
+                        }
                         if (dedupeKeys && dedupeStrategy) {
                             const key = await dedupeStrategy(row);
                             if (dedupeKeys.has(key)) {

package/dist/packageVersion.d.ts

@@ -3,4 +3,4 @@
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.17.0";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.18.0";

package/dist/packageVersion.js

@@ -6,4 +6,4 @@ exports.PLAYWRIGHT_SMART_TABLE_VERSION = void 0;
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.17.0";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.18.0";

package/dist/presets/mui.js

@@ -196,7 +196,12 @@ function createMuiDataGrid(opts) {
         rowSelector: '.MuiDataGrid-row',
         cellSelector: '.MuiDataGrid-cell',
         headerSelector: '.MuiDataGrid-columnHeader',
+        concurrency: 'synchronized',
         strategies: {
+            resolveRowIndex: async (row) => {
+                const v = await row.getAttribute('data-rowindex').catch(() => null);
+                return v !== null && !isNaN(Number(v)) ? Number(v) : undefined;
+            },
             pagination: {
                 goNext: async (context) => {
                     const footer = context.root.locator('.MuiDataGrid-footerContainer');
@@ -325,9 +330,13 @@ function createMuiDataGrid(opts) {
                 // DataGrid uses data-rowindex for its own virtualization management
                 return (_a = (await row.getAttribute('data-rowindex').catch(() => null))) !== null && _a !== void 0 ? _a : '';
             },
-            getCellLocator: ({ row, columnIndex }) => {
-                // Horizontal virtualization uses aria-colindex (1-indexed)
-                return row.locator(`[aria-colindex="${columnIndex + 1}"]`);
+            getCellLocator: ({ row, root, columnIndex, rowIndex }) => {
+                // Use data-rowindex for a stable row reference: nth-based locators break after
+                // vertical eviction because the DOM order shifts when rows are removed/added.
+                const stableRow = typeof rowIndex === 'number'
+                    ? root.locator(`[data-rowindex="${rowIndex}"]`)
+                    : row;
+                return stableRow.locator(`[aria-colindex="${columnIndex + 1}"]`);
             },
             // MUI DataGrid virtualizes rows vertically (always) and columns horizontally (when
             // columnBuffer is configured). The virtualScroller is a descendant of root, so
@@ -348,12 +357,39 @@ function createMuiDataGrid(opts) {
                     const rowSel = config.rowSelector;
                     const cellSel = typeof config.cellSelector === 'string' ? config.cellSelector : '[aria-colindex]';
                     return root.evaluate((el, { rowSel, cellSel }) => {
-                        const firstRow = el.querySelector(rowSel);
-                        if (!firstRow)
+                        const scroller = el.querySelector('.MuiDataGrid-virtualScroller');
+                        const allRows = Array.from(el.querySelectorAll(rowSel));
+                        if (!allRows.length)
                             return { first: 0, last: 0 };
-                        const indices = Array.from(firstRow.querySelectorAll(cellSel))
-                            .map(c => Number(c.getAttribute('aria-colindex')) - 1)
-                            .filter(n => !isNaN(n));
+                        // Use a row that's fully within the scroller's viewport bounds.
+                        // The first DOM row is often an overscan row with extra columns rendered
+                        // outside the clip boundary, causing the range to appear wider than it is.
+                        let targetRow = allRows[0];
+                        if (scroller) {
+                            const scrollerRect = scroller.getBoundingClientRect();
+                            const inView = allRows.find(r => {
+                                const rect = r.getBoundingClientRect();
+                                return rect.height > 0 &&
+                                    rect.top >= scrollerRect.top &&
+                                    rect.bottom <= scrollerRect.bottom;
+                            });
+                            if (inView)
+                                targetRow = inView;
+                        }
+                        const scrollerRect = scroller === null || scroller === void 0 ? void 0 : scroller.getBoundingClientRect();
+                        const indices = Array.from(targetRow.querySelectorAll(cellSel))
+                            .map(c => {
+                            if (scrollerRect) {
+                                const rect = c.getBoundingClientRect();
+                                const visible = rect.width > 0 &&
+                                    rect.right > scrollerRect.left &&
+                                    rect.left < scrollerRect.right;
+                                if (!visible)
+                                    return NaN;
+                            }
+                            return Number(c.getAttribute('aria-colindex')) - 1;
+                        })
+                            .filter(n => !isNaN(n) && n >= 0);
                         if (!indices.length)
                             return { first: 0, last: 0 };
                         return { first: Math.min(...indices), last: Math.max(...indices) };
@@ -365,40 +401,85 @@ function createMuiDataGrid(opts) {
                         const scroller = el.querySelector('.MuiDataGrid-virtualScroller');
                         if (!scroller)
                             return;
-                        const row = el.querySelector(`${rowSel}[data-rowindex="${idx}"]`);
-                        if (row) {
-                            row.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+                        const existingRow = el.querySelector(`${rowSel}[data-rowindex="${idx}"]`);
+                        if (existingRow) {
+                            // Row is in DOM — adjust scrollTop only, never scrollLeft.
+                            const scrollerRect = scroller.getBoundingClientRect();
+                            const rowRect = existingRow.getBoundingClientRect();
+                            if (rowRect.top < scrollerRect.top) {
+                                scroller.scrollTop -= (scrollerRect.top - rowRect.top) + 4;
+                            }
+                            else if (rowRect.bottom > scrollerRect.bottom) {
+                                scroller.scrollTop += (rowRect.bottom - scrollerRect.bottom) + 4;
+                            }
                             return;
                         }
+                        // Row not in DOM — interpolate from visible rows' style.top positions.
+                        // This is far more accurate than estimating from row heights because MUI
+                        // DataGrid uses absolute positioning (style.top) for each virtual row.
                         const visibleRows = Array.from(el.querySelectorAll(rowSel));
+                        const rowsWithPos = visibleRows
+                            .map(r => {
+                            const ridx = Number(r.getAttribute('data-rowindex'));
+                            const top = parseFloat(r.style.top);
+                            return { ridx, top };
+                        })
+                            .filter(r => !isNaN(r.ridx) && !isNaN(r.top) && r.top >= 0)
+                            .sort((a, b) => a.ridx - b.ridx);
+                        if (rowsWithPos.length >= 2) {
+                            const first = rowsWithPos[0];
+                            const last = rowsWithPos[rowsWithPos.length - 1];
+                            const rowHeight = (last.top - first.top) / (last.ridx - first.ridx);
+                            const targetTop = first.top + (idx - first.ridx) * rowHeight;
+                            scroller.scrollTop = Math.max(0, targetTop - 20);
+                            return;
+                        }
+                        // Fallback: use bounding-rect heights.
                         const heights = visibleRows
-                            .map(visibleRow => visibleRow.getBoundingClientRect().height)
-                            .filter(height => height > 0);
+                            .map(r => r.getBoundingClientRect().height)
+                            .filter(h => h > 0);
                         const estimatedHeight = heights.length
-                            ? heights.reduce((sum, height) => sum + height, 0) / heights.length
+                            ? heights.reduce((s, h) => s + h, 0) / heights.length
                             : 52;
                         scroller.scrollTop = Math.max(0, idx * estimatedHeight - 20);
                     }, { rowSel, idx: rowIndex });
+                    // Swallow timeout: the row may still be readable if it re-enters the
+                    // virtual viewport. targetReached() in the caller is the authoritative check.
                     await root.locator(`${rowSel}[data-rowindex="${rowIndex}"]`)
-                        .waitFor({ state: 'attached', timeout: 3000 });
+                        .waitFor({ state: 'attached', timeout: 3000 })
+                        .catch(() => { });
                 },
-                scrollToColumn: async ({ root, config }, colIndex) => {
+                scrollToColumn: async ({ root, config, page }, colIndex) => {
                     const headerSel = typeof config.headerSelector === 'string' ? config.headerSelector : null;
                     await root.evaluate((el, { headerSel, idx }) => {
-                        // virtualScroller is a descendant — querySelector, not closest
                         const scroller = el.querySelector('.MuiDataGrid-virtualScroller');
                         if (!scroller || !headerSel)
                             return;
                         const headers = Array.from(el.querySelectorAll(headerSel));
-                        const target = headers[idx];
+                        const targetAriaIdx = idx + 1; // aria-colindex is 1-based
+                        // Find header by aria-colindex, NOT by DOM position. With column
+                        // virtualization, DOM order does not match colIndex — only headers in
+                        // the current virtual window are rendered, so headers[idx] would be wrong.
+                        const target = headers.find(h => Number(h.getAttribute('aria-colindex')) === targetAriaIdx);
                         if (!target) {
-                            const widths = headers
-                                .map(header => header.getBoundingClientRect().width)
-                                .filter(width => width > 0);
-                            const estimatedWidth = widths.length
-                                ? widths.reduce((sum, width) => sum + width, 0) / widths.length
-                                : 100;
-                            scroller.scrollLeft = Math.max(0, idx * estimatedWidth - 20);
+                            // Header not in DOM (column virtualized away). Interpolate scrollLeft
+                            // from the positions of currently visible headers.
+                            const visibleHeaders = headers
+                                .map(h => ({ colIdx: Number(h.getAttribute('aria-colindex')), rect: h.getBoundingClientRect() }))
+                                .filter(h => !isNaN(h.colIdx) && h.rect.width > 0)
+                                .sort((a, b) => a.colIdx - b.colIdx);
+                            if (visibleHeaders.length >= 2) {
+                                const first = visibleHeaders[0];
+                                const last = visibleHeaders[visibleHeaders.length - 1];
+                                const pxPerCol = (last.rect.left - first.rect.left) / (last.colIdx - first.colIdx);
+                                const sRect = scroller.getBoundingClientRect();
+                                const firstAbsLeft = first.rect.left - sRect.left + scroller.scrollLeft;
+                                scroller.scrollLeft = Math.max(0, firstAbsLeft + (targetAriaIdx - first.colIdx) * pxPerCol - 20);
+                            }
+                            else if (visibleHeaders.length === 1) {
+                                const h = visibleHeaders[0];
+                                scroller.scrollLeft = Math.max(0, scroller.scrollLeft + (targetAriaIdx - h.colIdx) * h.rect.width - 20);
+                            }
                             return;
                         }
                         const cRect = scroller.getBoundingClientRect();
@@ -410,9 +491,21 @@ function createMuiDataGrid(opts) {
                             scroller.scrollLeft += (tRect.right - cRect.right) + 20;
                         }
                     }, { headerSel, idx: colIndex });
-                    await root.locator(`${config.rowSelector} [aria-colindex="${colIndex + 1}"]`)
+                    // Wait for any cell with this colIndex to appear. With column virtualization
+                    // (32 cols), MUI DataGrid updates the DOM on requestAnimationFrame after a
+                    // scrollLeft change — so we may need to wait a tick. If it doesn't appear,
+                    // fall back to a brief pause; targetReached() is the authoritative gate.
+                    // Scope to body cells (.MuiDataGrid-cell) — [aria-colindex] also matches
+                    // column headers which appear before body cells after a scroll.
+                    const cellSel = typeof config.cellSelector === 'string' ? config.cellSelector : '.MuiDataGrid-cell';
+                    const appeared = await root.locator(`${cellSel}[aria-colindex="${colIndex + 1}"]`)
                         .first()
-                        .waitFor({ state: 'attached', timeout: 3000 });
+                        .waitFor({ state: 'attached', timeout: 2000 })
+                        .then(() => true)
+                        .catch(() => false);
+                    if (!appeared) {
+                        await page.waitForTimeout(300);
+                    }
                 },
             },
             loading: {

package/dist/smartRow.js

@@ -26,6 +26,9 @@ const _navigateToCell = async (params) => {
         // Optimization: Check if we are ALREADY at the target cell
         if (activeCell && activeCell.rowIndex === rowIndex && activeCell.columnIndex === index) {
             (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: Already at target cell {row: ${rowIndex}, col: ${index}}`);
+            // Still participate in the barrier (no-op) so peers are not left waiting.
+            if (barrier)
+                await barrier.sync(index);
             return activeCell.locator;
         }
     }
@@ -63,6 +66,10 @@ const _navigateToCell = async (params) => {
                 const rowVisible = !rowRange || (rowIndex >= rowRange.first && rowIndex <= rowRange.last);
                 if (rowVisible && await targetReached()) {
                     (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.
+                    if (barrier)
+                        await barrier.sync(index);
                     return getCellLocator();
                 }
             }
@@ -76,33 +83,12 @@ const _navigateToCell = async (params) => {
         // Column is out of view. Scroll to bring it in.
         // In synchronized mode, the last row to arrive triggers the scroll once for all rows.
         const scrollIntoViewport = async () => {
-            // Reuse the range fetched during the fast-path check; re-query only if unknown.
-            const colRange = knownColRange !== null && knownColRange !== void 0 ? knownColRange : (viewport.getVisibleColumnRange
-                ? await viewport.getVisibleColumnRange(context)
-                : null);
-            const colOutOfView = !colRange || index < colRange.first || index > colRange.last;
-            if (colOutOfView) {
-                (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} out of view, scrolling`);
-                if (viewport.scrollToColumn) {
-                    await viewport.scrollToColumn(context, index);
-                }
-            }
-            // Some row locators (notably rows returned by findRow()) have a logical
-            // rowIndex that is not the grid's viewport coordinate. If the target cell
-            // is already mounted after any column scroll, avoid a misleading row jump.
-            if (await targetReached()) {
-                return;
-            }
-            // 2D scroll hazard: horizontal scroll may evict the target row from the DOM.
-            // scrollToRow moves the viewport to one specific row, which would evict every
-            // other row in a parallel batch — safe only when there are no peers to evict.
-            if ((!barrier || !barrier.isParallel()) && viewport.scrollToRow && viewport.getVisibleRowRange) {
-                const rowRange = await viewport.getVisibleRowRange(context);
-                const rowOutOfView = rowRange && (rowIndex < rowRange.first || rowIndex > rowRange.last);
-                if (rowOutOfView) {
-                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: row ${rowIndex} out of view after col scroll, recovering`);
-                    await viewport.scrollToRow(context, rowIndex);
-                }
+            // Always scroll — scrollToColumn is idempotent (bounds-checks before acting).
+            // The trigger row may already have the cell via overscan, but other rows in the
+            // batch might not; skipping the scroll here would silently starve them.
+            (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} out of view, scrolling`);
+            if (viewport.scrollToColumn) {
+                await viewport.scrollToColumn(context, index);
             }
         };
         if (barrier) {
@@ -111,6 +97,27 @@ const _navigateToCell = async (params) => {
         else {
             await scrollIntoViewport();
         }
+        // Per-row 2D recovery: horizontal scroll may evict rows from the vertical viewport
+        // (scrollbar layout shift) or rows may simply be outside the virtual row window.
+        // Recovery is serialized via the barrier's mutex so concurrent rows don't race on
+        // scrollTop — adjacent rows often appear in view for free after the previous recovery.
+        // scrollToRow must only adjust scrollTop (not scrollLeft) to preserve the column
+        // position established by scrollToColumn.
+        if (!await targetReached() && viewport.scrollToRow && typeof rowIndex === 'number') {
+            const scrollToRow = viewport.scrollToRow;
+            const recover = async () => {
+                if (!await targetReached()) {
+                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: row ${rowIndex} evicted by col scroll, recovering`);
+                    await scrollToRow(context, rowIndex);
+                }
+            };
+            if (barrier) {
+                await barrier.runExclusiveRecovery(recover);
+            }
+            else {
+                await recover();
+            }
+        }
         if (await targetReached()) {
             return getCellLocator();
         }

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.mjs
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * headerSelector: (root) => root.locator('[role=\"columnheader\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */\n  root: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n  config: FinalTableConfig<any>;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in `toJSON` (and `columnOverrides.read`).\n *\n * Use this to scroll off-screen columns into view in **horizontally** virtualized tables,\n * wait for lazy-rendered content (popovers, tooltips, async cell renderers), or perform\n * any other pre-read setup that doesn't involve Y-axis scrolling.\n *\n * ---\n *\n * **\u26A0\uFE0F Y-scroll footgun \u2014 do NOT call `scrollIntoViewIfNeeded()` on row-virtualized grids.**\n *\n * `scrollIntoViewIfNeeded` adjusts *both* scroll axes. On grids that recycle DOM nodes\n * based on the Y position (MUI DataGrid, AG Grid, react-window, etc.) calling it will\n * shift the viewport vertically, unmounting the row you are currently reading and\n * silently returning stale or empty cell values for the remainder of the row.\n *\n * Safe uses:\n * - Column-only (X-axis) virtualization where rows are always in the DOM.\n * - Calling `scrollIntoViewIfNeeded` on the **header cell** only, when that header is\n *   guaranteed not to trigger a Y-scroll (e.g. sticky header grids).\n *\n * For grids with **both** row and column virtualization, use the `viewport` strategy\n * instead \u2014 it drives explicit `scrollToRow` / `scrollToColumn` calls and is aware of\n * the virtualization lifecycle.\n *\n * @example\n * // Safe: column-only horizontal virtualization (rows always in DOM)\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded(); // only scrolls X \u2014 rows stay mounted\n *   }\n * }\n *\n * @example\n * // Safe: wait for a lazy-rendered popover/tooltip before reading its text\n * strategies: {\n *   beforeCellRead: async ({ cell }) => {\n *     await cell.hover();\n *     await cell.page().waitForSelector('.cell-tooltip', { state: 'visible' });\n *   }\n * }\n */\nexport type BeforeCellReadFn = (args: {\n  /** The resolved cell locator */\n  cell: Locator;\n  columnName: string;\n  columnIndex: number;\n  row: Locator;\n  page: Page;\n  root: Locator;\n  /** Resolves a column name to its header cell locator */\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n}) => Promise<void>;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n/**\n * Viewport oracle strategies for virtualized tables.\n *\n * These tell the library *what is currently in the DOM* rather than *how to move*.\n * When present, the cell-reading engine uses them to jump directly to a target\n * row/column instead of stepping blindly with navigation primitives.\n *\n * This is the primary fix for the 2D scroll hazard: scrolling right to bring a\n * column into view can knock rows out of the vertical viewport (and vice versa).\n * With `getVisibleRowRange` the engine detects this and calls `scrollToRow` to\n * restore the row before reading \u2014 eliminating the hazard without polling loops.\n *\n * All members are optional. Supply whichever the underlying grid exposes:\n * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.\n * - Scroll primitives alone enable direct jumps without range awareness.\n * - Both together give the most reliable, fastest path.\n *\n * @example\n * // MUI DataGrid via apiRef\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const api = (el as any).__muiDataGrid__;\n *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };\n *       }),\n *     scrollToRow: async ({ root }, rowIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),\n *     scrollToColumn: async ({ root }, colIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),\n *   }\n * }\n *\n * @example\n * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const rows = [...el.querySelectorAll('[role=\"row\"][aria-rowindex]')];\n *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);\n *         return { first: Math.min(...idxs), last: Math.max(...idxs) };\n *       }),\n *   }\n * }\n */\nexport interface ViewportStrategy {\n  /**\n   * Returns the 0-based index range of rows currently rendered in the DOM.\n   * Used to detect when a target row has been scrolled out of view and needs recovery.\n   */\n  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Returns the 0-based index range of columns currently rendered in the DOM.\n   * Used to detect when a target column is not yet mounted before reading.\n   */\n  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Scrolls or jumps directly to make a row visible by 0-based index.\n   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.\n   */\n  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;\n\n  /**\n   * Scrolls or jumps directly to make a column visible by 0-based index.\n   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.\n   */\n  scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;\n\n  /**\n   * When true, disables the automatic memoization of getVisibleColumnRange and\n   * getVisibleRowRange results. By default the library caches each range value and\n   * invalidates it after the corresponding scroll call, eliminating redundant DOM\n   * evaluate() round-trips between scrolls.\n   */\n  disableCache?: boolean;\n}\n\n\n/**\n * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.\n * \n * Extends all standard Locator methods (click, isVisible, etc.).\n */\nexport type SmartCell = Locator & {\n  /**\n   * Scrolls/paginates to bring this specific cell into view using the configured strategies.\n   * Useful when the grid is horizontally virtualized and the column must be scrolled\n   * into view before it can be interacted with or read.\n   */\n  bringIntoView(): Promise<void>;\n};\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns SmartCell (Locator + bringIntoView)\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await emailCell.bringIntoView();\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): SmartCell;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Works when row position metadata is known (e.g., from getRowByIndex, findRow,\n   * findRows, filter, or async iteration).\n   * @throws Error if row position metadata is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to last page / scroll to bottom */\n  goToLast?: (context: TableContext) => Promise<boolean>;\n\n  /**\n   * Fetch the total number of pages currently available.\n   * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).\n   */\n  getTotalPages?: (context: TableContext) => Promise<number | null>;\n\n  /**\n   * Jump to specific page index (0-indexed).\n   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6\u201314).\n   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.\n   */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n\n  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */\n  nextBulkPages?: number;\n\n  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */\n  previousBulkPages?: number;\n\n  /**\n   * Called once during init() to sync the library's page counter with the actual DOM state.\n   * Use when a table may open on a page other than the first (e.g. a deep-linked URL that\n   * lands on page 5). Returns a 0-indexed page number.\n   * @example\n   * detectCurrentPage: async (root) => {\n   *   const text = await root.locator('[aria-current=\"page\"]').textContent();\n   *   return parseInt(text ?? '1') - 1;\n   * }\n   */\n  detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;\n}\n\nexport type PaginationStrategy = PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell.\n   * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\n// fallow-ignore-next-line unused-type\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria. Applied when using getRow/findRow/findRows with filters.\n * The default engine handles string, RegExp, number, and function (cell) => Locator filters.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: FilterValue };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading. Used after pagination/sort to wait for content.\n * E.g. isHeaderLoading for init stability; isTableLoading after sort/pagination.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n  isHeaderLoading?: (context: TableContext) => Promise<boolean>;\n\n  /**\n   * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.\n   * When not set, loading rows are immediately skipped (backward-compatible behavior).\n   */\n  rowLoadingTimeout?: number;\n\n  /**\n   * What to do when a row is still loading after rowLoadingTimeout ms.\n   * - 'skip': drop the row from results (matches legacy skip behavior)\n   * - 'read-as-is': include the row even though it's still loading (default)\n   * - 'throw': throw an error with row index and timeout info\n   * Defaults to 'read-as-is' when rowLoadingTimeout is set.\n   */\n  onRowLoadingTimeout?: 'skip' | 'read-as-is' | 'throw';\n\n  /**\n   * Predicate called before reading each cell. Return true if the cell is still loading.\n   * When cellLoadingTimeout is also set, the engine waits up to that many ms for the\n   * cell to resolve before applying onCellLoadingTimeout.\n   */\n  isCellLoading?: (cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<boolean>;\n\n  /**\n   * How long (ms) to wait for a loading cell to resolve before applying onCellLoadingTimeout.\n   * When not set and isCellLoading returns true, the cell is read as-is immediately.\n   */\n  cellLoadingTimeout?: number;\n\n  /**\n   * What to do when a cell is still loading after cellLoadingTimeout ms.\n   * - 'skip': use empty string for this cell value\n   * - 'read-as-is': read the cell content even though it's still loading (default)\n   * - 'throw': throw an error with column name, row index and timeout info\n   * - callback: called with (cell, columnName, row); its return value becomes the cell's string value\n   * Defaults to 'read-as-is' when cellLoadingTimeout is set.\n   */\n  onCellLoadingTimeout?:\n    | 'skip'\n    | 'read-as-is'\n    | 'throw'\n    | ((cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<string>);\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */\n  navigation?: NavigationPrimitives;\n\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /**\n   * Strategy for filtering rows. If present, FilterEngine will delegate filter application\n   * to this pluggable strategy.\n   */\n  filter?: FilterStrategy;\n  /**\n   * Hook called before each cell value is read in toJSON and columnOverrides.read.\n   * Fires for both the default innerText extraction and custom read mappers.\n   * Useful for scrolling off-screen columns into view in horizontally virtualized tables.\n   */\n  beforeCellRead?: BeforeCellReadFn;\n  /**\n   * Strategy for detecting loading states. Use this for table-, row-, and header-level readiness.\n   * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.\n   */\n  loading?: LoadingStrategy;\n\n  /**\n   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,\n   * Braintrust-style grids where both rows and columns are virtualized simultaneously).\n   *\n   * When present, the cell-reading engine uses these to jump directly to the target\n   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can\n   * knock rows out of the vertical viewport, and vice versa).\n   *\n   * Completely optional and additive \u2014 existing `navigation` primitives remain the fallback.\n   */\n  viewport?: ViewportStrategy;\n}\n\n\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /**\n   * Default concurrency strategy for iteration methods.\n   * Can be overridden by the options passed to forEach, map, or filter.\n   */\n  concurrency?: RowIterationMode;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n\n  /**\n   * Unified interface for reading and writing data to specific columns.\n   * Overrides both default extraction (toJSON) and filling (smartFill) logic.\n   */\n  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;\n}\n\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: string | ((root: Locator) => Locator);\n  rowSelector: string;\n  cellSelector: string | ((row: Locator) => Locator);\n  maxPages: number;\n  autoScroll: boolean;\n  concurrency?: RowIterationMode;\n  debug?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\n\n\n/** Callback context passed to forEach, map, and filter. */\nexport type RowIterationContext<T = any> = {\n  row: SmartRow<T>;\n  /** 0-based iteration counter \u2014 the order this row was visited, not its DOM position or grid identity. @deprecated Use `index` instead. `rowIndex` will be removed in v7.0.0. */\n  rowIndex: number;\n  /** 0-based iteration counter \u2014 the order this row was visited, not its DOM position or grid identity. */\n  index: number;\n  /** 0-based page index \u2014 which page this row was collected from. */\n  pageIndex: number;\n  stop: () => void;\n};\n\n/** Concurrency modes for row iteration. */\nexport type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';\n\n/** Shared options for forEach, map, and filter. */\nexport type RowIterationOptions = {\n  /** Maximum number of pages to iterate. Defaults to config.maxPages. */\n  maxPages?: number;\n  /**\n   * Concurrency strategy for iteration.\n   * - 'parallel': Full parallel execution of both navigation and actions.\n   * - 'synchronized': Parallel navigation (lock-step) with serial actions.\n   * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.\n   * @default 'parallel' (for map), 'sequential' (for forEach/filter)\n   */\n  concurrency?: RowIterationMode;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n  /**\n   * When true, use goNextBulk (if present) to advance pages during iteration.\n   * @default false \u2014 uses goNext for one-page-at-a-time advancement\n   */\n  useBulkPagination?: boolean;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number; pageIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult<T>>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.\n   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow<T>;\n\n  /**\n   * Gets a row by 0-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 0-based row index\n   */\n  getRowByIndex: (\n    index: number\n  ) => SmartRow<T>;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow<T>>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match (omit or pass {} for all rows)\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters?: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number, useBulkPagination?: boolean }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * Counts the number of rows currently on the page.\n   * Does not paginate.\n   */\n  countRows: () => Promise<number>;\n\n  /**\n   * Iterates over rows and extracts the value of a single column.\n   * More efficient than map + toJSON for single-column extraction.\n   * @param columnName - The name of the column to extract\n   * @param options - Iteration options\n   */\n  mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;\n\n  /**\n   * Iterates over rows and extracts the value of a single column as strings.\n   * @param columnName - The name of the column to extract\n   * @param options - Iteration options\n   */\n  getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `concurrency: 'parallel'`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `concurrency: 'sequential'` (or `'synchronized'`\n   * > when navigation must stay lock-step) to avoid overlapping interactions.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 use sequential (or synchronized) concurrency\n   * const assignees = await table.map(async ({ row }) => {\n   *   await row.getCell('Assignee').locator('button').click();\n   *   const name = await page.locator('.popover .name').innerText();\n   *   await page.keyboard.press('Escape');\n   *   return name;\n   * }, { concurrency: 'sequential' });\n   */\n  map<R>(\n    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Shorthand for `map()` + `reset()`. Iterates every row across all pages, applies the\n   * callback (defaults to `row.toJSON()`), then resets the table back to page 1 \u2014 even if\n   * the callback throws.\n   *\n   * @param callback - Optional map function. Defaults to `({ row }) => row.toJSON()`.\n   * @param options - Same options as `map()`.\n   *\n   * @example\n   * // Zero-arg: returns toJSON() for every row\n   * const rows = await table.toArray();\n   *\n   * @example\n   * // Custom callback\n   * const names = await table.toArray(({ row }) => row.getCell('Name').innerText());\n   *\n   * @example\n   * // With options\n   * const rows = await table.toArray(({ row }) => row.toJSON(), { concurrency: 'parallel' });\n   */\n  toArray<R = Record<string, unknown>>(\n    callback?: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.\n   * Rows are returned as-is \u2014 call `bringIntoView()` on each if needed.\n   * Execution is sequential by default.\n   *\n   * @param predicate - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * const active = await table.filter(async ({ row }) =>\n   *   await row.getCell('Status').innerText() === 'Active'\n   * );\n   */\n  filter(\n    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,\n    options?: RowIterationOptions\n  ): Promise<SmartRowArray<T>>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   * Automatically throws an Error containing the prompt.\n   */\n  generateConfig: () => Promise<void>;\n\n  /**\n   * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.\n   */\n  generateConfigPrompt: () => Promise<void>;\n}\n";
+export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * headerSelector: (root) => root.locator('[role=\"columnheader\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */\n  root: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n  config: FinalTableConfig<any>;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in `toJSON` (and `columnOverrides.read`).\n *\n * Use this to scroll off-screen columns into view in **horizontally** virtualized tables,\n * wait for lazy-rendered content (popovers, tooltips, async cell renderers), or perform\n * any other pre-read setup that doesn't involve Y-axis scrolling.\n *\n * ---\n *\n * **\u26A0\uFE0F Y-scroll footgun \u2014 do NOT call `scrollIntoViewIfNeeded()` on row-virtualized grids.**\n *\n * `scrollIntoViewIfNeeded` adjusts *both* scroll axes. On grids that recycle DOM nodes\n * based on the Y position (MUI DataGrid, AG Grid, react-window, etc.) calling it will\n * shift the viewport vertically, unmounting the row you are currently reading and\n * silently returning stale or empty cell values for the remainder of the row.\n *\n * Safe uses:\n * - Column-only (X-axis) virtualization where rows are always in the DOM.\n * - Calling `scrollIntoViewIfNeeded` on the **header cell** only, when that header is\n *   guaranteed not to trigger a Y-scroll (e.g. sticky header grids).\n *\n * For grids with **both** row and column virtualization, use the `viewport` strategy\n * instead \u2014 it drives explicit `scrollToRow` / `scrollToColumn` calls and is aware of\n * the virtualization lifecycle.\n *\n * @example\n * // Safe: column-only horizontal virtualization (rows always in DOM)\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded(); // only scrolls X \u2014 rows stay mounted\n *   }\n * }\n *\n * @example\n * // Safe: wait for a lazy-rendered popover/tooltip before reading its text\n * strategies: {\n *   beforeCellRead: async ({ cell }) => {\n *     await cell.hover();\n *     await cell.page().waitForSelector('.cell-tooltip', { state: 'visible' });\n *   }\n * }\n */\nexport type BeforeCellReadFn = (args: {\n  /** The resolved cell locator */\n  cell: Locator;\n  columnName: string;\n  columnIndex: number;\n  row: Locator;\n  page: Page;\n  root: Locator;\n  /** Resolves a column name to its header cell locator */\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n}) => Promise<void>;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n/**\n * Viewport oracle strategies for virtualized tables.\n *\n * These tell the library *what is currently in the DOM* rather than *how to move*.\n * When present, the cell-reading engine uses them to jump directly to a target\n * row/column instead of stepping blindly with navigation primitives.\n *\n * This is the primary fix for the 2D scroll hazard: scrolling right to bring a\n * column into view can knock rows out of the vertical viewport (and vice versa).\n * With `getVisibleRowRange` the engine detects this and calls `scrollToRow` to\n * restore the row before reading \u2014 eliminating the hazard without polling loops.\n *\n * All members are optional. Supply whichever the underlying grid exposes:\n * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.\n * - Scroll primitives alone enable direct jumps without range awareness.\n * - Both together give the most reliable, fastest path.\n *\n * @example\n * // MUI DataGrid via apiRef\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const api = (el as any).__muiDataGrid__;\n *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };\n *       }),\n *     scrollToRow: async ({ root }, rowIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),\n *     scrollToColumn: async ({ root }, colIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),\n *   }\n * }\n *\n * @example\n * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const rows = [...el.querySelectorAll('[role=\"row\"][aria-rowindex]')];\n *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);\n *         return { first: Math.min(...idxs), last: Math.max(...idxs) };\n *       }),\n *   }\n * }\n */\nexport interface ViewportStrategy {\n  /**\n   * Returns the 0-based index range of rows currently rendered in the DOM.\n   * Used to detect when a target row has been scrolled out of view and needs recovery.\n   */\n  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Returns the 0-based index range of columns currently rendered in the DOM.\n   * Used to detect when a target column is not yet mounted before reading.\n   */\n  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Scrolls or jumps directly to make a row visible by 0-based index.\n   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.\n   */\n  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;\n\n  /**\n   * Scrolls or jumps directly to make a column visible by 0-based index.\n   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.\n   */\n  scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;\n\n  /**\n   * When true, disables the automatic memoization of getVisibleColumnRange and\n   * getVisibleRowRange results. By default the library caches each range value and\n   * invalidates it after the corresponding scroll call, eliminating redundant DOM\n   * evaluate() round-trips between scrolls.\n   */\n  disableCache?: boolean;\n}\n\n\n/**\n * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.\n * \n * Extends all standard Locator methods (click, isVisible, etc.).\n */\nexport type SmartCell = Locator & {\n  /**\n   * Scrolls/paginates to bring this specific cell into view using the configured strategies.\n   * Useful when the grid is horizontally virtualized and the column must be scrolled\n   * into view before it can be interacted with or read.\n   */\n  bringIntoView(): Promise<void>;\n};\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns SmartCell (Locator + bringIntoView)\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await emailCell.bringIntoView();\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): SmartCell;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Works when row position metadata is known (e.g., from getRowByIndex, findRow,\n   * findRows, filter, or async iteration).\n   * @throws Error if row position metadata is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to last page / scroll to bottom */\n  goToLast?: (context: TableContext) => Promise<boolean>;\n\n  /**\n   * Fetch the total number of pages currently available.\n   * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).\n   */\n  getTotalPages?: (context: TableContext) => Promise<number | null>;\n\n  /**\n   * Jump to specific page index (0-indexed).\n   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6\u201314).\n   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.\n   */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n\n  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */\n  nextBulkPages?: number;\n\n  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */\n  previousBulkPages?: number;\n\n  /**\n   * Called once during init() to sync the library's page counter with the actual DOM state.\n   * Use when a table may open on a page other than the first (e.g. a deep-linked URL that\n   * lands on page 5). Returns a 0-indexed page number.\n   * @example\n   * detectCurrentPage: async (root) => {\n   *   const text = await root.locator('[aria-current=\"page\"]').textContent();\n   *   return parseInt(text ?? '1') - 1;\n   * }\n   */\n  detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;\n}\n\nexport type PaginationStrategy = PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell.\n   * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\n// fallow-ignore-next-line unused-type\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria. Applied when using getRow/findRow/findRows with filters.\n * The default engine handles string, RegExp, number, and function (cell) => Locator filters.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: FilterValue };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading. Used after pagination/sort to wait for content.\n * E.g. isHeaderLoading for init stability; isTableLoading after sort/pagination.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n  isHeaderLoading?: (context: TableContext) => Promise<boolean>;\n\n  /**\n   * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.\n   * Honored by findRows AND by map/forEach/filter, where the wait runs before the dedupe\n   * strategy so content-based dedupe keys see the row's final loaded state.\n   * When not set (backward-compatible behavior): findRows skips loading rows immediately;\n   * map/forEach/filter process them as-is.\n   */\n  rowLoadingTimeout?: number;\n\n  /**\n   * What to do when a row is still loading after rowLoadingTimeout ms.\n   * - 'skip': drop the row from results (matches legacy skip behavior)\n   * - 'read-as-is': include the row even though it's still loading (default)\n   * - 'throw': throw an error with row index and timeout info\n   * Defaults to 'read-as-is' when rowLoadingTimeout is set.\n   */\n  onRowLoadingTimeout?: 'skip' | 'read-as-is' | 'throw';\n\n  /**\n   * Predicate called before reading each cell. Return true if the cell is still loading.\n   * When cellLoadingTimeout is also set, the engine waits up to that many ms for the\n   * cell to resolve before applying onCellLoadingTimeout.\n   */\n  isCellLoading?: (cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<boolean>;\n\n  /**\n   * How long (ms) to wait for a loading cell to resolve before applying onCellLoadingTimeout.\n   * When not set and isCellLoading returns true, the cell is read as-is immediately.\n   */\n  cellLoadingTimeout?: number;\n\n  /**\n   * What to do when a cell is still loading after cellLoadingTimeout ms.\n   * - 'skip': use empty string for this cell value\n   * - 'read-as-is': read the cell content even though it's still loading (default)\n   * - 'throw': throw an error with column name, row index and timeout info\n   * - callback: called with (cell, columnName, row); its return value becomes the cell's string value\n   * Defaults to 'read-as-is' when cellLoadingTimeout is set.\n   */\n  onCellLoadingTimeout?:\n    | 'skip'\n    | 'read-as-is'\n    | 'throw'\n    | ((cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<string>);\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */\n  navigation?: NavigationPrimitives;\n\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /**\n   * Strategy for filtering rows. If present, FilterEngine will delegate filter application\n   * to this pluggable strategy.\n   */\n  filter?: FilterStrategy;\n  /**\n   * Hook called before each cell value is read in toJSON and columnOverrides.read.\n   * Fires for both the default innerText extraction and custom read mappers.\n   * Useful for scrolling off-screen columns into view in horizontally virtualized tables.\n   */\n  beforeCellRead?: BeforeCellReadFn;\n  /**\n   * Strategy for detecting loading states. Use this for table-, row-, and header-level readiness.\n   * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.\n   */\n  loading?: LoadingStrategy;\n\n  /**\n   * Resolve the stable data-model index for a row locator.\n   *\n   * Called by `findRow` / `findRows` to convert a DOM row into the index used for\n   * virtual-scroll positioning. Useful for grids where DOM position resets to 0 on\n   * each page while the grid itself maintains a monotone counter (e.g. MUI DataGrid's\n   * `data-rowindex` attribute).\n   *\n   * Return `undefined` to fall back to DOM position.\n   *\n   * @example\n   * // MUI DataGrid: read the global monotone counter from the attribute\n   * resolveRowIndex: async (row) => {\n   *   const v = await row.getAttribute('data-rowindex').catch(() => null);\n   *   return v !== null && !isNaN(Number(v)) ? Number(v) : undefined;\n   * }\n   */\n  resolveRowIndex?: (row: Locator) => Promise<number | undefined>;\n\n  /**\n   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,\n   * Braintrust-style grids where both rows and columns are virtualized simultaneously).\n   *\n   * When present, the cell-reading engine uses these to jump directly to the target\n   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can\n   * knock rows out of the vertical viewport, and vice versa).\n   *\n   * Completely optional and additive \u2014 existing `navigation` primitives remain the fallback.\n   */\n  viewport?: ViewportStrategy;\n}\n\n\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /**\n   * Default concurrency strategy for iteration methods.\n   * Can be overridden by the options passed to forEach, map, or filter.\n   */\n  concurrency?: RowIterationMode;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n\n  /**\n   * Unified interface for reading and writing data to specific columns.\n   * Overrides both default extraction (toJSON) and filling (smartFill) logic.\n   */\n  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;\n}\n\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: string | ((root: Locator) => Locator);\n  rowSelector: string;\n  cellSelector: string | ((row: Locator) => Locator);\n  maxPages: number;\n  autoScroll: boolean;\n  concurrency?: RowIterationMode;\n  debug?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\n\n\n/** Callback context passed to forEach, map, and filter. */\nexport type RowIterationContext<T = any> = {\n  row: SmartRow<T>;\n  /** 0-based iteration counter \u2014 the order this row was visited, not its DOM position or grid identity. @deprecated Use `index` instead. `rowIndex` will be removed in v7.0.0. */\n  rowIndex: number;\n  /** 0-based iteration counter \u2014 the order this row was visited, not its DOM position or grid identity. */\n  index: number;\n  /** 0-based page index \u2014 which page this row was collected from. */\n  pageIndex: number;\n  stop: () => void;\n};\n\n/** Concurrency modes for row iteration. */\nexport type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';\n\n/** Shared options for forEach, map, and filter. */\nexport type RowIterationOptions = {\n  /** Maximum number of pages to iterate. Defaults to config.maxPages. */\n  maxPages?: number;\n  /**\n   * Concurrency strategy for iteration.\n   * - 'parallel': Full parallel execution of both navigation and actions.\n   * - 'synchronized': Parallel navigation (lock-step) with serial actions.\n   * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.\n   * @default 'parallel' (for map), 'sequential' (for forEach/filter)\n   */\n  concurrency?: RowIterationMode;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n  /**\n   * When true, use goNextBulk (if present) to advance pages during iteration.\n   * @default false \u2014 uses goNext for one-page-at-a-time advancement\n   */\n  useBulkPagination?: boolean;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number; pageIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult<T>>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   * @note The sync path cannot compute a real `rowIndex`, so the returned SmartRow's\n   * `rowIndex` is `undefined` (virtual-scroll positioning via `bringIntoView()` is limited).\n   * Use `findRow()` (async) when you need a row with an accurate `rowIndex`.\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow<T>;\n\n  /**\n   * Gets a row by its 0-based position in the currently-rendered DOM (sync, no scroll).\n   * Throws if the table is not initialized.\n   *\n   * For button-paginated tables this is the i-th row on the current page. For virtualized\n   * tables the render window shifts as you scroll, so `getRowByIndex(i)` returns whatever\n   * row currently sits at DOM position `i` \u2014 NOT the logical/absolute row `i` in the dataset\n   * once the list has scrolled. To iterate virtualized rows by logical identity, use `map` /\n   * `findRows` (with a `dedupe` strategy) instead.\n   *\n   * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when\n   * it is used, rather than throwing here.\n   *\n   * @param index 0-based position within the current render window\n   */\n  getRowByIndex: (\n    index: number\n  ) => SmartRow<T>;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow<T>>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match (omit or pass {} for all rows)\n   * @param options - Search options (exact, maxPages). `useBulkPagination` defaults to `false`: pages advance one at a time via `goNext` so no intermediate page is skipped. Set it to `true` to opt into `goNextBulk` (faster, but skips the rows on jumped-over pages).\n   */\n  findRows: (\n    filters?: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number, useBulkPagination?: boolean }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * Counts the number of rows currently on the page.\n   * Does not paginate.\n   */\n  countRows: () => Promise<number>;\n\n  /**\n   * Iterates over rows and extracts the value of a single column.\n   * More efficient than map + toJSON for single-column extraction.\n   * @param columnName - The name of the column to extract\n   * @param options - Iteration options\n   */\n  mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;\n\n  /**\n   * Iterates over rows and extracts the value of a single column as strings.\n   * @param columnName - The name of the column to extract\n   * @param options - Iteration options\n   */\n  getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `concurrency: 'parallel'`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `concurrency: 'sequential'` (or `'synchronized'`\n   * > when navigation must stay lock-step) to avoid overlapping interactions.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 use sequential (or synchronized) concurrency\n   * const assignees = await table.map(async ({ row }) => {\n   *   await row.getCell('Assignee').locator('button').click();\n   *   const name = await page.locator('.popover .name').innerText();\n   *   await page.keyboard.press('Escape');\n   *   return name;\n   * }, { concurrency: 'sequential' });\n   */\n  map<R>(\n    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Shorthand for `map()` + `reset()`. Iterates every row across all pages, applies the\n   * callback (defaults to `row.toJSON()`), then resets the table back to page 1 \u2014 even if\n   * the callback throws.\n   *\n   * @param callback - Optional map function. Defaults to `({ row }) => row.toJSON()`.\n   * @param options - Same options as `map()`.\n   *\n   * @example\n   * // Zero-arg: returns toJSON() for every row\n   * const rows = await table.toArray();\n   *\n   * @example\n   * // Custom callback\n   * const names = await table.toArray(({ row }) => row.getCell('Name').innerText());\n   *\n   * @example\n   * // With options\n   * const rows = await table.toArray(({ row }) => row.toJSON(), { concurrency: 'parallel' });\n   */\n  toArray<R = Record<string, unknown>>(\n    callback?: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.\n   * Rows are returned as-is \u2014 call `bringIntoView()` on each if needed.\n   * Execution is sequential by default.\n   *\n   * @param predicate - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * const active = await table.filter(async ({ row }) =>\n   *   await row.getCell('Status').innerText() === 'Active'\n   * );\n   */\n  filter(\n    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,\n    options?: RowIterationOptions\n  ): Promise<SmartRowArray<T>>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   * Automatically throws an Error containing the prompt.\n   */\n  generateConfig: () => Promise<void>;\n\n  /**\n   * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.\n   */\n  generateConfigPrompt: () => Promise<void>;\n}\n";

package/dist/typeContext.js

@@ -475,7 +475,10 @@ export interface LoadingStrategy {
 
   /**
    * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.
-   * When not set, loading rows are immediately skipped (backward-compatible behavior).
+   * Honored by findRows AND by map/forEach/filter, where the wait runs before the dedupe
+   * strategy so content-based dedupe keys see the row's final loaded state.
+   * When not set (backward-compatible behavior): findRows skips loading rows immediately;
+   * map/forEach/filter process them as-is.
    */
   rowLoadingTimeout?: number;
 
@@ -554,6 +557,25 @@ export interface TableStrategies {
    */
   loading?: LoadingStrategy;
 
+  /**
+   * Resolve the stable data-model index for a row locator.
+   *
+   * Called by \`findRow\` / \`findRows\` to convert a DOM row into the index used for
+   * virtual-scroll positioning. Useful for grids where DOM position resets to 0 on
+   * each page while the grid itself maintains a monotone counter (e.g. MUI DataGrid's
+   * \`data-rowindex\` attribute).
+   *
+   * Return \`undefined\` to fall back to DOM position.
+   *
+   * @example
+   * // MUI DataGrid: read the global monotone counter from the attribute
+   * resolveRowIndex: async (row) => {
+   *   const v = await row.getAttribute('data-rowindex').catch(() => null);
+   *   return v !== null && !isNaN(Number(v)) ? Number(v) : undefined;
+   * }
+   */
+  resolveRowIndex?: (row: Locator) => Promise<number | undefined>;
+
   /**
    * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
    * Braintrust-style grids where both rows and columns are virtualized simultaneously).
@@ -688,8 +710,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   /**
    * Finds a row by filters on the current page only. Returns immediately (sync).
    * Throws error if table is not initialized.
-   * @note The returned SmartRow may have \`rowIndex\` as 0 when the match is not the first row.
-   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).
+   * @note The sync path cannot compute a real \`rowIndex\`, so the returned SmartRow's
+   * \`rowIndex\` is \`undefined\` (virtual-scroll positioning via \`bringIntoView()\` is limited).
+   * Use \`findRow()\` (async) when you need a row with an accurate \`rowIndex\`.
    */
   getRow: (
     filters: Record<string, FilterValue>,
@@ -697,9 +720,19 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   ) => SmartRow<T>;
 
   /**
-   * Gets a row by 0-based index on the current page.
-   * Throws error if table is not initialized.
-   * @param index 0-based row index
+   * Gets a row by its 0-based position in the currently-rendered DOM (sync, no scroll).
+   * Throws if the table is not initialized.
+   *
+   * For button-paginated tables this is the i-th row on the current page. For virtualized
+   * tables the render window shifts as you scroll, so \`getRowByIndex(i)\` returns whatever
+   * row currently sits at DOM position \`i\` — NOT the logical/absolute row \`i\` in the dataset
+   * once the list has scrolled. To iterate virtualized rows by logical identity, use \`map\` /
+   * \`findRows\` (with a \`dedupe\` strategy) instead.
+   *
+   * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when
+   * it is used, rather than throwing here.
+   *
+   * @param index 0-based position within the current render window
    */
   getRowByIndex: (
     index: number
@@ -720,7 +753,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * ASYNC: Searches for all matching rows across pages using pagination.
    * Auto-initializes the table if not already initialized.
    * @param filters - The filter criteria to match (omit or pass {} for all rows)
-   * @param options - Search options including exact match and max pages
+   * @param options - Search options (exact, maxPages). \`useBulkPagination\` defaults to \`false\`: pages advance one at a time via \`goNext\` so no intermediate page is skipped. Set it to \`true\` to opt into \`goNextBulk\` (faster, but skips the rows on jumped-over pages).
    */
   findRows: (
     filters?: Record<string, FilterValue>,

package/dist/types.d.ts

@@ -432,7 +432,10 @@ export interface LoadingStrategy {
     isHeaderLoading?: (context: TableContext) => Promise<boolean>;
     /**
      * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.
-     * When not set, loading rows are immediately skipped (backward-compatible behavior).
+     * Honored by findRows AND by map/forEach/filter, where the wait runs before the dedupe
+     * strategy so content-based dedupe keys see the row's final loaded state.
+     * When not set (backward-compatible behavior): findRows skips loading rows immediately;
+     * map/forEach/filter process them as-is.
      */
     rowLoadingTimeout?: number;
     /**
@@ -500,6 +503,24 @@ export interface TableStrategies {
      * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.
      */
     loading?: LoadingStrategy;
+    /**
+     * Resolve the stable data-model index for a row locator.
+     *
+     * Called by `findRow` / `findRows` to convert a DOM row into the index used for
+     * virtual-scroll positioning. Useful for grids where DOM position resets to 0 on
+     * each page while the grid itself maintains a monotone counter (e.g. MUI DataGrid's
+     * `data-rowindex` attribute).
+     *
+     * Return `undefined` to fall back to DOM position.
+     *
+     * @example
+     * // MUI DataGrid: read the global monotone counter from the attribute
+     * resolveRowIndex: async (row) => {
+     *   const v = await row.getAttribute('data-rowindex').catch(() => null);
+     *   return v !== null && !isNaN(Number(v)) ? Number(v) : undefined;
+     * }
+     */
+    resolveRowIndex?: (row: Locator) => Promise<number | undefined>;
     /**
      * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
      * Braintrust-style grids where both rows and columns are virtualized simultaneously).
@@ -635,16 +656,27 @@ export interface TableResult<T = any> extends AsyncIterable<{
     /**
      * Finds a row by filters on the current page only. Returns immediately (sync).
      * Throws error if table is not initialized.
-     * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.
-     * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).
+     * @note The sync path cannot compute a real `rowIndex`, so the returned SmartRow's
+     * `rowIndex` is `undefined` (virtual-scroll positioning via `bringIntoView()` is limited).
+     * Use `findRow()` (async) when you need a row with an accurate `rowIndex`.
      */
     getRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
     }) => SmartRow<T>;
     /**
-     * Gets a row by 0-based index on the current page.
-     * Throws error if table is not initialized.
-     * @param index 0-based row index
+     * Gets a row by its 0-based position in the currently-rendered DOM (sync, no scroll).
+     * Throws if the table is not initialized.
+     *
+     * For button-paginated tables this is the i-th row on the current page. For virtualized
+     * tables the render window shifts as you scroll, so `getRowByIndex(i)` returns whatever
+     * row currently sits at DOM position `i` — NOT the logical/absolute row `i` in the dataset
+     * once the list has scrolled. To iterate virtualized rows by logical identity, use `map` /
+     * `findRows` (with a `dedupe` strategy) instead.
+     *
+     * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when
+     * it is used, rather than throwing here.
+     *
+     * @param index 0-based position within the current render window
      */
     getRowByIndex: (index: number) => SmartRow<T>;
     /**
@@ -661,7 +693,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * ASYNC: Searches for all matching rows across pages using pagination.
      * Auto-initializes the table if not already initialized.
      * @param filters - The filter criteria to match (omit or pass {} for all rows)
-     * @param options - Search options including exact match and max pages
+     * @param options - Search options (exact, maxPages). `useBulkPagination` defaults to `false`: pages advance one at a time via `goNext` so no intermediate page is skipped. Set it to `true` to opt into `goNextBulk` (faster, but skips the rows on jumped-over pages).
      */
     findRows: (filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;

package/dist/useTable.js

@@ -64,10 +64,15 @@ const useTable = (rootLocator, configOptions = {}) => {
     const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "thead th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text }) => text, autoScroll: true, onReset: async () => { } }, configOptions), { strategies: Object.assign(Object.assign({}, defaultStrategies), configOptions.strategies) });
     // Automatically memoize viewport range oracles so user-provided functions are
     // pure DOM queries with no cache bookkeeping. Invalidated after each scroll call.
+    let _clearViewportCache = null;
     if (config.strategies.viewport && !config.strategies.viewport.disableCache) {
         const vp = config.strategies.viewport;
         let colRangeCache = null;
         let rowRangeCache = null;
+        _clearViewportCache = () => {
+            colRangeCache = null;
+            rowRangeCache = null;
+        };
         config.strategies.viewport = Object.assign(Object.assign({}, vp), { getVisibleColumnRange: vp.getVisibleColumnRange
                 ? async (ctx) => {
                     if (!colRangeCache)
@@ -194,6 +199,10 @@ const useTable = (rootLocator, configOptions = {}) => {
         if (pagesJumped > 0) {
             tableState.currentPageIndex += pagesJumped;
             log(`_advancePage: ${primitive} advanced ${pagesJumped} page(s) — now at page ${tableState.currentPageIndex}`);
+            // Invalidate viewport caches: after a page advance the row set changes and the
+            // column renderer may recalculate (e.g. scrollbar appearance changes available width).
+            if (_clearViewportCache)
+                _clearViewportCache();
             await (0, debugUtils_1.debugDelay)(config, 'pagination');
         }
         else {
@@ -271,6 +280,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             const tracker = new elementTracker_1.ElementTracker('countRows');
             let total = 0;
             let pagesScanned = 1;
+            let paginationError;
             try {
                 while (true) {
                     const newIndices = await tracker.getUnseenIndices(resolve(config.rowSelector, rootLocator));
@@ -283,11 +293,25 @@ const useTable = (rootLocator, configOptions = {}) => {
                     pagesScanned++;
                 }
             }
+            catch (e) {
+                paginationError = e;
+                throw e;
+            }
             finally {
                 await tracker.cleanup(rootLocator.page());
+                // Always restore page 1, even if pagination threw mid-count (#348), so the table
+                // stays usable for callers that catch the error. If reset() itself fails, only let
+                // it surface when pagination succeeded — otherwise preserve the original error.
+                log(`countRows: ${total} total row(s) across ${pagesScanned} page(s) — resetting`);
+                try {
+                    await result.reset();
+                }
+                catch (resetError) {
+                    if (paginationError === undefined)
+                        throw resetError;
+                    (0, debugUtils_1.logDebug)(config, 'error', 'countRows: reset() failed after pagination error', resetError);
+                }
             }
-            log(`countRows: ${total} total row(s) across ${pagesScanned} page(s) — resetting`);
-            await result.reset();
             return total;
         },
         mapColumn: async (columnName, options = {}) => {

package/dist/utils/navigationBarrier.d.ts

@@ -1,23 +1,35 @@
-/**
- * A synchronization barrier that allows multiple parallel row processors
- * to coordinate their navigation actions.
- */
 export declare class NavigationBarrier {
     private total;
     private finishedCount;
     private buckets;
+    private recoveryMutex;
     constructor(total: number);
     /** True when more than one row shares this barrier (scrollToRow would evict peers). */
     isParallel(): boolean;
     /**
      * Synchronize all active rows at a specific column index.
-     * The last row to arrive will trigger the `moveAction`.
+     * The last row to arrive (or the last markFinished call) triggers the `moveAction`.
      */
     sync<T = void>(colIndex: number, moveAction?: () => Promise<T>): Promise<T | void>;
     /**
      * Mark a row as finished (no more cells to process).
-     * This ensures the barrier doesn't wait for rows that have exited the loop.
+     * This ensures the barrier doesn't wait for rows that have exited the loop,
+     * and runs the pending move action so waiting peers are not starved.
      */
     markFinished(): void;
-    private broadcast;
+    /**
+     * Run a recovery action exclusively — serialized so concurrent rows don't race
+     * on scrollTop after a horizontal scroll evicts rows from the vertical viewport.
+     * The fn receives a fresh `targetReached` check; if the previous row's scroll
+     * already brought this row into view, fn can no-op immediately.
+     */
+    runExclusiveRecovery<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Detach the bucket for `colIndex`, run the first available moveAction,
+     * then resolve or reject all captured waiters.
+     *
+     * Detaching before the await prevents a concurrent markFinished() from
+     * broadcasting the same bucket a second time while the action is in-flight.
+     */
+    private triggerBucket;
 }

package/dist/utils/navigationBarrier.js

@@ -1,15 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NavigationBarrier = void 0;
-/**
- * A synchronization barrier that allows multiple parallel row processors
- * to coordinate their navigation actions.
- */
+const mutex_1 = require("./mutex");
 class NavigationBarrier {
     constructor(total) {
         this.finishedCount = 0;
-        // Map of colIndex -> Set of waiting resolvers
         this.buckets = new Map();
+        this.recoveryMutex = null;
         this.total = total;
     }
     /** True when more than one row shares this barrier (scrollToRow would evict peers). */
@@ -18,7 +15,7 @@ class NavigationBarrier {
     }
     /**
      * Synchronize all active rows at a specific column index.
-     * The last row to arrive will trigger the `moveAction`.
+     * The last row to arrive (or the last markFinished call) triggers the `moveAction`.
      */
     async sync(colIndex, moveAction) {
         if (this.total <= 1) {
@@ -26,50 +23,82 @@ class NavigationBarrier {
                 return await moveAction();
             return;
         }
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
             let bucket = this.buckets.get(colIndex);
             if (!bucket) {
                 bucket = new Set();
                 this.buckets.set(colIndex, bucket);
             }
-            bucket.add(resolve);
+            bucket.add({ resolve, reject, moveAction });
             if (bucket.size + this.finishedCount >= this.total) {
-                // Use a self-executing async function to handle the moveAction synchronously in this context
-                (async () => {
-                    let result;
-                    try {
-                        if (moveAction)
-                            result = await moveAction();
-                    }
-                    finally {
-                        this.broadcast(colIndex, result);
-                    }
-                })();
+                this.triggerBucket(colIndex);
             }
         });
     }
     /**
      * Mark a row as finished (no more cells to process).
-     * This ensures the barrier doesn't wait for rows that have exited the loop.
+     * This ensures the barrier doesn't wait for rows that have exited the loop,
+     * and runs the pending move action so waiting peers are not starved.
      */
     markFinished() {
         this.finishedCount++;
-        // Check all buckets - any bucket that was waiting for this row might now be ready
         for (const colIndex of Array.from(this.buckets.keys())) {
             const bucket = this.buckets.get(colIndex);
             if (bucket.size + this.finishedCount >= this.total) {
-                this.broadcast(colIndex);
+                this.triggerBucket(colIndex);
             }
         }
     }
-    broadcast(colIndex, result) {
+    /**
+     * Run a recovery action exclusively — serialized so concurrent rows don't race
+     * on scrollTop after a horizontal scroll evicts rows from the vertical viewport.
+     * The fn receives a fresh `targetReached` check; if the previous row's scroll
+     * already brought this row into view, fn can no-op immediately.
+     */
+    async runExclusiveRecovery(fn) {
+        if (!this.recoveryMutex)
+            this.recoveryMutex = new mutex_1.Mutex();
+        return this.recoveryMutex.run(fn);
+    }
+    /**
+     * Detach the bucket for `colIndex`, run the first available moveAction,
+     * then resolve or reject all captured waiters.
+     *
+     * Detaching before the await prevents a concurrent markFinished() from
+     * broadcasting the same bucket a second time while the action is in-flight.
+     */
+    triggerBucket(colIndex) {
         const bucket = this.buckets.get(colIndex);
-        if (bucket) {
-            for (const resolve of bucket) {
-                resolve(result);
+        if (!bucket)
+            return;
+        const waiters = Array.from(bucket);
+        this.buckets.delete(colIndex);
+        (async () => {
+            var _a;
+            let result;
+            let err;
+            try {
+                // Find the first waiter that supplied a moveAction — the last arrival may be
+                // a no-op (fast-path) row with no action, but an earlier waiter's action must
+                // still run, otherwise the column scroll is silently skipped.
+                const action = (_a = waiters.find(w => w.moveAction)) === null || _a === void 0 ? void 0 : _a.moveAction;
+                if (action)
+                    result = await action();
             }
-            this.buckets.delete(colIndex);
-        }
+            catch (e) {
+                err = e;
+            }
+            finally {
+                if (err !== undefined) {
+                    for (const { reject } of waiters)
+                        reject(err);
+                }
+                else {
+                    for (const { resolve } of waiters)
+                        resolve(result);
+                }
+            }
+        })();
     }
 }
 exports.NavigationBarrier = NavigationBarrier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.17.0",
+  "version": "6.18.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -76,11 +76,21 @@
   },
   "typesVersions": {
     "*": {
-      "types": ["./dist/types.d.ts"],
-      "presets": ["./dist/presets/index.d.ts"],
-      "presets/mui": ["./dist/presets/mui.d.ts"],
-      "presets/rdg": ["./dist/presets/rdg.d.ts"],
-      "presets/glide": ["./dist/presets/glide/index.d.ts"]
+      "types": [
+        "./dist/types.d.ts"
+      ],
+      "presets": [
+        "./dist/presets/index.d.ts"
+      ],
+      "presets/mui": [
+        "./dist/presets/mui.d.ts"
+      ],
+      "presets/rdg": [
+        "./dist/presets/rdg.d.ts"
+      ],
+      "presets/glide": [
+        "./dist/presets/glide/index.d.ts"
+      ]
     }
   },
   "keywords": [