@rickcedwhat/playwright-smart-table 6.22.0-next.0d452da → 6.22.0-next.28cae60

package/dist/engine/rowFinder.d.ts

@@ -13,7 +13,7 @@ export declare class RowFinder<T = any> {
     private tableState;
     private advancePage;
     private resolve;
-    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number | undefined, tablePageIndex?: number, barrier?: NavigationBarrier, rowSelector?: string) => SmartRow<T>, tableState?: {
+    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number | undefined, tablePageIndex?: number, barrier?: NavigationBarrier, healSelector?: string) => SmartRow<T>, tableState?: {
         currentPageIndex: number;
     }, advancePage?: (useBulk: boolean) => Promise<boolean>);
     private splitFilters;
@@ -38,8 +38,8 @@ export declare class RowFinder<T = any> {
      * every row calling elementHandle() + evaluate() per row (O(n) CDP roundtrips, and
      * elementHandle() is soft-deprecated). We 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)
+     * same selector/scope as everywhere else, so a string or function rowSelector behave
+     * identically. (#350)
      */
     private throwIfAmbiguous;
     private scanDomPosition;

package/dist/engine/rowFinder.js

@@ -269,8 +269,8 @@ class RowFinder {
      * every row calling elementHandle() + evaluate() per row (O(n) CDP roundtrips, and
      * elementHandle() is soft-deprecated). We 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)
+     * same selector/scope as everywhere else, so a string or function rowSelector behave
+     * identically. (#350)
      */
     async throwIfAmbiguous(rows, filters, map) {
         const sampleData = [];

package/dist/engine/tableIteration.d.ts

@@ -7,7 +7,7 @@ export interface TableIterationEnv<T = any> {
     getRowLocators: () => Locator;
     getMap: () => Map<string, number>;
     advancePage: (useBulk: boolean) => Promise<boolean>;
-    makeSmartRow: (rowLocator: Locator, map: Map<string, number>, rowIndex: number, tablePageIndex?: number, barrier?: NavigationBarrier, rowSelector?: string) => SmartRow<T>;
+    makeSmartRow: (rowLocator: Locator, map: Map<string, number>, rowIndex: number, tablePageIndex?: number, barrier?: NavigationBarrier, healSelector?: string) => SmartRow<T>;
     createSmartRowArray: (rows: SmartRow<T>[]) => SmartRowArray<T>;
     config: FinalTableConfig<T>;
     getPage: () => Page;

package/dist/engine/tableIteration.js

@@ -9,6 +9,7 @@ const navigationBarrier_1 = require("../utils/navigationBarrier");
 const mutex_1 = require("../utils/mutex");
 const rowResolution_1 = require("./rowResolution");
 const scanPages_1 = require("./scanPages");
+const smartRowInternals_1 = require("../utils/smartRowInternals");
 function log(config, msg) {
     (0, debugUtils_1.logDebug)(config, 'verbose', msg);
 }
@@ -112,7 +113,7 @@ async function runMap(env, callback, options = {}, label = 'map') {
                     const sr = env.makeSmartRow(pageRows[idx], map, logicalIndex, env.getCurrentPageIndex(), barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
                     // Mark as part of an iteration batch so toJSON's #366 re-pin uses rescan-only recovery
                     // (no scroll-back) — scrolling here would disrupt sibling rows' positional locators.
-                    sr._inBatch = true;
+                    (0, smartRowInternals_1.internals)(sr)._inBatch = true;
                     return sr;
                 }));
                 // enumIndex = visit-order counter (ctx.index); row.rowIndex = logical (ctx.rowIndex).

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { PLAYWRIGHT_SMART_TABLE_VERSION } from './packageVersion';
 export { useTable } from './useTable';
-export type { TableConfig, TableResult, SmartRow, SmartCell, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, SyntheticColumnDef, ColumnOverride, ColumnOverrideReadContext, TableStrategies, LoadingStrategy, ViewportStrategy, FilterStrategy, NavigationPrimitives, DedupeStrategy, ContentReadyStrategy, FillStrategy, PaginationStrategy, HeaderStrategy, } from './types';
+export type { TableConfig, TableResult, SmartRow, SmartCell, Selector, TableSelector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, SyntheticColumnDef, ColumnOverride, ColumnOverrideReadContext, TableStrategies, LoadingStrategy, ViewportStrategy, FilterStrategy, NavigationPrimitives, DedupeStrategy, ContentReadyStrategy, FillStrategy, PaginationStrategy, HeaderStrategy, } from './types';
 export { Strategies } from './strategies';
 export * as presets from './presets';
 /**

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.22.0-next.0d452da";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.22.0-next.28cae60";

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.22.0-next.0d452da";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.22.0-next.28cae60";

package/dist/plugins/index.d.ts

@@ -27,9 +27,9 @@ export declare const Plugins: {
             };
             pagination: import("..").PaginationPrimitives;
         };
-        headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
-        rowSelector?: string | undefined;
-        cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
+        headerSelector?: import("..").TableSelector | undefined;
+        rowSelector?: import("..").TableSelector | undefined;
+        cellSelector?: import("..").TableSelector | undefined;
         maxPages?: number | undefined;
         concurrency?: import("../types").RowIterationMode | undefined;
         headerTransformer?: ((args: {
@@ -68,9 +68,9 @@ export declare const Plugins: {
                 locator: any;
             } | null>;
         };
-        headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
-        rowSelector?: string | undefined;
-        cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
+        headerSelector?: import("..").TableSelector | undefined;
+        rowSelector?: import("..").TableSelector | undefined;
+        cellSelector?: import("..").TableSelector | undefined;
         maxPages?: number | undefined;
         concurrency?: import("../types").RowIterationMode | undefined;
         headerTransformer?: ((args: {
@@ -93,9 +93,9 @@ export declare const Plugins: {
      */
     MUI: {
         Strategies: import("..").TableStrategies | undefined;
-        headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
-        rowSelector?: string | undefined;
-        cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
+        headerSelector?: import("..").TableSelector | undefined;
+        rowSelector?: import("..").TableSelector | undefined;
+        cellSelector?: import("..").TableSelector | undefined;
         maxPages?: number | undefined;
         concurrency?: import("../types").RowIterationMode | undefined;
         headerTransformer?: ((args: {

package/dist/presets/mui.js

@@ -4,6 +4,12 @@ exports.muiDataGrid = exports.muiTable = void 0;
 exports.createMuiTable = createMuiTable;
 exports.createMuiDataGrid = createMuiDataGrid;
 const debugUtils_1 = require("../utils/debugUtils");
+const cssSelector_1 = require("../utils/cssSelector");
+// Fallbacks for in-browser queries when the configured selector is a function.
+// Only DataGrid rows carry data-rowindex, so this can't match cells or headers.
+const MUI_ROW_CSS = '[data-rowindex]';
+const MUI_HEADER_CSS = '.MuiDataGrid-columnHeader';
+const cssOr = (selector, fallback) => typeof selector === 'string' ? selector : fallback;
 const DEFAULT_LABELS = {
     nextPage: 'Go to next page',
     previousPage: 'Go to previous page',
@@ -331,7 +337,7 @@ function createMuiDataGrid(opts) {
             // scroll methods use querySelector rather than closest().
             viewport: {
                 getVisibleRowRange: async ({ root, config }) => {
-                    const rowSel = config.rowSelector;
+                    const rowSel = cssOr(config.rowSelector, MUI_ROW_CSS);
                     return root.evaluate((el, rowSel) => {
                         const indices = Array.from(el.querySelectorAll(rowSel))
                             .map(r => Number(r.getAttribute('data-rowindex')))
@@ -345,8 +351,13 @@ function createMuiDataGrid(opts) {
                 // the DOM positions of rows overlapping the virtualScroller's bounds so map/forEach
                 // skip the overscan rows MUI keeps mounted above/below the fold. The scroller is a
                 // descendant of root, so querySelector (not closest).
-                getVisibleRowIndices: async ({ root, config }) => {
-                    const rowSel = config.rowSelector;
+                getVisibleRowIndices: async ({ root, config, resolve }) => {
+                    // Positions must index into the configured row set, so no CSS fallback here.
+                    const rowSel = (0, cssSelector_1.cssSelectorOrWarn)(config, 'rowSelector', 'MUI DataGrid overscan filtering');
+                    if (!rowSel) {
+                        const count = await resolve(config.rowSelector, root).count();
+                        return Array.from({ length: count }, (_, i) => i);
+                    }
                     return root.evaluate((el, rowSel) => {
                         const scroller = el.querySelector('.MuiDataGrid-virtualScroller');
                         const rows = Array.from(el.querySelectorAll(rowSel));
@@ -367,7 +378,7 @@ function createMuiDataGrid(opts) {
                     }, rowSel);
                 },
                 getVisibleColumnRange: async ({ root, config }) => {
-                    const rowSel = config.rowSelector;
+                    const rowSel = cssOr(config.rowSelector, MUI_ROW_CSS);
                     const cellSel = typeof config.cellSelector === 'string' ? config.cellSelector : '[aria-colindex]';
                     return root.evaluate((el, { rowSel, cellSel }) => {
                         const scroller = el.querySelector('.MuiDataGrid-virtualScroller');
@@ -409,7 +420,7 @@ function createMuiDataGrid(opts) {
                     }, { rowSel, cellSel });
                 },
                 scrollToRow: async ({ root, config }, rowIndex) => {
-                    const rowSel = config.rowSelector;
+                    const rowSel = cssOr(config.rowSelector, MUI_ROW_CSS);
                     await root.evaluate((el, { rowSel, idx }) => {
                         const scroller = el.querySelector('.MuiDataGrid-virtualScroller');
                         if (!scroller)
@@ -463,10 +474,10 @@ function createMuiDataGrid(opts) {
                         .catch(() => { });
                 },
                 scrollToColumn: async ({ root, config, page }, colIndex) => {
-                    const headerSel = typeof config.headerSelector === 'string' ? config.headerSelector : null;
+                    const headerSel = cssOr(config.headerSelector, MUI_HEADER_CSS);
                     await root.evaluate((el, { headerSel, idx }) => {
                         const scroller = el.querySelector('.MuiDataGrid-virtualScroller');
-                        if (!scroller || !headerSel)
+                        if (!scroller)
                             return;
                         const headers = Array.from(el.querySelectorAll(headerSel));
                         const targetAriaIdx = idx + 1; // aria-colindex is 1-based

package/dist/smartRow.js

@@ -14,7 +14,13 @@ const pageIndex_1 = require("./utils/pageIndex");
  * Returns the target cell locator after navigation.
  */
 const _navigateToCell = async (params) => {
-    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier, allowMissingCell } = params;
+    var _a;
+    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, barrier, allowMissingCell } = params;
+    // getRowByIndex supplies a position in the mounted row set. Resolve it while the
+    // selected row is still mounted, before horizontal scrolling can evict it.
+    const rowIndex = params.renderWindowPosition && config.strategies.viewport && config.strategies.resolveRowIndex
+        ? (_a = (await (0, rowResolution_1.resolveLogicalRowIndex)(rowLocator, config, () => undefined))) === null || _a === void 0 ? void 0 : _a.index
+        : params.rowIndex;
     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
@@ -358,6 +364,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 index: idx,
                 rowLocator,
                 rowIndex,
+                renderWindowPosition,
                 barrier: smart._barrier
             });
             // Run beforeCellRead hook (same as toJSON does after navigation).
@@ -419,6 +426,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             index: idx,
             rowLocator,
             rowIndex,
+            renderWindowPosition,
             barrier: smart._barrier,
             allowMissingCell: !!(columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read),
         });
@@ -718,6 +726,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 index: idx,
                 rowLocator: stableRow,
                 rowIndex,
+                renderWindowPosition,
                 barrier: smart._barrier,
                 allowMissingCell: !!mapper,
             });
@@ -834,6 +843,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 index: colIdx,
                 rowLocator,
                 rowIndex,
+                renderWindowPosition,
                 barrier: smart._barrier
             });
             const columnOverride = (_c = config.columnOverrides) === null || _c === void 0 ? void 0 : _c[colName];

package/dist/strategies/filter.js

@@ -8,9 +8,8 @@ exports.FilterStrategies = void 0;
 exports.FilterStrategies = {
     default: {
         apply({ rows, filter, colIndex, tableContext }) {
-            const page = tableContext.page;
-            const resolve = tableContext.resolve;
-            const cellTemplate = resolve(tableContext.config.cellSelector, page);
+            const scopeRow = tableContext.page.locator(':scope');
+            const cellTemplate = tableContext.resolve(tableContext.config.cellSelector, scopeRow);
             const targetCell = cellTemplate.nth(colIndex);
             if (typeof filter.value === 'function') {
                 return rows.filter({ has: filter.value(targetCell) });

package/dist/strategies/viewport.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ViewportStrategies = void 0;
 const debugUtils_1 = require("../utils/debugUtils");
+const cssSelector_1 = require("../utils/cssSelector");
 /**
  * Viewport strategies for tables where row and cell elements carry a DOM attribute
  * equal to their index (e.g. Braintrust logs table, TanStack-style grids).
@@ -46,7 +47,9 @@ const dataAttribute = (options) => {
     const scrollPadding = (_g = options === null || options === void 0 ? void 0 : options.scrollPadding) !== null && _g !== void 0 ? _g : 20;
     return {
         getVisibleColumnRange: async ({ root, config }) => {
-            const rowSel = config.rowSelector;
+            const rowSel = (0, cssSelector_1.cssSelectorOrWarn)(config, 'rowSelector', 'dataAttribute viewport column range');
+            if (!rowSel)
+                return cssSelector_1.UNKNOWN_RANGE;
             const cellSel = typeof config.cellSelector === 'string' ? config.cellSelector : `[${colAttr}]`;
             const result = await root.evaluate((el, { rowSel, cellSel, colAttr, colOffset }) => {
                 const firstRow = el.querySelector(rowSel);
@@ -65,8 +68,12 @@ const dataAttribute = (options) => {
             }
             return { first: result.first, last: result.last };
         },
-        getVisibleRowIndices: async ({ root, config }) => {
-            const rowSel = config.rowSelector;
+        getVisibleRowIndices: async ({ root, config, resolve }) => {
+            const rowSel = (0, cssSelector_1.cssSelectorOrWarn)(config, 'rowSelector', 'dataAttribute viewport overscan filtering');
+            if (!rowSel) {
+                const count = await resolve(config.rowSelector, root).count();
+                return Array.from({ length: count }, (_, i) => i);
+            }
             // Geometry-based (mirrors getVisibleRowRange's inclusive intersection), but returns
             // the rows' DOM positions so the iteration engine can drop overscan rows (#353/#357).
             return root.evaluate((el, { rowSel, containerSel }) => {
@@ -92,7 +99,9 @@ const dataAttribute = (options) => {
             }, { rowSel, containerSel });
         },
         getVisibleRowRange: async ({ root, config }) => {
-            const rowSel = config.rowSelector;
+            const rowSel = (0, cssSelector_1.cssSelectorOrWarn)(config, 'rowSelector', 'dataAttribute viewport row range');
+            if (!rowSel)
+                return cssSelector_1.UNKNOWN_RANGE;
             const result = await root.evaluate((el, { rowSel, rowAttr, rowOffset, containerSel }) => {
                 const rows = Array.from(el.querySelectorAll(rowSel));
                 const container = containerSel
@@ -120,9 +129,11 @@ const dataAttribute = (options) => {
             }
             return { first: result.first, last: result.last };
         },
-        scrollToColumn: async ({ root, config }, colIndex) => {
-            const headerSel = typeof config.headerSelector === 'string' ? config.headerSelector : null;
-            if (!containerSel || !headerSel)
+        scrollToColumn: async ({ root, config, resolve }, colIndex) => {
+            if (!containerSel)
+                return;
+            const headerSel = (0, cssSelector_1.cssSelectorOrWarn)(config, 'headerSelector', 'dataAttribute viewport scrollToColumn');
+            if (!headerSel)
                 return;
             const cellSel = typeof config.cellSelector === 'string' ? config.cellSelector : `[${colAttr}]`;
             const canScroll = await root.evaluate((el, { containerSel, headerSel, cellSel, idx, columnWidth, scrollPadding }) => {
@@ -157,15 +168,20 @@ const dataAttribute = (options) => {
             if (!canScroll)
                 return;
             // Wait for a cell at this column index to mount in any row
-            await root
-                .locator(`${config.rowSelector} [${colAttr}="${colIndex + colOffset}"]`)
+            const rows = typeof config.rowSelector === 'string'
+                ? root.locator(config.rowSelector)
+                : resolve(config.rowSelector, root);
+            await rows
+                .locator(`[${colAttr}="${colIndex + colOffset}"]`)
                 .first()
                 .waitFor({ state: 'attached', timeout: attachTimeout });
         },
         scrollToRow: async ({ root, config }, rowIndex) => {
             if (!containerSel)
                 return;
-            const rowSel = config.rowSelector;
+            const rowSel = (0, cssSelector_1.cssSelectorOrWarn)(config, 'rowSelector', 'dataAttribute viewport scrollToRow');
+            if (!rowSel)
+                return;
             const canScroll = await root.evaluate((el, { containerSel, rowSel, rowAttr, idx, rowOffset, rowHeight, scrollPadding }) => {
                 const container = el.closest(containerSel);
                 if (!container)

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 * Return type for `resolveRowIndex`. A plain number gives the logical index only;\n * `{ index, selector }` additionally provides a CSS selector the library uses to\n * build a self-healing row locator that survives virtual-scroll DOM recycling.\n */\nexport type RowIndexResult = number | { index: number; selector: string };\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 DOM positions (0-based, document order \u2014 indices into the resolved\n   * `rowSelector` set) of rows currently within the scroll container's visible bounds.\n   * Unlike `getVisibleRowRange` (a logical min/max), this identifies the exact rows, so\n   * `map`/`forEach`/`filter` can skip overscan rows during collection (see #353 / #357).\n   * Geometry-based and inclusive (any overlap counts as visible). When the container can't\n   * be measured, return all positions so no rows are filtered.\n   */\n  getVisibleRowIndices?: (context: TableContext) => Promise<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   * // Atomic: snapshot all cell values in a single evaluate \u2014 zero inter-column stagger.\n   * // Requires cellSelector to be a CSS string (not a function).\n   * // Column overrides ARE supported (run against a frozen off-screen reconstruction).\n   * // Uses textContent (not layout-dependent innerText) for non-override columns.\n   * const coherent = await row.toJSON({ atomic: true });\n   */\n  toJSON(options?: { columns?: string[]; atomic?: boolean }): 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   *\n   * Prefers `strategies.viewport.scrollToRow` when configured; otherwise falls back to\n   * Playwright `scrollIntoViewIfNeeded()`.\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   * Get the resolved value of any column \u2014 real, override, or synthetic.\n   *\n   * When `strategies.viewport` or `strategies.navigation` is configured, runs the same\n   * cell-navigation pipeline as `toJSON` / `getCell().bringIntoView()` so off-screen\n   * virtualized cells are mounted before reading. Without those strategies, reads the\n   * current DOM cell (Playwright auto-wait).\n   *\n   * @param column - Column name (case-sensitive)\n   * @returns The column value as a string\n   */\n  getValue(column: string): Promise<string>;\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\nexport type ContentReadyStrategy = (row: Locator, page: Page) => Promise<void>;\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\n/** Context passed as the second argument to {@link ColumnOverride.read}. */\nexport interface ColumnOverrideReadContext {\n  /**\n   * The parent row. Use for multi-cell or row-derived values \u2014 e.g. a synthetic column\n   * that reads an `a[href]` or a `data-*` attribute from the row rather than a cell:\n   * `read: (_cell, { row }) => row.evaluate(el => el.querySelector('a')?.href)`.\n   */\n  row: SmartRow;\n  /** The column being read. */\n  columnName: string;\n  /** The column's 0-based index in the resolved header map. */\n  columnIndex: number;\n  /**\n   * Get a Locator for another cell in the same row by column name.\n   * Returns raw cell Locators, not override-processed values.\n   *\n   * In atomic mode, the Locator points at the frozen reconstructed cell \u2014 coherent with\n   * every other cell from the same snapshot. In non-atomic mode, it points at the live cell.\n   *\n   * @example\n   * read: async (_cell, { getCell }) => {\n   *   const name = (await getCell('Name').innerText()).trim();\n   *   const href = await getCell('Name').locator('a').getAttribute('href') || '';\n   *   return `${name} | ${href}`;\n   * }\n   */\n  getCell: (columnName: string) => Locator;\n}\n\nexport interface SyntheticColumnDef<T = any> {\n  compute: (row: SmartRow<T>) => Promise<string | number> | string | number;\n}\n\nexport interface ColumnOverride<TValue = any> {\n  /**\n   * How to extract the value from the cell.\n   * The second `context` argument provides the parent `row` (for multi-cell or row-derived\n   * values), plus `columnName` and `columnIndex`. Backwards-compatible: existing\n   * single-argument `read(cell)` implementations keep working.\n   */\n  read?: (cell: Locator, context: ColumnOverrideReadContext) => 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';\nexport type { NavigationPrimitives, CellNavigationStrategy } from './strategies/columns';\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   * Max ms to wait while `isTableLoading` returns true (countRows, findRow(s),\n   * page-ready gates, and sort when `sortStabilizationTimeout` is unset).\n   * @default 10000\n   */\n  loadingTimeout?: number;\n\n  /** Max ms to wait for sort stabilization when isTableLoading is set. Overrides `loadingTimeout` for sort only. @default 10000 */\n  sortStabilizationTimeout?: number;\n  /** Polling interval (ms) while waiting for sort / table-ready stabilization. @default 100 (sort) / 200 (table-ready) */\n  sortStabilizationPollInterval?: number;\n  /** Fallback delay (ms) after sort when no isTableLoading is configured. @default 200 */\n  sortStabilizationFallbackDelay?: number;\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   * When the index maps to a DOM attribute, return `{ index, selector }` instead of\n   * a plain number. The library uses the CSS selector to build a **self-healing row\n   * locator** that re-queries the DOM on every action \u2014 surviving virtual-scroll\n   * recycling for `getCell`, `smartFill`, and `toJSON` without manual re-pinning.\n   *\n   * @example\n   * // MUI DataGrid: self-healing via data-rowindex attribute\n   * resolveRowIndex: async (row) => {\n   *   const v = await row.getAttribute('data-rowindex').catch(() => null);\n   *   if (v === null || isNaN(Number(v))) return undefined;\n   *   return { index: Number(v), selector: `[data-rowindex=\"${v}\"]` };\n   * }\n   */\n  resolveRowIndex?: (row: Locator) => Promise<RowIndexResult | undefined>;\n\n  /**\n   * Waits until a row's content has stabilized before cloning in\n   * `toJSON({ atomic: true })`. Needed for recycling virtualizers where the\n   * framework updates element positions synchronously but renders cell content\n   * asynchronously (e.g. react-window, react-virtuoso with React concurrent mode).\n   *\n   * Without this, the clone captures stale content from the previous occupant of the\n   * DOM slot \u2014 the element is at the correct position but React hasn't re-rendered yet.\n   *\n   * Use `Strategies.ContentReady.textStable()` for the built-in text-polling strategy.\n   *\n   * @example\n   * strategies: {\n   *   contentReady: Strategies.ContentReady.textStable({ timeout: 500 }),\n   * }\n   */\n  contentReady?: ContentReadyStrategy;\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  /**\n   * Number of pages to scan for verification / iteration.\n   * Defaults to `1` \u2014 set explicitly (e.g. `maxPages: 5`) when using a pagination\n   * strategy, or you will never leave page 1. Init logs a warning when pagination\n   * is configured and this is still `1`.\n   */\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   * Defaults to sequential when unset (safer for UI interactions).\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  /** Hook called after reset completes (after goToFirst, cache clear, and autoInit). */\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  /**\n   * Computed columns with no DOM presence. Each key becomes a virtual column name\n   * available in `toJSON()`, `getValue()`, and `findRow()`/`findRows()` filters.\n   * The `compute` function receives the full SmartRow and must only read real or\n   * override columns (no chaining between synthetics).\n   */\n  syntheticColumns?: Record<string, SyntheticColumnDef<T>>;\n\n  /**\n   * Locator for an empty-state element that replaces the table when there are no results.\n   * If header resolution fails during init() and this locator is visible, init() succeeds\n   * and isEmpty() returns true. All row operations still throw normally.\n   */\n  emptyState?: Locator;\n}\n\n/**\n * @internal Resolved config after defaults are applied. Prefer {@link TableConfig} in public code.\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  /**\n   * The row's logical/data-model index. When a `resolveRowIndex` strategy is configured\n   * (e.g. MUI DataGrid's `data-rowindex`) this is the grid's true row index; otherwise it\n   * equals `index`. Use this for `row.bringIntoView()` and position math on virtualized\n   * tables \u2014 it is stable across scrolling/dedupe, unlike the visit-order `index`.\n   */\n  rowIndex: number;\n  /**\n   * 0-based enumeration counter \u2014 the order this row was visited (contiguous within the run).\n   * Not a DOM position or grid identity. Use `rowIndex` for the row's data-model index.\n   */\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\n/**\n * Result of {@link useTable}. Implements `AsyncIterable` \u2014 `for await (const { row } of table)`\n * uses the same page-walk as `map` / `forEach` (`scanPages` + runMap): overscan, loading,\n * dedupe, and EOF final scan (#427).\n */\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number; pageIndex: number }> {\n  /**\n   * Current DOM page index (0-based). Automatically maintained during pagination\n   * and `bringIntoView`. Treat as **read-only** \u2014 assigning manually can desync\n   * the path planner. Manual writes log a warning; prefer `reset()` / library\n   * navigation. Writable access may become read-only in v7.\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  /**\n   * SYNC: Returns true if init() resolved via the emptyState path \u2014 the table's\n   * empty-state locator was visible when header resolution failed.\n   * Row operations still throw normally; use this to branch before calling them.\n   */\n  isEmpty(): 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   * @note Cannot filter by `syntheticColumns` or `columnOverrides.read` keys \u2014 those need\n   * async evaluation via `findRow()` / `findRows()`. DOM filters use `strategies.getCellLocator`\n   * when configured (column-virtualized grids), otherwise `cellSelector` + column index.\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. For the row with a specific logical/data-model index on a\n   * virtualized table, use the async `findRowByIndex(i)` instead (it scrolls to the row);\n   * to iterate by logical identity, use `map` / `findRows` (with a `dedupe` strategy).\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: Returns the row with a specific logical/data-model index, scrolling/paginating to\n   * reach it. Unlike the sync `getRowByIndex` (render-window position), this resolves the true\n   * data-model row `index` on virtualized tables.\n   *\n   * Reaches the row via, in order: a currently-mounted match, the viewport's random-access\n   * `scrollToRow` fast path, then advancing pages (on infinite-scroll tables a \"page\" is a\n   * scroll step) up to `maxPages`.\n   *\n   * Requires a `strategies.resolveRowIndex` to identify rows by logical index \u2014 throws if one\n   * is not configured. Also throws if the row cannot be reached (no silent wrong-row fallback).\n   *\n   * @param index 0-based logical/data-model row index\n   * @param options - `maxPages` bounds how far to scroll/paginate (defaults to config.maxPages)\n   */\n  findRowByIndex: (\n    index: number,\n    options?: { maxPages?: number }\n  ) => Promise<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   * Resolves the named column and scrolls it into view.\n   * Prefers `strategies.viewport.scrollToColumn` when configured; otherwise scrolls the\n   * header cell via Playwright `scrollIntoViewIfNeeded()`.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * Counts the number of rows, optionally filtered.\n   * Without arguments, counts all rows. With filters, counts only matching rows.\n   * Paginates when pagination is configured.\n   */\n  countRows: (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }) => 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   * @deprecated Use `mapColumn` (or `map`) instead. Will be removed in v7.0.0.\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: calls goToFirst (if configured), clears cache, re-inits headers, then calls onReset.\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   * Defaults to `concurrency: 'sequential'` (safe for clicks/fills). Pass\n   * `concurrency: 'parallel'` for read-only extraction, or `'synchronized'` when\n   * navigation must stay lock-step on virtualized grids.\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * // Default sequential \u2014 safe for UI interactions\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   * });\n   *\n   * @example\n   * // Read-only extraction \u2014 opt into parallel\n   * const emails = await table.map(\n   *   ({ row }) => row.getCell('Email').innerText(),\n   *   { concurrency: 'parallel' }\n   * );\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 * Selector used by strategies (e.g. pagination buttons, spinners): a CSS string resolved\n * relative to the parent, or a function that receives the parent and returns a Locator.\n * @example\n * nextButton: 'button.next'\n * nextButton: (root) => root.getByRole('button', { name: 'Next' })\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Selector for `headerSelector`, `rowSelector`, and `cellSelector`: a CSS string resolved\n * relative to the parent, or a function that receives the parent Locator (the table root for\n * headers/rows, the row for cells) and returns a Locator.\n *\n * Some features evaluate selectors in the browser and need a CSS string. Given a function,\n * the `dataAttribute` viewport strategy warns once and skips the step that needs the string.\n * The MUI DataGrid viewport instead uses `[data-rowindex]` for row scrolling and ranges,\n * and `.MuiDataGrid-columnHeader` for header scrolling. Its overscan filtering warns and\n * includes every mounted row because it needs the configured row selector.\n * @example\n * rowSelector: 'tbody tr'\n * rowSelector: (root) => root.getByRole('row').filter({ has: root.getByRole('cell') })\n * // Headers rendered as a separate table outside the root:\n * headerSelector: (root) => root.page().locator('#header-table th')\n */\nexport type TableSelector = string | ((parent: Locator) => Locator);\n\n/**\n * Return type for `resolveRowIndex`. A plain number gives the logical index only;\n * `{ index, selector }` additionally provides a CSS selector the library uses to\n * build a self-healing row locator that survives virtual-scroll DOM recycling.\n */\nexport type RowIndexResult = number | { index: number; selector: string };\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 DOM positions (0-based, document order \u2014 indices into the resolved\n   * `rowSelector` set) of rows currently within the scroll container's visible bounds.\n   * Unlike `getVisibleRowRange` (a logical min/max), this identifies the exact rows, so\n   * `map`/`forEach`/`filter` can skip overscan rows during collection (see #353 / #357).\n   * Geometry-based and inclusive (any overlap counts as visible). When the container can't\n   * be measured, return all positions so no rows are filtered.\n   */\n  getVisibleRowIndices?: (context: TableContext) => Promise<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   * // Atomic: snapshot all cell values in a single evaluate \u2014 zero inter-column stagger.\n   * // Requires cellSelector to be a CSS string (not a function).\n   * // Column overrides ARE supported (run against a frozen off-screen reconstruction).\n   * // Uses textContent (not layout-dependent innerText) for non-override columns.\n   * const coherent = await row.toJSON({ atomic: true });\n   */\n  toJSON(options?: { columns?: string[]; atomic?: boolean }): 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   *\n   * Prefers `strategies.viewport.scrollToRow` when configured; otherwise falls back to\n   * Playwright `scrollIntoViewIfNeeded()`.\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   * Get the resolved value of any column \u2014 real, override, or synthetic.\n   *\n   * When `strategies.viewport` or `strategies.navigation` is configured, runs the same\n   * cell-navigation pipeline as `toJSON` / `getCell().bringIntoView()` so off-screen\n   * virtualized cells are mounted before reading. Without those strategies, reads the\n   * current DOM cell (Playwright auto-wait).\n   *\n   * @param column - Column name (case-sensitive)\n   * @returns The column value as a string\n   */\n  getValue(column: string): Promise<string>;\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\nexport type ContentReadyStrategy = (row: Locator, page: Page) => Promise<void>;\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\n/** Context passed as the second argument to {@link ColumnOverride.read}. */\nexport interface ColumnOverrideReadContext {\n  /**\n   * The parent row. Use for multi-cell or row-derived values \u2014 e.g. a synthetic column\n   * that reads an `a[href]` or a `data-*` attribute from the row rather than a cell:\n   * `read: (_cell, { row }) => row.evaluate(el => el.querySelector('a')?.href)`.\n   */\n  row: SmartRow;\n  /** The column being read. */\n  columnName: string;\n  /** The column's 0-based index in the resolved header map. */\n  columnIndex: number;\n  /**\n   * Get a Locator for another cell in the same row by column name.\n   * Returns raw cell Locators, not override-processed values.\n   *\n   * In atomic mode, the Locator points at the frozen reconstructed cell \u2014 coherent with\n   * every other cell from the same snapshot. In non-atomic mode, it points at the live cell.\n   *\n   * @example\n   * read: async (_cell, { getCell }) => {\n   *   const name = (await getCell('Name').innerText()).trim();\n   *   const href = await getCell('Name').locator('a').getAttribute('href') || '';\n   *   return `${name} | ${href}`;\n   * }\n   */\n  getCell: (columnName: string) => Locator;\n}\n\nexport interface SyntheticColumnDef<T = any> {\n  compute: (row: SmartRow<T>) => Promise<string | number> | string | number;\n}\n\nexport interface ColumnOverride<TValue = any> {\n  /**\n   * How to extract the value from the cell.\n   * The second `context` argument provides the parent `row` (for multi-cell or row-derived\n   * values), plus `columnName` and `columnIndex`. Backwards-compatible: existing\n   * single-argument `read(cell)` implementations keep working.\n   */\n  read?: (cell: Locator, context: ColumnOverrideReadContext) => 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';\nexport type { NavigationPrimitives, CellNavigationStrategy } from './strategies/columns';\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   * Max ms to wait while `isTableLoading` returns true (countRows, findRow(s),\n   * page-ready gates, and sort when `sortStabilizationTimeout` is unset).\n   * @default 10000\n   */\n  loadingTimeout?: number;\n\n  /** Max ms to wait for sort stabilization when isTableLoading is set. Overrides `loadingTimeout` for sort only. @default 10000 */\n  sortStabilizationTimeout?: number;\n  /** Polling interval (ms) while waiting for sort / table-ready stabilization. @default 100 (sort) / 200 (table-ready) */\n  sortStabilizationPollInterval?: number;\n  /** Fallback delay (ms) after sort when no isTableLoading is configured. @default 200 */\n  sortStabilizationFallbackDelay?: number;\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   * When the index maps to a DOM attribute, return `{ index, selector }` instead of\n   * a plain number. The library uses the CSS selector to build a **self-healing row\n   * locator** that re-queries the DOM on every action \u2014 surviving virtual-scroll\n   * recycling for `getCell`, `smartFill`, and `toJSON` without manual re-pinning.\n   *\n   * @example\n   * // MUI DataGrid: self-healing via data-rowindex attribute\n   * resolveRowIndex: async (row) => {\n   *   const v = await row.getAttribute('data-rowindex').catch(() => null);\n   *   if (v === null || isNaN(Number(v))) return undefined;\n   *   return { index: Number(v), selector: `[data-rowindex=\"${v}\"]` };\n   * }\n   */\n  resolveRowIndex?: (row: Locator) => Promise<RowIndexResult | undefined>;\n\n  /**\n   * Waits until a row's content has stabilized before cloning in\n   * `toJSON({ atomic: true })`. Needed for recycling virtualizers where the\n   * framework updates element positions synchronously but renders cell content\n   * asynchronously (e.g. react-window, react-virtuoso with React concurrent mode).\n   *\n   * Without this, the clone captures stale content from the previous occupant of the\n   * DOM slot \u2014 the element is at the correct position but React hasn't re-rendered yet.\n   *\n   * Use `Strategies.ContentReady.textStable()` for the built-in text-polling strategy.\n   *\n   * @example\n   * strategies: {\n   *   contentReady: Strategies.ContentReady.textStable({ timeout: 500 }),\n   * }\n   */\n  contentReady?: ContentReadyStrategy;\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  /**\n   * Selector for the header cells, relative to the table root. Default `'thead th'`.\n   * Use a function to reach headers outside the root, e.g.\n   * `(root) => root.page().locator('#header-table th')`.\n   */\n  headerSelector?: TableSelector;\n  /** Selector for the rows, relative to the table root. Default `'tbody tr'`. */\n  rowSelector?: TableSelector;\n  /** Selector for the cells, relative to a row. Default `'td'`. */\n  cellSelector?: TableSelector;\n  /**\n   * Number of pages to scan for verification / iteration.\n   * Defaults to `1` \u2014 set explicitly (e.g. `maxPages: 5`) when using a pagination\n   * strategy, or you will never leave page 1. Init logs a warning when pagination\n   * is configured and this is still `1`.\n   */\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   * Defaults to sequential when unset (safer for UI interactions).\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  /** Hook called after reset completes (after goToFirst, cache clear, and autoInit). */\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  /**\n   * Computed columns with no DOM presence. Each key becomes a virtual column name\n   * available in `toJSON()`, `getValue()`, and `findRow()`/`findRows()` filters.\n   * The `compute` function receives the full SmartRow and must only read real or\n   * override columns (no chaining between synthetics).\n   */\n  syntheticColumns?: Record<string, SyntheticColumnDef<T>>;\n\n  /**\n   * Locator for an empty-state element that replaces the table when there are no results.\n   * If header resolution fails during init() and this locator is visible, init() succeeds\n   * and isEmpty() returns true. All row operations still throw normally.\n   */\n  emptyState?: Locator;\n}\n\n/**\n * @internal Resolved config after defaults are applied. Prefer {@link TableConfig} in public code.\n */\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: TableSelector;\n  rowSelector: TableSelector;\n  cellSelector: TableSelector;\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  /**\n   * The row's logical/data-model index. When a `resolveRowIndex` strategy is configured\n   * (e.g. MUI DataGrid's `data-rowindex`) this is the grid's true row index; otherwise it\n   * equals `index`. Use this for `row.bringIntoView()` and position math on virtualized\n   * tables \u2014 it is stable across scrolling/dedupe, unlike the visit-order `index`.\n   */\n  rowIndex: number;\n  /**\n   * 0-based enumeration counter \u2014 the order this row was visited (contiguous within the run).\n   * Not a DOM position or grid identity. Use `rowIndex` for the row's data-model index.\n   */\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 config.concurrency, then 'sequential'\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\n/**\n * Result of {@link useTable}. Implements `AsyncIterable` \u2014 `for await (const { row } of table)`\n * uses the same page-walk as `map` / `forEach` (`scanPages` + runMap): overscan, loading,\n * dedupe, and EOF final scan (#427).\n */\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number; pageIndex: number }> {\n  /**\n   * Current DOM page index (0-based). Automatically maintained during pagination\n   * and `bringIntoView`. Treat as **read-only** \u2014 assigning manually can desync\n   * the path planner. Manual writes log a warning; prefer `reset()` / library\n   * navigation. Writable access may become read-only in v7.\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  /**\n   * SYNC: Returns true if init() resolved via the emptyState path \u2014 the table's\n   * empty-state locator was visible when header resolution failed.\n   * Row operations still throw normally; use this to branch before calling them.\n   */\n  isEmpty(): 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   * @note Cannot filter by `syntheticColumns` or `columnOverrides.read` keys \u2014 those need\n   * async evaluation via `findRow()` / `findRows()`. DOM filters use `strategies.getCellLocator`\n   * when configured (column-virtualized grids), otherwise `cellSelector` + column index.\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. For the row with a specific logical/data-model index on a\n   * virtualized table, use the async `findRowByIndex(i)` instead (it scrolls to the row);\n   * to iterate by logical identity, use `map` / `findRows` (with a `dedupe` strategy).\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: Returns the row with a specific logical/data-model index, scrolling/paginating to\n   * reach it. Unlike the sync `getRowByIndex` (render-window position), this resolves the true\n   * data-model row `index` on virtualized tables.\n   *\n   * Reaches the row via, in order: a currently-mounted match, the viewport's random-access\n   * `scrollToRow` fast path, then advancing pages (on infinite-scroll tables a \"page\" is a\n   * scroll step) up to `maxPages`.\n   *\n   * Requires a `strategies.resolveRowIndex` to identify rows by logical index \u2014 throws if one\n   * is not configured. Also throws if the row cannot be reached (no silent wrong-row fallback).\n   *\n   * @param index 0-based logical/data-model row index\n   * @param options - `maxPages` bounds how far to scroll/paginate (defaults to config.maxPages)\n   */\n  findRowByIndex: (\n    index: number,\n    options?: { maxPages?: number }\n  ) => Promise<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   * Resolves the named column and scrolls it into view.\n   * Prefers `strategies.viewport.scrollToColumn` when configured; otherwise scrolls the\n   * header cell via Playwright `scrollIntoViewIfNeeded()`.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * Counts the number of rows, optionally filtered.\n   * Without arguments, counts all rows. With filters, counts only matching rows.\n   * Paginates when pagination is configured.\n   */\n  countRows: (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }) => 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   * @deprecated Use `mapColumn` (or `map`) instead. Will be removed in v7.0.0.\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: calls goToFirst (if configured), clears cache, re-inits headers, then calls onReset.\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   * Defaults to `concurrency: 'sequential'` (safe for clicks/fills). Pass\n   * `concurrency: 'parallel'` for read-only extraction, or `'synchronized'` when\n   * navigation must stay lock-step on virtualized grids.\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * // Default sequential \u2014 safe for UI interactions\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   * });\n   *\n   * @example\n   * // Read-only extraction \u2014 opt into parallel\n   * const emails = await table.map(\n   *   ({ row }) => row.getCell('Email').innerText(),\n   *   { concurrency: 'parallel' }\n   * );\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

@@ -8,16 +8,32 @@ exports.TYPE_CONTEXT = void 0;
  */
 exports.TYPE_CONTEXT = `
 /**
- * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.
+ * Selector used by strategies (e.g. pagination buttons, spinners): a CSS string resolved
+ * relative to the parent, or a function that receives the parent and returns a Locator.
  * @example
- * // String selector
- * rowSelector: 'tbody tr'
- * 
- * // Function selector
- * headerSelector: (root) => root.locator('[role="columnheader"]')
+ * nextButton: 'button.next'
+ * nextButton: (root) => root.getByRole('button', { name: 'Next' })
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
 
+/**
+ * Selector for \`headerSelector\`, \`rowSelector\`, and \`cellSelector\`: a CSS string resolved
+ * relative to the parent, or a function that receives the parent Locator (the table root for
+ * headers/rows, the row for cells) and returns a Locator.
+ *
+ * Some features evaluate selectors in the browser and need a CSS string. Given a function,
+ * the \`dataAttribute\` viewport strategy warns once and skips the step that needs the string.
+ * The MUI DataGrid viewport instead uses \`[data-rowindex]\` for row scrolling and ranges,
+ * and \`.MuiDataGrid-columnHeader\` for header scrolling. Its overscan filtering warns and
+ * includes every mounted row because it needs the configured row selector.
+ * @example
+ * rowSelector: 'tbody tr'
+ * rowSelector: (root) => root.getByRole('row').filter({ has: root.getByRole('cell') })
+ * // Headers rendered as a separate table outside the root:
+ * headerSelector: (root) => root.page().locator('#header-table th')
+ */
+export type TableSelector = string | ((parent: Locator) => Locator);
+
 /**
  * Return type for \`resolveRowIndex\`. A plain number gives the logical index only;
  * \`{ index, selector }\` additionally provides a CSS selector the library uses to
@@ -706,12 +722,16 @@ export interface TableStrategies {
 
 
 export interface TableConfig<T = any> {
-  /** Selector for the table headers */
-  headerSelector?: string | ((root: Locator) => Locator);
-  /** Selector for the table rows */
-  rowSelector?: string;
-  /** Selector for the cells within a row */
-  cellSelector?: string | ((row: Locator) => Locator);
+  /**
+   * Selector for the header cells, relative to the table root. Default \`'thead th'\`.
+   * Use a function to reach headers outside the root, e.g.
+   * \`(root) => root.page().locator('#header-table th')\`.
+   */
+  headerSelector?: TableSelector;
+  /** Selector for the rows, relative to the table root. Default \`'tbody tr'\`. */
+  rowSelector?: TableSelector;
+  /** Selector for the cells, relative to a row. Default \`'td'\`. */
+  cellSelector?: TableSelector;
   /**
    * Number of pages to scan for verification / iteration.
    * Defaults to \`1\` — set explicitly (e.g. \`maxPages: 5\`) when using a pagination
@@ -762,9 +782,9 @@ export interface TableConfig<T = any> {
  * @internal Resolved config after defaults are applied. Prefer {@link TableConfig} in public code.
  */
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
-  headerSelector: string | ((root: Locator) => Locator);
-  rowSelector: string;
-  cellSelector: string | ((row: Locator) => Locator);
+  headerSelector: TableSelector;
+  rowSelector: TableSelector;
+  cellSelector: TableSelector;
   maxPages: number;
   autoScroll: boolean;
   concurrency?: RowIterationMode;
@@ -817,7 +837,7 @@ export type RowIterationOptions = {
    * - 'parallel': Full parallel execution of both navigation and actions.
    * - 'synchronized': Parallel navigation (lock-step) with serial actions.
    * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.
-   * @default 'parallel' (for map), 'sequential' (for forEach/filter)
+   * @default config.concurrency, then 'sequential'
    */
   concurrency?: RowIterationMode;
   /**

package/dist/types.d.ts

@@ -1,15 +1,30 @@
 import type { Locator, Page } from '@playwright/test';
 import type { SmartRowArray } from './utils/smartRowArray';
 /**
- * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.
+ * Selector used by strategies (e.g. pagination buttons, spinners): a CSS string resolved
+ * relative to the parent, or a function that receives the parent and returns a Locator.
  * @example
- * // String selector
- * rowSelector: 'tbody tr'
- *
- * // Function selector
- * headerSelector: (root) => root.locator('[role="columnheader"]')
+ * nextButton: 'button.next'
+ * nextButton: (root) => root.getByRole('button', { name: 'Next' })
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
+/**
+ * Selector for `headerSelector`, `rowSelector`, and `cellSelector`: a CSS string resolved
+ * relative to the parent, or a function that receives the parent Locator (the table root for
+ * headers/rows, the row for cells) and returns a Locator.
+ *
+ * Some features evaluate selectors in the browser and need a CSS string. Given a function,
+ * the `dataAttribute` viewport strategy warns once and skips the step that needs the string.
+ * The MUI DataGrid viewport instead uses `[data-rowindex]` for row scrolling and ranges,
+ * and `.MuiDataGrid-columnHeader` for header scrolling. Its overscan filtering warns and
+ * includes every mounted row because it needs the configured row selector.
+ * @example
+ * rowSelector: 'tbody tr'
+ * rowSelector: (root) => root.getByRole('row').filter({ has: root.getByRole('cell') })
+ * // Headers rendered as a separate table outside the root:
+ * headerSelector: (root) => root.page().locator('#header-table th')
+ */
+export type TableSelector = string | ((parent: Locator) => Locator);
 /**
  * Return type for `resolveRowIndex`. A plain number gives the logical index only;
  * `{ index, selector }` additionally provides a CSS selector the library uses to
@@ -644,12 +659,16 @@ export interface TableStrategies {
     viewport?: ViewportStrategy;
 }
 export interface TableConfig<T = any> {
-    /** Selector for the table headers */
-    headerSelector?: string | ((root: Locator) => Locator);
-    /** Selector for the table rows */
-    rowSelector?: string;
-    /** Selector for the cells within a row */
-    cellSelector?: string | ((row: Locator) => Locator);
+    /**
+     * Selector for the header cells, relative to the table root. Default `'thead th'`.
+     * Use a function to reach headers outside the root, e.g.
+     * `(root) => root.page().locator('#header-table th')`.
+     */
+    headerSelector?: TableSelector;
+    /** Selector for the rows, relative to the table root. Default `'tbody tr'`. */
+    rowSelector?: TableSelector;
+    /** Selector for the cells, relative to a row. Default `'td'`. */
+    cellSelector?: TableSelector;
     /**
      * Number of pages to scan for verification / iteration.
      * Defaults to `1` — set explicitly (e.g. `maxPages: 5`) when using a pagination
@@ -701,9 +720,9 @@ export interface TableConfig<T = any> {
  * @internal Resolved config after defaults are applied. Prefer {@link TableConfig} in public code.
  */
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
-    headerSelector: string | ((root: Locator) => Locator);
-    rowSelector: string;
-    cellSelector: string | ((row: Locator) => Locator);
+    headerSelector: TableSelector;
+    rowSelector: TableSelector;
+    cellSelector: TableSelector;
     maxPages: number;
     autoScroll: boolean;
     concurrency?: RowIterationMode;
@@ -754,7 +773,7 @@ export type RowIterationOptions = {
      * - 'parallel': Full parallel execution of both navigation and actions.
      * - 'synchronized': Parallel navigation (lock-step) with serial actions.
      * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.
-     * @default 'parallel' (for map), 'sequential' (for forEach/filter)
+     * @default config.concurrency, then 'sequential'
      */
     concurrency?: RowIterationMode;
     /**

package/dist/useTable.js

@@ -34,6 +34,7 @@ const smartRowArray_1 = require("./utils/smartRowArray");
 const elementTracker_1 = require("./utils/elementTracker");
 const loadingWait_1 = require("./utils/loadingWait");
 const pageIndex_1 = require("./utils/pageIndex");
+const smartRowInternals_1 = require("./utils/smartRowInternals");
 // Helper to safely serialize objects containing functions for logging
 const safeStringify = (obj) => {
     try {
@@ -147,13 +148,14 @@ const useTable = (rootLocator, configOptions = {}) => {
     // Placeholder for the final table object
     let finalTable = null;
     // Helper factory
-    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier, rowSelector, renderWindowPosition = false) => {
-        const effectiveLocator = rowSelector
-            ? rootLocator.locator(rowSelector)
+    // healSelector: the per-row selector returned by resolveRowIndex (not config.rowSelector).
+    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier, healSelector, renderWindowPosition = false) => {
+        const effectiveLocator = healSelector
+            ? rootLocator.locator(healSelector)
             : rowLocator;
         const sr = (0, smartRow_1.default)(effectiveLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier, renderWindowPosition);
-        if (rowSelector)
-            sr._selfHealing = true;
+        if (healSelector)
+            (0, smartRowInternals_1.internals)(sr)._selfHealing = true;
         return sr;
     };
     const tableState = { currentPageIndex: 0, empty: false };

package/dist/utils/cssSelector.d.ts

@@ -0,0 +1,14 @@
+import type { TableSelector } from '../types';
+type SelectorKey = 'headerSelector' | 'rowSelector' | 'cellSelector';
+/** Viewport range meaning "can't measure": callers treat everything as possibly visible and verify in the DOM. */
+export declare const UNKNOWN_RANGE: {
+    first: number;
+    last: number;
+};
+/**
+ * Returns the configured selector when it is a CSS string. Features that run
+ * `querySelectorAll` in the browser can't use a function selector; for those this warns
+ * once per config + feature and returns `null` so the caller can skip that step.
+ */
+export declare function cssSelectorOrWarn(config: Partial<Record<SelectorKey, TableSelector>>, key: SelectorKey, feature: string): string | null;
+export {};

package/dist/utils/cssSelector.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_RANGE = void 0;
+exports.cssSelectorOrWarn = cssSelectorOrWarn;
+/** Viewport range meaning "can't measure": callers treat everything as possibly visible and verify in the DOM. */
+exports.UNKNOWN_RANGE = { first: 0, last: Number.POSITIVE_INFINITY };
+const warned = new WeakMap();
+/**
+ * Returns the configured selector when it is a CSS string. Features that run
+ * `querySelectorAll` in the browser can't use a function selector; for those this warns
+ * once per config + feature and returns `null` so the caller can skip that step.
+ */
+function cssSelectorOrWarn(config, key, feature) {
+    const selector = config[key];
+    if (typeof selector === 'string')
+        return selector;
+    if (selector === undefined)
+        return null;
+    let seen = warned.get(config);
+    if (!seen)
+        warned.set(config, (seen = new Set()));
+    const id = `${key}:${feature}`;
+    if (!seen.has(id)) {
+        seen.add(id);
+        console.warn(`[SmartTable] ${feature} needs ${key} to be a CSS string, but a function was configured — skipping it. Use a string ${key} to enable ${feature}.`);
+    }
+    return null;
+}

package/dist/utils/resolveCellLocator.d.ts

@@ -22,8 +22,8 @@ export declare function resolveCellLocator(args: {
  * `filter({ has })`. Using the rows collection or a document-rooted parent nests
  * the row selector and matches nothing.
  *
- * Without `getCellLocator`, keeps the historical page-scoped `cellSelector.nth(i)`
- * template that Playwright re-bases into each row.
+ * Without `getCellLocator`, resolves `cellSelector` against the same `:scope` row so a
+ * function `cellSelector` receives a Locator, and Playwright re-bases it into each row.
  */
 export declare function resolveCellLocatorForFilter(args: {
     config: FinalTableConfig;

package/dist/utils/resolveCellLocator.js

@@ -31,14 +31,14 @@ function resolveCellLocator(args) {
  * `filter({ has })`. Using the rows collection or a document-rooted parent nests
  * the row selector and matches nothing.
  *
- * Without `getCellLocator`, keeps the historical page-scoped `cellSelector.nth(i)`
- * template that Playwright re-bases into each row.
+ * Without `getCellLocator`, resolves `cellSelector` against the same `:scope` row so a
+ * function `cellSelector` receives a Locator, and Playwright re-bases it into each row.
  */
 function resolveCellLocatorForFilter(args) {
     var _a;
     const { config, resolve, page, root, columnName, columnIndex } = args;
+    const scopeRow = page.locator(':scope');
     if ((_a = config.strategies) === null || _a === void 0 ? void 0 : _a.getCellLocator) {
-        const scopeRow = page.locator(':scope');
         return config.strategies.getCellLocator({
             row: scopeRow,
             root: root !== null && root !== void 0 ? root : scopeRow,
@@ -48,5 +48,5 @@ function resolveCellLocatorForFilter(args) {
             config,
         });
     }
-    return resolve(config.cellSelector, page).nth(columnIndex);
+    return resolve(config.cellSelector, scopeRow).nth(columnIndex);
 }

package/dist/utils/smartRowInternals.d.ts

@@ -0,0 +1,14 @@
+import type { SmartRow } from '../types';
+import type { NavigationBarrier } from './navigationBarrier';
+/**
+ * Library-private state stored on SmartRow instances. Not part of the public `SmartRow` type.
+ */
+export interface SmartRowInternals {
+    /** Row re-resolves itself from the `resolveRowIndex` selector on every use (DOM recycling). */
+    _selfHealing?: boolean;
+    /** Row is being processed inside a batch (map/forEach/filter or findRows). */
+    _inBatch?: boolean;
+    /** Barrier coordinating column scrolls across rows in `synchronized` iteration. */
+    _barrier?: NavigationBarrier;
+}
+export declare function internals(row: SmartRow<any>): SmartRowInternals;

package/dist/utils/smartRowInternals.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.internals = internals;
+function internals(row) {
+    return row;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.22.0-next.0d452da",
+  "version": "6.22.0-next.28cae60",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",