@rickcedwhat/playwright-smart-table 6.20.1-next.b5aa4bd → 6.20.1-next.dbc9618

package/dist/engine/rowFinder.js

@@ -8,6 +8,7 @@ const sentinel_1 = require("../utils/sentinel");
 const navigationBarrier_1 = require("../utils/navigationBarrier");
 const rowResolution_1 = require("./rowResolution");
 const resolveCellLocator_1 = require("../utils/resolveCellLocator");
+const scanPages_1 = require("./scanPages");
 class RowFinder {
     constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow, tableState = { currentPageIndex: 0 }, advancePage = async () => false) {
         this.rootLocator = rootLocator;
@@ -141,39 +142,40 @@ class RowFinder {
         const map = await this.tableMapper.getMap();
         const allRows = [];
         const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
-        let pagesScanned = 1;
+        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 hasPagination = !!this.config.strategies.pagination;
         (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: starting (maxPages=${effectiveMaxPages}, filters=${JSON.stringify(filtersRecord)})`);
         const tracker = new elementTracker_1.ElementTracker('findRows');
         try {
-            await this.waitForTableReady();
             const { domFilters, overrideFilters, syntheticFilters } = this.splitFilters(filtersRecord);
             const hasOverrideFilters = Object.keys(overrideFilters).length > 0;
             const hasSyntheticFilters = Object.keys(syntheticFilters).length > 0;
-            const collectMatches = async () => {
+            const { pagesScanned } = await (0, scanPages_1.scanPages)({
+                advancePage: this.advancePage,
+                getCurrentPageIndex: () => this.tableState.currentPageIndex,
+                config: this.config,
+                waitForReady: () => this.waitForTableReady(),
+            }, async () => {
                 var _a, _b, _c, _d;
                 let rowLocators = this.resolve(this.config.rowSelector, this.rootLocator);
                 if (Object.keys(domFilters).length > 0) {
                     rowLocators = this.filterEngine.applyFilters(rowLocators, domFilters, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page(), this.rootLocator);
                 }
-                // Get only newly seen matched rows
                 const newIndices = await tracker.getUnseenIndices(rowLocators);
                 const currentRows = await rowLocators.all();
                 let added = 0;
-                // One barrier per batch — synchronizes cell navigation across all rows in this page's results
                 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 resolved = await (0, rowResolution_1.resolveLogicalRowIndex)(currentRows[idx], this.config, () => allRows.length);
                     const smartRow = this.makeSmartRow(currentRows[idx], map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
-                    // findRows skips a still-loading row when no timeout is configured (legacy
-                    // behavior) — see resolveRowLoading's `noTimeoutAction: 'skip'`.
                     const loadingOutcome = await (0, rowResolution_1.resolveRowLoading)(smartRow, this.config.strategies.loading, 'skip', (msg) => (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: ${msg}`));
                     if (loadingOutcome !== 'process') {
                         barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
                         if (loadingOutcome === 'throw') {
                             throw new Error(`[SmartTable] Row ${allRows.length} did not finish loading within ${(_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.rowLoadingTimeout}ms`);
                         }
-                        continue; // 'skip'
+                        continue;
                     }
                     if (hasOverrideFilters && !await this.matchesOverrideFilters(currentRows[idx], overrideFilters, map, (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false)) {
                         barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
@@ -187,44 +189,33 @@ class RowFinder {
                     added++;
                 }
                 (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: page ${this.tableState.currentPageIndex} — ${added} new match(es) (total: ${allRows.length})`);
-            };
-            // Scan first page
-            await collectMatches();
-            // Pagination Loop
-            while (pagesScanned < effectiveMaxPages && this.config.strategies.pagination) {
-                // 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) {
-                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: pagination returned false — final scan`);
-                    await collectMatches();
-                    break;
-                }
-                const pagesJumped = this.tableState.currentPageIndex - prevPage;
-                pagesScanned += pagesJumped;
-                (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: advanced ${pagesJumped} page(s), now at page ${this.tableState.currentPageIndex}`);
-                await (0, debugUtils_1.debugDelay)(this.config, 'pagination');
-                await collectMatches();
-            }
+                return 'continue';
+            }, {
+                maxPages: hasPagination ? effectiveMaxPages : 1,
+                useBulk,
+                label: 'findRows',
+                finalScanOnEof: hasPagination,
+            });
+            (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: done — ${allRows.length} row(s) collected across ${pagesScanned} page(s)`);
         }
         finally {
             await tracker.cleanup(this.rootLocator.page());
         }
-        (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: done — ${allRows.length} row(s) collected across ${pagesScanned} page(s)`);
         return (0, smartRowArray_1.createSmartRowArray)(allRows);
     }
     async findRowLocator(filters, options = {}) {
         var _a, _b;
         const map = await this.tableMapper.getMap();
         const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages;
-        let pagesScanned = 1;
+        const useBulk = options.useBulkPagination === true && !!((_b = this.config.strategies.pagination) === null || _b === void 0 ? void 0 : _b.goNextBulk);
+        let found = null;
         (0, debugUtils_1.logDebug)(this.config, 'verbose', `Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
-        while (true) {
-            await this.waitForTableReady();
+        await (0, scanPages_1.scanPages)({
+            advancePage: this.advancePage,
+            getCurrentPageIndex: () => this.tableState.currentPageIndex,
+            config: this.config,
+            waitForReady: () => this.waitForTableReady(),
+        }, async () => {
             const allRows = this.resolve(this.config.rowSelector, this.rootLocator);
             const { domFilters, overrideFilters, syntheticFilters } = this.splitFilters(filters);
             const hasPostFilters = Object.keys(overrideFilters).length > 0 || Object.keys(syntheticFilters).length > 0;
@@ -237,8 +228,10 @@ class RowFinder {
                 (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Found ${count} matches.`);
                 if (count > 1)
                     await this.throwIfAmbiguous(await matchedRows.all(), filters, map);
-                if (count === 1)
-                    return matchedRows.first();
+                if (count === 1) {
+                    found = matchedRows.first();
+                    return 'stop';
+                }
             }
             else {
                 const candidates = await matchedRows.all();
@@ -254,31 +247,19 @@ class RowFinder {
                 (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: ${postFilterMatches.length} match(es) after post-filter`);
                 if (postFilterMatches.length > 1)
                     await this.throwIfAmbiguous(postFilterMatches, filters, map);
-                if (postFilterMatches.length === 1)
-                    return postFilterMatches[0];
-            }
-            if (pagesScanned < effectiveMaxPages) {
-                (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Not found. Attempting pagination...`);
-                // 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 && !!((_b = this.config.strategies.pagination) === null || _b === void 0 ? void 0 : _b.goNextBulk);
-                const prevPage = this.tableState.currentPageIndex;
-                const didLoadMore = await this.advancePage(useBulk);
-                if (didLoadMore) {
-                    const pagesJumped = this.tableState.currentPageIndex - prevPage;
-                    pagesScanned += pagesJumped;
-                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRowLocator: advanced ${pagesJumped} page(s), now at page ${this.tableState.currentPageIndex}`);
-                    await (0, debugUtils_1.debugDelay)(this.config, 'pagination');
-                    continue;
-                }
-                else {
-                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: pagination returned false — final scan`);
-                    pagesScanned = effectiveMaxPages;
-                    continue;
+                if (postFilterMatches.length === 1) {
+                    found = postFilterMatches[0];
+                    return 'stop';
                 }
             }
-            return null;
-        }
+            return 'continue';
+        }, {
+            maxPages: effectiveMaxPages,
+            useBulk,
+            label: 'findRow',
+            finalScanOnEof: true,
+        });
+        return found;
     }
     resolveRowIndex(rowLocator) {
         // Shared resolver: resolveRowIndex strategy first, else the DOM-position fallback.

package/dist/engine/scanPages.d.ts

@@ -0,0 +1,58 @@
+import type { FinalTableConfig } from '../types';
+/**
+ * Page-walk primitive (#427).
+ *
+ * Owns the shared pagination shell used by map/forEach/filter, findRow(s),
+ * countRows, and the public async iterator:
+ * - `maxPages` budget
+ * - `advancePage(useBulk)` with bulk page-jump accounting
+ * - EOF final scan (one more `onPage` after `advancePage` returns false)
+ * - optional `waitForReady` before each page
+ *
+ * Per-page collection (overscan, dedupe, loading, filters) stays in the caller
+ * so find vs map can keep their different row policies.
+ *
+ * ## Feature matrix (public APIs → this shell)
+ *
+ * | API | final-scan | bulk opt-in | waitForReady | overscan/dedupe/loading |
+ * |-----|------------|-------------|--------------|-------------------------|
+ * | map / forEach / filter | yes | options.useBulkPagination | via caller | in runMap |
+ * | findRows | yes | options.useBulkPagination | yes | findRows policy (skip loading) |
+ * | findRow | yes | options.useBulkPagination | yes | DOM/post filters only |
+ * | countRows | yes | no (single-step) | yes | count-only / post filters |
+ * | async iterator | yes | no | via runMap path | same as map |
+ * | findRowByIndex | no* | no | n/a | scroll/search, not a full scan |
+ * | bringIntoView | n/a | path planner | n/a | not a page scan |
+ *
+ * \* findRowByIndex stops when the target index is mounted; it does not collect rows.
+ */
+export type ScanDecision = 'continue' | 'stop';
+export interface ScanPageContext {
+    /** 1-based count of pages visited so far (includes the current page). */
+    pagesScanned: number;
+    /** `tableState.currentPageIndex` at the start of this page callback. */
+    pageIndex: number;
+    /** True when this is the post-EOF extra pass after `advancePage` returned false. */
+    isFinalScan: boolean;
+}
+export interface ScanPagesEnv {
+    advancePage: (useBulk: boolean) => Promise<boolean>;
+    getCurrentPageIndex: () => number;
+    config: FinalTableConfig;
+    /** Optional gate before each page (e.g. `isTableLoading` poll). */
+    waitForReady?: () => Promise<void>;
+}
+export interface ScanPagesOptions {
+    maxPages: number;
+    /** Prefer goNextBulk when the advance helper supports it. @default false */
+    useBulk?: boolean;
+    label?: string;
+    /**
+     * When `advancePage` returns false, invoke `onPage` once more before stopping.
+     * Matches runMap / findRows EOF behavior. @default true
+     */
+    finalScanOnEof?: boolean;
+}
+export declare function scanPages(env: ScanPagesEnv, onPage: (ctx: ScanPageContext) => Promise<ScanDecision>, options: ScanPagesOptions): Promise<{
+    pagesScanned: number;
+}>;

package/dist/engine/scanPages.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanPages = scanPages;
+const debugUtils_1 = require("../utils/debugUtils");
+async function scanPages(env, onPage, options) {
+    var _a, _b;
+    const maxPages = options.maxPages;
+    const useBulk = (_a = options.useBulk) !== null && _a !== void 0 ? _a : false;
+    const finalScanOnEof = options.finalScanOnEof !== false;
+    const label = (_b = options.label) !== null && _b !== void 0 ? _b : 'scanPages';
+    let pagesScanned = 1;
+    let reachedEnd = false;
+    (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: starting (maxPages=${maxPages}, useBulk=${useBulk}, finalScanOnEof=${finalScanOnEof})`);
+    while (true) {
+        if (env.waitForReady) {
+            await env.waitForReady();
+        }
+        const decision = await onPage({
+            pagesScanned,
+            pageIndex: env.getCurrentPageIndex(),
+            isFinalScan: reachedEnd,
+        });
+        if (decision === 'stop') {
+            (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: onPage returned stop at page ${env.getCurrentPageIndex()}`);
+            break;
+        }
+        if (pagesScanned >= maxPages || reachedEnd) {
+            break;
+        }
+        const prevPage = env.getCurrentPageIndex();
+        const didAdvance = await env.advancePage(useBulk);
+        if (!didAdvance) {
+            if (finalScanOnEof) {
+                (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: pagination returned false — final scan`);
+                reachedEnd = true;
+                continue;
+            }
+            break;
+        }
+        const pagesJumped = env.getCurrentPageIndex() - prevPage;
+        pagesScanned += pagesJumped > 0 ? pagesJumped : 1;
+        (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: advanced ${pagesJumped > 0 ? pagesJumped : 1} page(s), now at page ${env.getCurrentPageIndex()} (scanned=${pagesScanned})`);
+    }
+    (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: done — ${pagesScanned} page(s) scanned`);
+    return { pagesScanned };
+}

package/dist/engine/tableIteration.d.ts

@@ -20,6 +20,7 @@ export declare function runForEach<T>(env: TableIterationEnv<T>, callback: (ctx:
 /**
  * Row iteration for map (and forEach/filter via label).
  * Concurrency: `parallel` | `synchronized` | `sequential` (see RowIterationOptions).
+ * Page walking is owned by {@link scanPages} (#427).
  */
 export declare function runMap<T, R>(env: TableIterationEnv<T>, callback: (ctx: RowIterationContext<T>) => R | Promise<R>, options?: RowIterationOptions, label?: string): Promise<R[]>;
 /** Filter via map; returns matched rows as {@link SmartRowArray}. */

package/dist/engine/tableIteration.js

@@ -8,6 +8,7 @@ const debugUtils_1 = require("../utils/debugUtils");
 const navigationBarrier_1 = require("../utils/navigationBarrier");
 const mutex_1 = require("../utils/mutex");
 const rowResolution_1 = require("./rowResolution");
+const scanPages_1 = require("./scanPages");
 function log(config, msg) {
     (0, debugUtils_1.logDebug)(config, 'verbose', msg);
 }
@@ -19,9 +20,10 @@ async function runForEach(env, callback, options = {}) {
 /**
  * Row iteration for map (and forEach/filter via label).
  * Concurrency: `parallel` | `synchronized` | `sequential` (see RowIterationOptions).
+ * Page walking is owned by {@link scanPages} (#427).
  */
 async function runMap(env, callback, options = {}, label = 'map') {
-    var _a, _b, _c, _d, _e, _f;
+    var _a, _b, _c, _d, _e;
     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;
@@ -42,8 +44,6 @@ async function runMap(env, callback, options = {}, label = 'map') {
         let rowIndex = 0;
         let stopped = false;
         let stoppedIndex = Infinity;
-        let pagesScanned = 1;
-        let reachedEnd = false;
         const stop = (idx) => {
             if (!stopped) {
                 log(env.config, `${label}: stop() called at row ${idx} — halting`);
@@ -51,7 +51,14 @@ async function runMap(env, callback, options = {}, label = 'map') {
                 stoppedIndex = idx;
             }
         };
-        while (!stopped) {
+        const { pagesScanned } = await (0, scanPages_1.scanPages)({
+            advancePage: env.advancePage,
+            getCurrentPageIndex: env.getCurrentPageIndex,
+            config: env.config,
+        }, async ({ pagesScanned: pageNum, isFinalScan }) => {
+            var _a;
+            if (stopped)
+                return 'stop';
             const rowLocators = env.getRowLocators();
             const allIndices = await tracker.peekUnseenIndices(rowLocators);
             const pageRows = await rowLocators.all();
@@ -68,8 +75,8 @@ async function runMap(env, callback, options = {}, label = 'map') {
             // #417 follow-up: skip viewport filtering on the final scan — there are no more pages
             // to defer to, so collect all remaining unseen rows regardless of visibility.
             let candidateIndices = allIndices;
-            const getVisibleRowIndices = (_f = env.config.strategies.viewport) === null || _f === void 0 ? void 0 : _f.getVisibleRowIndices;
-            if (getVisibleRowIndices && !reachedEnd) {
+            const getVisibleRowIndices = (_a = env.config.strategies.viewport) === null || _a === void 0 ? void 0 : _a.getVisibleRowIndices;
+            if (getVisibleRowIndices && !isFinalScan) {
                 const visible = new Set(await getVisibleRowIndices(env.getContext()));
                 const minVisible = visible.size > 0 ? Math.min(...visible) : Infinity;
                 candidateIndices = allIndices.filter(idx => visible.has(idx) || idx < minVisible);
@@ -86,10 +93,10 @@ async function runMap(env, callback, options = {}, label = 'map') {
             await tracker.commitIndices(rowLocators, newIndices);
             const batchSize = newIndices.length;
             if (batchSize === 0) {
-                log(env.config, `${label}: page ${pagesScanned} — no new row(s) found`);
+                log(env.config, `${label}: page ${pageNum} — no new row(s) found`);
             }
             else {
-                log(env.config, `${label}: scanning page ${pagesScanned} — ${batchSize} new row(s)`);
+                log(env.config, `${label}: scanning page ${pageNum} — ${batchSize} new row(s)`);
                 const barrier = useBarrier ? new navigationBarrier_1.NavigationBarrier(batchSize) : undefined;
                 const actionMutex = useMutex ? new mutex_1.Mutex() : null;
                 // `index` (ctx.index) is the enumeration counter — the order rows are visited,
@@ -169,8 +176,8 @@ async function runMap(env, callback, options = {}, label = 'map') {
                     }
                 }
                 else {
-                    const results = await Promise.all(smartRows.map((row, i) => processRow(row, positionBase + i)));
-                    pageResults.push(...results);
+                    const batchResults = await Promise.all(smartRows.map((row, i) => processRow(row, positionBase + i)));
+                    pageResults.push(...batchResults);
                 }
                 for (let i = 0; i < pageResults.length; i++) {
                     if (positionBase + i > stoppedIndex)
@@ -181,16 +188,13 @@ async function runMap(env, callback, options = {}, label = 'map') {
                 }
                 rowIndex += batchSize;
             }
-            if (stopped || pagesScanned >= effectiveMaxPages || reachedEnd)
-                break;
-            log(env.config, `${label}: advancing to next page (${pagesScanned} → ${pagesScanned + 1})`);
-            if (!await env.advancePage(useBulk)) {
-                log(env.config, `${label}: pagination returned false — final scan`);
-                reachedEnd = true;
-                continue;
-            }
-            pagesScanned++;
-        }
+            return stopped ? 'stop' : 'continue';
+        }, {
+            maxPages: effectiveMaxPages,
+            useBulk,
+            label,
+            finalScanOnEof: true,
+        });
         log(env.config, `${label}: complete — ${results.length} result(s) across ${pagesScanned} page(s)`);
     }
     finally {

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.20.1-next.b5aa4bd";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.20.1-next.dbc9618";

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.20.1-next.b5aa4bd";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.20.1-next.dbc9618";

package/dist/smartRow.d.ts

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

package/dist/smartRow.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("@playwright/test");
 const rowResolution_1 = require("./engine/rowResolution");
 const fill_1 = require("./strategies/fill");
 const stringUtils_1 = require("./utils/stringUtils");
@@ -12,7 +13,7 @@ const sentinel_1 = require("./utils/sentinel");
  * Returns the target cell locator after navigation.
  */
 const _navigateToCell = async (params) => {
-    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier } = params;
+    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier, allowMissingCell } = params;
     const rowLabel = typeof rowIndex === 'number' ? `row ${rowIndex}` : 'row ?';
     (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: resolving column "${column}" (colIndex ${index}), ${rowLabel}`);
     // Get active cell if strategy is available
@@ -65,7 +66,18 @@ const _navigateToCell = async (params) => {
                     ? await viewport.getVisibleRowRange(context)
                     : null;
                 const rowVisible = !rowRange || (rowIndex >= rowRange.first && rowIndex <= rowRange.last);
-                if (rowVisible && await targetReached()) {
+                let cellAttached = rowVisible && await targetReached();
+                if (rowVisible && !cellAttached) {
+                    try {
+                        await getCellLocator().waitFor({ state: 'attached', timeout: 500 });
+                        cellAttached = true;
+                    }
+                    catch (error) {
+                        if (!(error instanceof test_1.errors.TimeoutError))
+                            throw error;
+                    }
+                }
+                if (cellAttached) {
                     (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} in visible range [${knownColRange.first}-${knownColRange.last}], reading directly`);
                     // Check in to the barrier without a moveAction — peers that need the scroll
                     // still supply their own action and will trigger it when all rows arrive.
@@ -124,6 +136,8 @@ const _navigateToCell = async (params) => {
         }
         // Cell still not accessible — fall through to navigation primitives if configured.
         if (!config.strategies.navigation) {
+            if (allowMissingCell)
+                return getCellLocator();
             const colRange = viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
             const rowRange = viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
             let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex}.\n`;
@@ -144,15 +158,17 @@ const _navigateToCell = async (params) => {
     // Use navigation primitives if available
     if (config.strategies.navigation) {
         const nav = config.strategies.navigation;
-        if (typeof rowIndex !== 'number') {
-            throw new Error('Row index is required for navigation');
-        }
         if (await targetReached()) {
             // Already there. If we have a barrier, check-in to stay in lock-step.
             if (barrier)
                 await barrier.sync(index);
             return getCellLocator();
         }
+        if (typeof rowIndex !== 'number') {
+            if (allowMissingCell)
+                return getCellLocator();
+            throw new Error('Row index is required for navigation');
+        }
         // If getActiveCell is present but returns null (no focus), and cell is in DOM,
         // try to focus it once before entering navigation loop.
         if (config.strategies.getActiveCell) {
@@ -271,6 +287,8 @@ const _navigateToCell = async (params) => {
         const finalCell = getCellLocator();
         if (await finalCell.count() > 0)
             return finalCell;
+        if (allowMissingCell)
+            return finalCell;
         const colRange = viewport && viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
         const rowRange = viewport && viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
         let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex} after exhausting navigation strategies. Ensure navigation primitives are correctly implemented.\n`;
@@ -294,7 +312,7 @@ const _navigateToCell = async (params) => {
  * @internal Internal factory for creating SmartRow objects.
  * Not part of the public package surface; tests and consumers should use public APIs.
  */
-const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex, barrier) => {
+const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex, barrier, renderWindowPosition = false) => {
     const smart = rowLocator;
     // Attach State
     smart.rowIndex = rowIndex;
@@ -387,12 +405,22 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, [...map.keys(), ...Object.keys((_b = config.syntheticColumns) !== null && _b !== void 0 ? _b : {})]));
         }
         const columnOverride = (_c = config.columnOverrides) === null || _c === void 0 ? void 0 : _c[colName];
-        const cell = config.strategies.getCellLocator
-            ? config.strategies.getCellLocator({
-                row: rowLocator, root: rootLocator, columnName: colName,
-                columnIndex: idx, rowIndex, page: rootLocator.page(), config,
-            })
-            : resolve(config.cellSelector, rowLocator).nth(idx);
+        const page = rootLocator.page();
+        // Same nav pipeline as toJSON / getCell().bringIntoView() (#430) so virtualized
+        // off-screen columns don't return empty/stale text.
+        const cell = await _navigateToCell({
+            config,
+            rootLocator,
+            page,
+            resolve,
+            getHeaders: table === null || table === void 0 ? void 0 : table.getHeaders,
+            column: colName,
+            index: idx,
+            rowLocator,
+            rowIndex,
+            barrier: smart._barrier,
+            allowMissingCell: !!(columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read),
+        });
         if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) {
             const getCell = (name) => {
                 const ci = map.get(name);
@@ -689,7 +717,8 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 index: idx,
                 rowLocator: stableRow,
                 rowIndex,
-                barrier: smart._barrier
+                barrier: smart._barrier,
+                allowMissingCell: !!mapper,
             });
             if (navigatedCell) {
                 targetCell = navigatedCell;
@@ -716,8 +745,22 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 ? rawCellTimeout
                 : undefined;
             const onCellLoadingTimeout = (_h = (_g = config.strategies.loading) === null || _g === void 0 ? void 0 : _g.onCellLoadingTimeout) !== null && _h !== void 0 ? _h : 'read-as-is';
-            if (isCellLoading && await isCellLoading(targetCell, col, smart)) {
-                if (cellLoadingTimeout !== undefined) {
+            if (isCellLoading) {
+                let loading = await isCellLoading(targetCell, col, smart);
+                // First-paint race: the cell node can attach a tick before the loading
+                // indicator mounts. A single false-negative then reads "" and skips
+                // onCellLoadingTimeout. Only grace when the cell still looks empty.
+                if (!loading && cellLoadingTimeout !== undefined && cellLoadingTimeout > 0) {
+                    const peek = await targetCell.evaluate((el) => (el.textContent || '').trim()).catch(() => '');
+                    if (peek === '') {
+                        const graceDeadline = Date.now() + Math.min(250, cellLoadingTimeout);
+                        while (!loading && Date.now() < graceDeadline) {
+                            await page.waitForTimeout(25);
+                            loading = await isCellLoading(targetCell, col, smart);
+                        }
+                    }
+                }
+                if (loading && cellLoadingTimeout !== undefined) {
                     (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — waiting up to ${cellLoadingTimeout}ms`);
                     const deadline = Date.now() + cellLoadingTimeout;
                     let cellResolved = !(await isCellLoading(targetCell, col, smart)); // immediate check (handles timeout=0)
@@ -830,6 +873,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         (0, debugUtils_1.logDebug)(config, 'info', 'Row fill complete');
     };
     smart.bringIntoView = async () => {
+        var _a;
         if (rowIndex === undefined) {
             (0, debugUtils_1.logDebug)(config, 'info', 'bringIntoView called on a row with unknown rowIndex (e.g. from getRow()). ' +
                 'Page navigation and scrolling will proceed, but virtual-scroll keyboard navigation will be skipped. ' +
@@ -876,8 +920,20 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         }
         // Delay after pagination/finding before scrolling
         await (0, debugUtils_1.debugDelay)(config, 'findRow');
-        // Scroll row into view using Playwright's built-in method
-        await rowLocator.scrollIntoViewIfNeeded();
+        // Prefer viewport.scrollToRow when configured (#430). scrollIntoViewIfNeeded adjusts
+        // both axes and can evict sibling rows on recycling virtualizers.
+        const viewport = config.strategies.viewport;
+        const logicalRowIndex = (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow) && renderWindowPosition
+            ? (_a = (await (0, rowResolution_1.resolveLogicalRowIndex)(rowLocator, config, () => undefined))) === null || _a === void 0 ? void 0 : _a.index
+            : rowIndex;
+        if ((viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow) && typeof logicalRowIndex === 'number') {
+            const page = rootLocator.page();
+            (0, debugUtils_1.logDebug)(config, 'verbose', `bringIntoView: viewport.scrollToRow(${logicalRowIndex})`);
+            await viewport.scrollToRow({ root: rootLocator, config, page, resolve, getHeaders: parentTable === null || parentTable === void 0 ? void 0 : parentTable.getHeaders }, logicalRowIndex);
+        }
+        else {
+            await rowLocator.scrollIntoViewIfNeeded();
+        }
     };
     return smart;
 };

package/dist/strategies/headers.d.ts

@@ -13,6 +13,11 @@ export declare const HeaderStrategies: {
     /**
      * Physically scrolls the table horizontally to force virtualized columns to mount,
      * collecting their names along the way.
+     *
+     * **Requires `selector`** — the CSS selector for the horizontal scroll container
+     * (e.g. `.dvn-scroller` for Glide, `.rdg-viewport` for RDG). Framework class names
+     * belong in presets / your config, not in this generic factory. Without `selector`,
+     * only currently visible headers are returned (no scrolling).
      */
     horizontalScroll: (options?: {
         limit?: number;