@rickcedwhat/playwright-smart-table 6.18.0 → 6.19.0

package/dist/typeContext.js

@@ -167,6 +167,16 @@ export interface ViewportStrategy {
    */
   getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;
 
+  /**
+   * Returns the DOM positions (0-based, document order — indices into the resolved
+   * \`rowSelector\` set) of rows currently within the scroll container's visible bounds.
+   * Unlike \`getVisibleRowRange\` (a logical min/max), this identifies the exact rows, so
+   * \`map\`/\`forEach\`/\`filter\` can skip overscan rows during collection (see #353 / #357).
+   * Geometry-based and inclusive (any overlap counts as visible). When the container can't
+   * be measured, return all positions so no rows are filtered.
+   */
+  getVisibleRowIndices?: (context: TableContext) => Promise<number[]>;
+
   /**
    * Returns the 0-based index range of columns currently rendered in the DOM.
    * Used to detect when a target column is not yet mounted before reading.
@@ -254,8 +264,14 @@ export type SmartRow<T = any> = Locator & {
    * 
    * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
    * // { Name: 'John', Email: 'john@example.com' }
+   *
+   * // Atomic: snapshot all cell values in a single evaluate — zero inter-column stagger.
+   * // Requires cellSelector to be a CSS string (not a function).
+   * // Column overrides ARE supported (run against a frozen off-screen reconstruction).
+   * // Uses textContent (not layout-dependent innerText) for non-override columns.
+   * const coherent = await row.toJSON({ atomic: true });
    */
-  toJSON(options?: { columns?: string[] }): Promise<T>;
+  toJSON(options?: { columns?: string[]; atomic?: boolean }): Promise<T>;
 
   /**
    * Scrolls/paginates to bring this row into view.
@@ -424,12 +440,43 @@ export type FillStrategy = (options: {
   fillOptions?: FillOptions;
 }) => Promise<void>;
 
+/** Context passed as the second argument to {@link ColumnOverride.read}. */
+export interface ColumnOverrideReadContext {
+  /**
+   * The parent row. Use for multi-cell or row-derived values — e.g. a synthetic column
+   * that reads an \`a[href]\` or a \`data-*\` attribute from the row rather than a cell:
+   * \`read: (_cell, { row }) => row.evaluate(el => el.querySelector('a')?.href)\`.
+   */
+  row: SmartRow;
+  /** The column being read. */
+  columnName: string;
+  /** The column's 0-based index in the resolved header map. */
+  columnIndex: number;
+  /**
+   * Get a Locator for another cell in the same row by column name.
+   * Returns raw cell Locators, not override-processed values.
+   *
+   * In atomic mode, the Locator points at the frozen reconstructed cell — coherent with
+   * every other cell from the same snapshot. In non-atomic mode, it points at the live cell.
+   *
+   * @example
+   * read: async (_cell, { getCell }) => {
+   *   const name = (await getCell('Name').innerText()).trim();
+   *   const href = await getCell('Name').locator('a').getAttribute('href') || '';
+   *   return \`\${name} | \${href}\`;
+   * }
+   */
+  getCell: (columnName: string) => Locator;
+}
+
 export interface ColumnOverride<TValue = any> {
-  /** 
+  /**
    * How to extract the value from the cell.
-   * \`context\` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.
+   * The second \`context\` argument provides the parent \`row\` (for multi-cell or row-derived
+   * values), plus \`columnName\` and \`columnIndex\`. Backwards-compatible: existing
+   * single-argument \`read(cell)\` implementations keep working.
    */
-  read?: (cell: Locator) => Promise<TValue> | TValue;
+  read?: (cell: Locator, context: ColumnOverrideReadContext) => Promise<TValue> | TValue;
 
   /** 
    * How to fill the cell with a new value. (Replaces smartFill default logic)
@@ -620,6 +667,13 @@ export interface TableConfig<T = any> {
    * Overrides both default extraction (toJSON) and filling (smartFill) logic.
    */
   columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
+
+  /**
+   * Locator for an empty-state element that replaces the table when there are no results.
+   * If header resolution fails during init() and this locator is visible, init() succeeds
+   * and isEmpty() returns true. All row operations still throw normally.
+   */
+  emptyState?: Locator;
 }
 
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
@@ -649,9 +703,17 @@ export interface FillOptions {
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
   row: SmartRow<T>;
-  /** 0-based iteration counter — 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. */
+  /**
+   * The row's logical/data-model index. When a \`resolveRowIndex\` strategy is configured
+   * (e.g. MUI DataGrid's \`data-rowindex\`) this is the grid's true row index; otherwise it
+   * equals \`index\`. Use this for \`row.bringIntoView()\` and position math on virtualized
+   * tables — it is stable across scrolling/dedupe, unlike the visit-order \`index\`.
+   */
   rowIndex: number;
-  /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
+  /**
+   * 0-based enumeration counter — the order this row was visited (contiguous within the run).
+   * Not a DOM position or grid identity. Use \`rowIndex\` for the row's data-model index.
+   */
   index: number;
   /** 0-based page index — which page this row was collected from. */
   pageIndex: number;
@@ -704,6 +766,13 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    */
   isInitialized(): boolean;
 
+  /**
+   * SYNC: Returns true if init() resolved via the emptyState path — the table's
+   * empty-state locator was visible when header resolution failed.
+   * Row operations still throw normally; use this to branch before calling them.
+   */
+  isEmpty(): boolean;
+
   getHeaders: () => Promise<string[]>;
   getHeaderCell: (columnName: string) => Promise<Locator>;
 
@@ -726,8 +795,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * 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.
+   * once the list has scrolled. For the row with a specific logical/data-model index on a
+   * virtualized table, use the async \`findRowByIndex(i)\` instead (it scrolls to the row);
+   * to iterate by logical identity, use \`map\` / \`findRows\` (with a \`dedupe\` strategy).
    *
    * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when
    * it is used, rather than throwing here.
@@ -738,6 +808,26 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
     index: number
   ) => SmartRow<T>;
 
+  /**
+   * ASYNC: Returns the row with a specific logical/data-model index, scrolling/paginating to
+   * reach it. Unlike the sync \`getRowByIndex\` (render-window position), this resolves the true
+   * data-model row \`index\` on virtualized tables.
+   *
+   * Reaches the row via, in order: a currently-mounted match, the viewport's random-access
+   * \`scrollToRow\` fast path, then advancing pages (on infinite-scroll tables a "page" is a
+   * scroll step) up to \`maxPages\`.
+   *
+   * Requires a \`strategies.resolveRowIndex\` to identify rows by logical index — throws if one
+   * is not configured. Also throws if the row cannot be reached (no silent wrong-row fallback).
+   *
+   * @param index 0-based logical/data-model row index
+   * @param options - \`maxPages\` bounds how far to scroll/paginate (defaults to config.maxPages)
+   */
+  findRowByIndex: (
+    index: number,
+    options?: { maxPages?: number }
+  ) => Promise<SmartRow<T>>;
+
   /**
    * ASYNC: Searches for a single row across pages using pagination.
    * Auto-initializes the table if not already initialized.

package/dist/types.d.ts

@@ -157,6 +157,15 @@ export interface ViewportStrategy {
         first: number;
         last: number;
     }>;
+    /**
+     * Returns the DOM positions (0-based, document order — indices into the resolved
+     * `rowSelector` set) of rows currently within the scroll container's visible bounds.
+     * Unlike `getVisibleRowRange` (a logical min/max), this identifies the exact rows, so
+     * `map`/`forEach`/`filter` can skip overscan rows during collection (see #353 / #357).
+     * Geometry-based and inclusive (any overlap counts as visible). When the container can't
+     * be measured, return all positions so no rows are filtered.
+     */
+    getVisibleRowIndices?: (context: TableContext) => Promise<number[]>;
     /**
      * Returns the 0-based index range of columns currently rendered in the DOM.
      * Used to detect when a target column is not yet mounted before reading.
@@ -236,9 +245,16 @@ export type SmartRow<T = any> = Locator & {
      *
      * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
      * // { Name: 'John', Email: 'john@example.com' }
+     *
+     * // Atomic: snapshot all cell values in a single evaluate — zero inter-column stagger.
+     * // Requires cellSelector to be a CSS string (not a function).
+     * // Column overrides ARE supported (run against a frozen off-screen reconstruction).
+     * // Uses textContent (not layout-dependent innerText) for non-override columns.
+     * const coherent = await row.toJSON({ atomic: true });
      */
     toJSON(options?: {
         columns?: string[];
+        atomic?: boolean;
     }): Promise<T>;
     /**
      * Scrolls/paginates to bring this row into view.
@@ -383,12 +399,42 @@ export type FillStrategy = (options: {
     table: TableResult;
     fillOptions?: FillOptions;
 }) => Promise<void>;
+/** Context passed as the second argument to {@link ColumnOverride.read}. */
+export interface ColumnOverrideReadContext {
+    /**
+     * The parent row. Use for multi-cell or row-derived values — e.g. a synthetic column
+     * that reads an `a[href]` or a `data-*` attribute from the row rather than a cell:
+     * `read: (_cell, { row }) => row.evaluate(el => el.querySelector('a')?.href)`.
+     */
+    row: SmartRow;
+    /** The column being read. */
+    columnName: string;
+    /** The column's 0-based index in the resolved header map. */
+    columnIndex: number;
+    /**
+     * Get a Locator for another cell in the same row by column name.
+     * Returns raw cell Locators, not override-processed values.
+     *
+     * In atomic mode, the Locator points at the frozen reconstructed cell — coherent with
+     * every other cell from the same snapshot. In non-atomic mode, it points at the live cell.
+     *
+     * @example
+     * read: async (_cell, { getCell }) => {
+     *   const name = (await getCell('Name').innerText()).trim();
+     *   const href = await getCell('Name').locator('a').getAttribute('href') || '';
+     *   return `${name} | ${href}`;
+     * }
+     */
+    getCell: (columnName: string) => Locator;
+}
 export interface ColumnOverride<TValue = any> {
     /**
      * How to extract the value from the cell.
-     * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.
+     * The second `context` argument provides the parent `row` (for multi-cell or row-derived
+     * values), plus `columnName` and `columnIndex`. Backwards-compatible: existing
+     * single-argument `read(cell)` implementations keep working.
      */
-    read?: (cell: Locator) => Promise<TValue> | TValue;
+    read?: (cell: Locator, context: ColumnOverrideReadContext) => Promise<TValue> | TValue;
     /**
      * How to fill the cell with a new value. (Replaces smartFill default logic)
      * Provides the current value (via `read`) if a `write` wants to check state first.
@@ -567,6 +613,12 @@ export interface TableConfig<T = any> {
      * Overrides both default extraction (toJSON) and filling (smartFill) logic.
      */
     columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
+    /**
+     * Locator for an empty-state element that replaces the table when there are no results.
+     * If header resolution fails during init() and this locator is visible, init() succeeds
+     * and isEmpty() returns true. All row operations still throw normally.
+     */
+    emptyState?: Locator;
 }
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
     headerSelector: string | ((root: Locator) => Locator);
@@ -595,9 +647,17 @@ export interface FillOptions {
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
     row: SmartRow<T>;
-    /** 0-based iteration counter — 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. */
+    /**
+     * The row's logical/data-model index. When a `resolveRowIndex` strategy is configured
+     * (e.g. MUI DataGrid's `data-rowindex`) this is the grid's true row index; otherwise it
+     * equals `index`. Use this for `row.bringIntoView()` and position math on virtualized
+     * tables — it is stable across scrolling/dedupe, unlike the visit-order `index`.
+     */
     rowIndex: number;
-    /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
+    /**
+     * 0-based enumeration counter — the order this row was visited (contiguous within the run).
+     * Not a DOM position or grid identity. Use `rowIndex` for the row's data-model index.
+     */
     index: number;
     /** 0-based page index — which page this row was collected from. */
     pageIndex: number;
@@ -651,6 +711,12 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * @returns true if init() has been called and completed, false otherwise
      */
     isInitialized(): boolean;
+    /**
+     * SYNC: Returns true if init() resolved via the emptyState path — the table's
+     * empty-state locator was visible when header resolution failed.
+     * Row operations still throw normally; use this to branch before calling them.
+     */
+    isEmpty(): boolean;
     getHeaders: () => Promise<string[]>;
     getHeaderCell: (columnName: string) => Promise<Locator>;
     /**
@@ -670,8 +736,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * 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.
+     * once the list has scrolled. For the row with a specific logical/data-model index on a
+     * virtualized table, use the async `findRowByIndex(i)` instead (it scrolls to the row);
+     * to iterate by logical identity, use `map` / `findRows` (with a `dedupe` strategy).
      *
      * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when
      * it is used, rather than throwing here.
@@ -679,6 +746,24 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * @param index 0-based position within the current render window
      */
     getRowByIndex: (index: number) => SmartRow<T>;
+    /**
+     * ASYNC: Returns the row with a specific logical/data-model index, scrolling/paginating to
+     * reach it. Unlike the sync `getRowByIndex` (render-window position), this resolves the true
+     * data-model row `index` on virtualized tables.
+     *
+     * Reaches the row via, in order: a currently-mounted match, the viewport's random-access
+     * `scrollToRow` fast path, then advancing pages (on infinite-scroll tables a "page" is a
+     * scroll step) up to `maxPages`.
+     *
+     * Requires a `strategies.resolveRowIndex` to identify rows by logical index — throws if one
+     * is not configured. Also throws if the row cannot be reached (no silent wrong-row fallback).
+     *
+     * @param index 0-based logical/data-model row index
+     * @param options - `maxPages` bounds how far to scroll/paginate (defaults to config.maxPages)
+     */
+    findRowByIndex: (index: number, options?: {
+        maxPages?: number;
+    }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for a single row across pages using pagination.
      * Auto-initializes the table if not already initialized.

package/dist/useTable.js

@@ -27,6 +27,7 @@ const filterEngine_1 = require("./filterEngine");
 const tableMapper_1 = require("./engine/tableMapper");
 const rowFinder_1 = require("./engine/rowFinder");
 const tableIteration_1 = require("./engine/tableIteration");
+const rowResolution_1 = require("./engine/rowResolution");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
 const elementTracker_1 = require("./utils/elementTracker");
@@ -69,9 +70,11 @@ const useTable = (rootLocator, configOptions = {}) => {
         const vp = config.strategies.viewport;
         let colRangeCache = null;
         let rowRangeCache = null;
+        let rowIndicesCache = null;
         _clearViewportCache = () => {
             colRangeCache = null;
             rowRangeCache = null;
+            rowIndicesCache = null;
         };
         config.strategies.viewport = Object.assign(Object.assign({}, vp), { getVisibleColumnRange: vp.getVisibleColumnRange
                 ? async (ctx) => {
@@ -85,15 +88,23 @@ const useTable = (rootLocator, configOptions = {}) => {
                         rowRangeCache = await vp.getVisibleRowRange(ctx);
                     return rowRangeCache;
                 }
+                : undefined, getVisibleRowIndices: vp.getVisibleRowIndices
+                ? async (ctx) => {
+                    if (!rowIndicesCache)
+                        rowIndicesCache = await vp.getVisibleRowIndices(ctx);
+                    return rowIndicesCache;
+                }
                 : undefined, scrollToColumn: vp.scrollToColumn
                 ? async (ctx, colIndex) => {
                     colRangeCache = null;
                     rowRangeCache = null;
+                    rowIndicesCache = null;
                     await vp.scrollToColumn(ctx, colIndex);
                 }
                 : undefined, scrollToRow: vp.scrollToRow
                 ? async (ctx, rowIndex) => {
                     rowRangeCache = null;
+                    rowIndicesCache = null;
                     await vp.scrollToRow(ctx, rowIndex);
                 }
                 : undefined });
@@ -137,7 +148,7 @@ const useTable = (rootLocator, configOptions = {}) => {
     const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier) => {
         return (0, smartRow_1.default)(rowLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier);
     };
-    const tableState = { currentPageIndex: 0 };
+    const tableState = { currentPageIndex: 0, empty: false };
     const rowFinder = new rowFinder_1.RowFinder(rootLocator, config, resolve, filterEngine, tableMapper, _makeSmart, tableState, (useBulk) => _advancePage(useBulk));
     /** Builds a full TableContext/StrategyContext with getHeaderCell, getHeaders, scrollToColumn. Set after result is created. */
     let createStrategyContext = () => ({ root: rootLocator, config, page: rootLocator.page(), resolve });
@@ -215,7 +226,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         set currentPageIndex(v) { tableState.currentPageIndex = v; },
         init: async (options) => {
             var _a;
-            if (tableMapper.isInitialized())
+            if (tableMapper.isInitialized() || tableState.empty)
                 return result;
             if (config.strategies.sorting)
                 (0, validation_1.validateSortingStrategy)(config.strategies.sorting);
@@ -223,7 +234,21 @@ const useTable = (rootLocator, configOptions = {}) => {
                 (0, validation_1.validateFillStrategy)(config.strategies.fill);
             (0, debugUtils_1.warnIfDebugInCI)(config);
             (0, debugUtils_1.logDebug)(config, 'info', 'Initializing table');
-            const map = await tableMapper.getMap(options === null || options === void 0 ? void 0 : options.timeout);
+            let map;
+            try {
+                map = await tableMapper.getMap(options === null || options === void 0 ? void 0 : options.timeout);
+            }
+            catch (headerError) {
+                if (config.emptyState) {
+                    const visible = await config.emptyState.isVisible().catch(() => false);
+                    if (visible) {
+                        tableState.empty = true;
+                        (0, debugUtils_1.logDebug)(config, 'info', 'init: header resolution failed but emptyState locator is visible — table is empty');
+                        return result;
+                    }
+                }
+                throw headerError;
+            }
             (0, debugUtils_1.logDebug)(config, 'info', `Table initialized with ${map.size} columns`, Array.from(map.keys()));
             if ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.detectCurrentPage) {
                 try {
@@ -269,6 +294,8 @@ const useTable = (rootLocator, configOptions = {}) => {
             return resolve(config.headerSelector, rootLocator).nth(idx);
         },
         countRows: async () => {
+            if (tableState.empty)
+                return 0;
             await _autoInit();
             const pag = config.strategies.pagination;
             const hasPagination = config.maxPages > 1 && !!((pag === null || pag === void 0 ? void 0 : pag.goNext) || (pag === null || pag === void 0 ? void 0 : pag.goNextBulk));
@@ -326,7 +353,10 @@ const useTable = (rootLocator, configOptions = {}) => {
                 await cell.bringIntoView();
                 const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[columnName];
                 if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) {
-                    return await columnOverride.read(cell);
+                    return await columnOverride.read(cell, {
+                        row, columnName, columnIndex: map.get(columnName),
+                        getCell: (name) => row.getCell(name),
+                    });
                 }
                 const text = await cell.innerText();
                 return (text || '').trim();
@@ -349,6 +379,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 log("No goToFirst strategy configured. Table may not be on page 1.");
             }
             tableState.currentPageIndex = 0;
+            tableState.empty = false;
             tableMapper.clear();
             log("Table reset complete. Calling autoInit to restore state.");
             await _autoInit();
@@ -356,6 +387,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         revalidate: async () => {
             log("Revalidating table structure...");
             await tableMapper.remapHeaders();
+            tableState.empty = false;
             log("Table revalidated.");
         },
         getRow: (filters, options = { exact: false }) => {
@@ -375,6 +407,55 @@ const useTable = (rootLocator, configOptions = {}) => {
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(index);
             return _makeSmart(rowLocator, map, index);
         },
+        findRowByIndex: async (index, options) => {
+            var _a, _b;
+            log(`findRowByIndex: index=${index} options=${safeStringify(options)}`);
+            await _autoInit();
+            const map = tableMapper.getMapSync();
+            const resolveRI = config.strategies.resolveRowIndex;
+            const viewport = config.strategies.viewport;
+            // Identifying a row by its logical index requires a resolveRowIndex strategy. Without one
+            // the library can only offer render-window-relative getRowByIndex, or filter-based findRow.
+            if (!resolveRI) {
+                throw new Error(`findRowByIndex(${index}) requires a strategies.resolveRowIndex to identify rows by their logical index. ` +
+                    `Configure one (e.g. read the grid's row-index attribute), or use getRowByIndex() (current render window) / findRow(filters).`);
+            }
+            // The currently-mounted row whose logical index === index, if any.
+            const findMounted = async () => {
+                const rows = await resolve(config.rowSelector, rootLocator).all();
+                for (const r of rows) {
+                    if ((await resolveRI(r)) === index)
+                        return r;
+                }
+                return null;
+            };
+            // 1. Already mounted (no navigation needed)?
+            let loc = await findMounted();
+            // 2. Fast path: jump straight to it via the viewport's random-access scroll.
+            if (!loc && (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow)) {
+                log(`findRowByIndex: scrolling to row ${index}`);
+                await viewport.scrollToRow(createStrategyContext(), index);
+                loc = await findMounted();
+            }
+            // 3. Fallback: advance pages (on infinite-scroll tables, a "page" is a scroll step) until
+            //    the row is reached. Bounded by maxPages so an unreachable index can't loop forever.
+            if (!loc && config.strategies.pagination) {
+                const effectiveMaxPages = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
+                let pagesScanned = 1;
+                while (!loc && pagesScanned < effectiveMaxPages) {
+                    if (!await _advancePage(false))
+                        break;
+                    pagesScanned++;
+                    loc = await findMounted();
+                }
+            }
+            if (!loc) {
+                throw new Error(`findRowByIndex(${index}): could not reach row ${index}. ` +
+                    `Ensure a viewport.scrollToRow or pagination can bring it into view (searched up to maxPages=${(_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages}).`);
+            }
+            await (0, debugUtils_1.debugDelay)(config, 'findRow');
+            return _makeSmart(loc, map, index, tableState.currentPageIndex);
+        },
         findRow: async (filters, options) => {
             log(`findRow: filters=${safeStringify(filters)} options=${safeStringify(options)}`);
             return rowFinder.findRow(filters, options);
@@ -384,10 +465,13 @@ const useTable = (rootLocator, configOptions = {}) => {
             return rowFinder.findRows(filters !== null && filters !== void 0 ? filters : {}, options);
         },
         isInitialized: () => {
-            const initialized = tableMapper.isInitialized();
+            const initialized = tableMapper.isInitialized() || tableState.empty;
             log(`isInitialized: ${initialized}`);
             return initialized;
         },
+        isEmpty: () => {
+            return tableState.empty;
+        },
         sorting: {
             apply: async (columnName, direction) => {
                 var _a;
@@ -434,6 +518,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         // ─── Shared async row iterator ───────────────────────────────────────────
         [Symbol.asyncIterator]() {
             return __asyncGenerator(this, arguments, function* _a() {
+                var _b;
                 yield __await(_autoInit());
                 const map = tableMapper.getMapSync();
                 const effectiveMaxPages = config.maxPages;
@@ -449,7 +534,13 @@ const useTable = (rootLocator, configOptions = {}) => {
                         const pageRows = yield __await(rowLocators.all());
                         const barrier = new navigationBarrier_1.NavigationBarrier(newIndices.length);
                         for (const idx of newIndices) {
-                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex, tableState.currentPageIndex, barrier), index: rowIndex, rowIndex, pageIndex: tableState.currentPageIndex });
+                            // index = visit-order counter; rowIndex = logical/data index (B-hybrid, #362).
+                            const logical = (_b = yield __await((0, rowResolution_1.resolveLogicalRowIndex)(pageRows[idx], config, () => rowIndex))) !== null && _b !== void 0 ? _b : rowIndex;
+                            const sr = _makeSmart(pageRows[idx], map, logical, tableState.currentPageIndex, barrier);
+                            // Iterator rows share one per-page DOM snapshot (positional locators); disable
+                            // toJSON's scroll-back recovery so reading one row can't invalidate the others (#366).
+                            sr._inBatch = true;
+                            yield yield __await({ row: sr, index: rowIndex, rowIndex: logical, pageIndex: tableState.currentPageIndex });
                             rowIndex++;
                         }
                         if (pagesScanned >= effectiveMaxPages)
@@ -477,6 +568,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 config,
                 getPage: () => rootLocator.page(),
                 getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
             }, callback, options);
         },
         map: async (callback, options = {}) => {
@@ -491,6 +583,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 config,
                 getPage: () => rootLocator.page(),
                 getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
             }, callback, options);
         },
         toArray: async (callback, options = {}) => {
@@ -515,6 +608,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 config,
                 getPage: () => rootLocator.page(),
                 getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
             }, predicate, options);
         },
         generateConfig: async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.18.0",
+  "version": "6.19.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",