@rickcedwhat/playwright-smart-table 6.7.7 → 6.7.8

package/dist/engine/rowFinder.js

@@ -55,6 +55,7 @@ class RowFinder {
             const allRows = [];
             const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
             let pagesScanned = 1;
+            this.log(`findRows: starting (maxPages=${effectiveMaxPages}, filters=${JSON.stringify(filtersRecord)})`);
             const tracker = new elementTracker_1.ElementTracker('findRows');
             try {
                 const collectMatches = () => __awaiter(this, void 0, void 0, function* () {
@@ -68,12 +69,17 @@ class RowFinder {
                     const newIndices = yield tracker.getUnseenIndices(rowLocators);
                     const currentRows = yield rowLocators.all();
                     const isRowLoading = (_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isRowLoading;
+                    let added = 0;
                     for (const idx of newIndices) {
                         const smartRow = this.makeSmartRow(currentRows[idx], map, allRows.length, this.tableState.currentPageIndex);
-                        if (isRowLoading && (yield isRowLoading(smartRow)))
+                        if (isRowLoading && (yield isRowLoading(smartRow))) {
+                            this.log(`findRows: page ${this.tableState.currentPageIndex} — row skipped (isRowLoading=true)`);
                             continue;
+                        }
                         allRows.push(smartRow);
+                        added++;
                     }
+                    this.log(`findRows: page ${this.tableState.currentPageIndex} — ${added} new match(es) (total: ${allRows.length})`);
                 });
                 // Scan first page
                 yield collectMatches();
@@ -93,20 +99,25 @@ class RowFinder {
                         paginationResult = yield this.config.strategies.pagination.goNext(context);
                     }
                     else {
+                        this.log(`findRows: no pagination primitive — stopping`);
                         break;
                     }
                     const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
-                    if (!didPaginate)
+                    if (!didPaginate) {
+                        this.log(`findRows: pagination returned false — end of data`);
                         break;
+                    }
                     const pagesJumped = typeof paginationResult === 'number' ? paginationResult : 1;
                     this.tableState.currentPageIndex += pagesJumped;
                     pagesScanned += pagesJumped;
+                    this.log(`findRows: advanced ${pagesJumped} page(s), now at page ${this.tableState.currentPageIndex}`);
                     yield collectMatches();
                 }
             }
             finally {
                 yield tracker.cleanup(this.rootLocator.page());
             }
+            this.log(`findRows: done — ${allRows.length} row(s) collected across ${pagesScanned} page(s)`);
             return (0, smartRowArray_1.createSmartRowArray)(allRows);
         });
     }

package/dist/engine/tableIteration.js

@@ -13,6 +13,10 @@ exports.runForEach = runForEach;
 exports.runMap = runMap;
 exports.runFilter = runFilter;
 const elementTracker_1 = require("../utils/elementTracker");
+const debugUtils_1 = require("../utils/debugUtils");
+function log(config, msg) {
+    (0, debugUtils_1.logDebug)(config, 'verbose', msg);
+}
 /**
  * Shared row-iteration loop used by forEach, map, and filter.
  */
@@ -26,27 +30,36 @@ function runForEach(env_1, callback_1) {
         const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
         const useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
         const tracker = new elementTracker_1.ElementTracker('forEach');
+        log(env.config, `forEach: starting (maxPages=${effectiveMaxPages}, parallel=${parallel}, dedupe=${!!dedupeStrategy})`);
         try {
             let rowIndex = 0;
             let stopped = false;
             let pagesScanned = 1;
-            const stop = () => { stopped = true; };
+            let totalProcessed = 0;
+            const stop = () => {
+                log(env.config, `forEach: stop() called — halting after current page`);
+                stopped = true;
+            };
             while (!stopped) {
                 const rowLocators = env.getRowLocators();
                 const newIndices = yield tracker.getUnseenIndices(rowLocators);
                 const pageRows = yield rowLocators.all();
                 const smartRows = newIndices.map((idx, i) => env.makeSmartRow(pageRows[idx], map, rowIndex + i));
+                log(env.config, `forEach: page ${pagesScanned} — ${newIndices.length} new row(s) found`);
                 if (parallel) {
                     yield Promise.all(smartRows.map((row) => __awaiter(this, void 0, void 0, function* () {
                         if (stopped)
                             return;
                         if (dedupeKeys && dedupeStrategy) {
                             const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
+                            if (dedupeKeys.has(key)) {
+                                log(env.config, `forEach: dedupe skip key="${key}"`);
                                 return;
+                            }
                             dedupeKeys.add(key);
                         }
                         yield callback({ row, rowIndex: row.rowIndex, stop });
+                        totalProcessed++;
                     })));
                 }
                 else {
@@ -55,20 +68,27 @@ function runForEach(env_1, callback_1) {
                             break;
                         if (dedupeKeys && dedupeStrategy) {
                             const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
+                            if (dedupeKeys.has(key)) {
+                                log(env.config, `forEach: dedupe skip key="${key}"`);
                                 continue;
+                            }
                             dedupeKeys.add(key);
                         }
                         yield callback({ row, rowIndex: row.rowIndex, stop });
+                        totalProcessed++;
                     }
                 }
                 rowIndex += smartRows.length;
                 if (stopped || pagesScanned >= effectiveMaxPages)
                     break;
-                if (!(yield env.advancePage(useBulk)))
+                log(env.config, `forEach: advancing to next page (${pagesScanned} → ${pagesScanned + 1})`);
+                if (!(yield env.advancePage(useBulk))) {
+                    log(env.config, `forEach: no more pages — done`);
                     break;
+                }
                 pagesScanned++;
             }
+            log(env.config, `forEach: complete — ${totalProcessed} row(s) processed across ${pagesScanned} page(s)`);
         }
         finally {
             yield tracker.cleanup(env.getPage());
@@ -88,24 +108,31 @@ function runMap(env_1, callback_1) {
         const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : true;
         const useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
         const tracker = new elementTracker_1.ElementTracker('map');
+        log(env.config, `map: starting (maxPages=${effectiveMaxPages}, parallel=${parallel}, dedupe=${!!dedupeStrategy})`);
         const results = [];
         const SKIP = Symbol('skip');
         try {
             let rowIndex = 0;
             let stopped = false;
             let pagesScanned = 1;
-            const stop = () => { stopped = true; };
+            const stop = () => {
+                log(env.config, `map: stop() called — halting after current page`);
+                stopped = true;
+            };
             while (!stopped) {
                 const rowLocators = env.getRowLocators();
                 const newIndices = yield tracker.getUnseenIndices(rowLocators);
                 const pageRows = yield rowLocators.all();
                 const smartRows = newIndices.map((idx, i) => env.makeSmartRow(pageRows[idx], map, rowIndex + i));
+                log(env.config, `map: scanning page ${pagesScanned} — ${newIndices.length} new row(s)`);
                 if (parallel) {
                     const pageResults = yield Promise.all(smartRows.map((row) => __awaiter(this, void 0, void 0, function* () {
                         if (dedupeKeys && dedupeStrategy) {
                             const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
+                            if (dedupeKeys.has(key)) {
+                                log(env.config, `map: dedupe skip key="${key}"`);
                                 return SKIP;
+                            }
                             dedupeKeys.add(key);
                         }
                         return callback({ row, rowIndex: row.rowIndex, stop });
@@ -121,8 +148,10 @@ function runMap(env_1, callback_1) {
                             break;
                         if (dedupeKeys && dedupeStrategy) {
                             const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
+                            if (dedupeKeys.has(key)) {
+                                log(env.config, `map: dedupe skip key="${key}"`);
                                 continue;
+                            }
                             dedupeKeys.add(key);
                         }
                         results.push(yield callback({ row, rowIndex: row.rowIndex, stop }));
@@ -131,10 +160,14 @@ function runMap(env_1, callback_1) {
                 rowIndex += smartRows.length;
                 if (stopped || pagesScanned >= effectiveMaxPages)
                     break;
-                if (!(yield env.advancePage(useBulk)))
+                log(env.config, `map: advancing to next page (${pagesScanned} → ${pagesScanned + 1})`);
+                if (!(yield env.advancePage(useBulk))) {
+                    log(env.config, `map: no more pages — done`);
                     break;
+                }
                 pagesScanned++;
             }
+            log(env.config, `map: complete — ${results.length} result(s) across ${pagesScanned} page(s)`);
         }
         finally {
             yield tracker.cleanup(env.getPage());
@@ -155,23 +188,30 @@ function runFilter(env_1, predicate_1) {
         const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
         const useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
         const tracker = new elementTracker_1.ElementTracker('filter');
+        log(env.config, `filter: starting (maxPages=${effectiveMaxPages}, parallel=${parallel}, dedupe=${!!dedupeStrategy})`);
         const matched = [];
         try {
             let rowIndex = 0;
             let stopped = false;
             let pagesScanned = 1;
-            const stop = () => { stopped = true; };
+            const stop = () => {
+                log(env.config, `filter: stop() called — halting after current page`);
+                stopped = true;
+            };
             while (!stopped) {
                 const rowLocators = env.getRowLocators();
                 const newIndices = yield tracker.getUnseenIndices(rowLocators);
                 const pageRows = yield rowLocators.all();
                 const smartRows = newIndices.map((idx, i) => env.makeSmartRow(pageRows[idx], map, rowIndex + i, pagesScanned - 1));
+                log(env.config, `filter: scanning page ${pagesScanned} — ${newIndices.length} new row(s)`);
                 if (parallel) {
                     const flags = yield Promise.all(smartRows.map((row) => __awaiter(this, void 0, void 0, function* () {
                         if (dedupeKeys && dedupeStrategy) {
                             const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
+                            if (dedupeKeys.has(key)) {
+                                log(env.config, `filter: dedupe skip key="${key}"`);
                                 return false;
+                            }
                             dedupeKeys.add(key);
                         }
                         return predicate({ row, rowIndex: row.rowIndex, stop });
@@ -185,8 +225,10 @@ function runFilter(env_1, predicate_1) {
                             break;
                         if (dedupeKeys && dedupeStrategy) {
                             const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
+                            if (dedupeKeys.has(key)) {
+                                log(env.config, `filter: dedupe skip key="${key}"`);
                                 continue;
+                            }
                             dedupeKeys.add(key);
                         }
                         if (yield predicate({ row, rowIndex: row.rowIndex, stop })) {
@@ -197,10 +239,14 @@ function runFilter(env_1, predicate_1) {
                 rowIndex += smartRows.length;
                 if (stopped || pagesScanned >= effectiveMaxPages)
                     break;
-                if (!(yield env.advancePage(useBulk)))
+                log(env.config, `filter: advancing to next page (${pagesScanned} → ${pagesScanned + 1})`);
+                if (!(yield env.advancePage(useBulk))) {
+                    log(env.config, `filter: no more pages — done`);
                     break;
+                }
                 pagesScanned++;
             }
+            log(env.config, `filter: complete — ${matched.length} match(es) across ${pagesScanned} page(s)`);
         }
         finally {
             yield tracker.cleanup(env.getPage());

package/dist/engine/tableMapper.js

@@ -73,7 +73,7 @@ class TableMapper {
                 }
                 catch (e) {
                     lastError = e;
-                    this.log(`Header mapping failed (retrying): ${e.message}`);
+                    this.log(`Header mapping failed. Attempt ${Math.floor((Date.now() - startTime) / 100)}: ${e.message}`);
                     yield new Promise(r => setTimeout(r, 100));
                 }
             }

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { useTable } from './useTable';
 export type { TableConfig, TableResult, SmartRow, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, } from './types';
 export { Strategies } from './strategies';
+export * as presets from './presets';
+/** @deprecated Use `presets` instead. Plugins will be removed in v7.0.0. */
 export { Plugins } from './plugins';

package/dist/index.js

@@ -1,10 +1,45 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Plugins = exports.Strategies = exports.useTable = void 0;
+exports.Plugins = exports.presets = exports.Strategies = exports.useTable = void 0;
 var useTable_1 = require("./useTable");
 Object.defineProperty(exports, "useTable", { enumerable: true, get: function () { return useTable_1.useTable; } });
 // Export namespace-like strategy collections
 var strategies_1 = require("./strategies");
 Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
+exports.presets = __importStar(require("./presets"));
+/** @deprecated Use `presets` instead. Plugins will be removed in v7.0.0. */
 var plugins_1 = require("./plugins");
 Object.defineProperty(exports, "Plugins", { enumerable: true, get: function () { return plugins_1.Plugins; } });

package/dist/plugins/index.d.ts

@@ -1,16 +1,65 @@
 /**
+ * @deprecated Use `presets` instead. Plugins will be removed in v7.0.0.
  * Presets for specific table/grid libraries. Each plugin exposes:
- * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Plugins.MUI, maxPages: 5 }).
- * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Plugins.MUI.Strategies }).
+ * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Presets.MUI, maxPages: 5 }).
+ * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Presets.MUI.Strategies }).
  */
 export declare const Plugins: {
-    RDG: Partial<import("..").TableConfig<any>> & {
-        Strategies: typeof import("./rdg").RDGStrategies;
+    /** @deprecated Use `presets.rdg` */
+    RDG: {
+        Strategies: import("../types").TableStrategies | undefined;
+        headerSelector?: string | ((root: import("playwright-core").Locator) => import("playwright-core").Locator) | undefined;
+        rowSelector?: string | undefined;
+        cellSelector?: string | ((row: import("playwright-core").Locator) => import("playwright-core").Locator) | undefined;
+        maxPages?: number | undefined;
+        headerTransformer?: ((args: {
+            text: string;
+            index: number;
+            locator: import("playwright-core").Locator;
+            seenHeaders: Set<string>;
+        }) => string | Promise<string>) | undefined;
+        autoScroll?: boolean | undefined;
+        debug?: import("..").DebugConfig | undefined;
+        onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
+        strategies?: import("../types").TableStrategies | undefined;
+        columnOverrides?: Partial<Record<string | number | symbol, import("../types").ColumnOverride<any>>> | undefined;
     };
-    Glide: Partial<import("..").TableConfig<any>> & {
-        Strategies: typeof import("./glide").GlideStrategies;
+    /** @deprecated Use `presets.glide` */
+    Glide: {
+        Strategies: import("../types").TableStrategies | undefined;
+        headerSelector?: string | ((root: import("playwright-core").Locator) => import("playwright-core").Locator) | undefined;
+        rowSelector?: string | undefined;
+        cellSelector?: string | ((row: import("playwright-core").Locator) => import("playwright-core").Locator) | undefined;
+        maxPages?: number | undefined;
+        headerTransformer?: ((args: {
+            text: string;
+            index: number;
+            locator: import("playwright-core").Locator;
+            seenHeaders: Set<string>;
+        }) => string | Promise<string>) | undefined;
+        autoScroll?: boolean | undefined;
+        debug?: import("..").DebugConfig | undefined;
+        onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
+        strategies?: import("../types").TableStrategies | undefined;
+        columnOverrides?: Partial<Record<string | number | symbol, import("../types").ColumnOverride<any>>> | undefined;
     };
-    MUI: Partial<import("..").TableConfig<any>> & {
-        Strategies: typeof import("./mui").MUIStrategies;
+    /** @deprecated Use `presets.muiDataGrid` */
+    MUI: {
+        Strategies: import("../types").TableStrategies | undefined;
+        headerSelector?: string | ((root: import("playwright-core").Locator) => import("playwright-core").Locator) | undefined;
+        rowSelector?: string | undefined;
+        cellSelector?: string | ((row: import("playwright-core").Locator) => import("playwright-core").Locator) | undefined;
+        maxPages?: number | undefined;
+        headerTransformer?: ((args: {
+            text: string;
+            index: number;
+            locator: import("playwright-core").Locator;
+            seenHeaders: Set<string>;
+        }) => string | Promise<string>) | undefined;
+        autoScroll?: boolean | undefined;
+        debug?: import("..").DebugConfig | undefined;
+        onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
+        strategies?: import("../types").TableStrategies | undefined;
+        columnOverrides?: Partial<Record<string | number | symbol, import("../types").ColumnOverride<any>>> | undefined;
     };
 };

package/dist/plugins/index.js

@@ -1,16 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Plugins = void 0;
-const rdg_1 = require("./rdg");
-const glide_1 = require("./glide");
-const mui_1 = require("./mui");
+const presets_1 = require("../presets");
 /**
+ * @deprecated Use `presets` instead. Plugins will be removed in v7.0.0.
  * Presets for specific table/grid libraries. Each plugin exposes:
- * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Plugins.MUI, maxPages: 5 }).
- * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Plugins.MUI.Strategies }).
+ * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Presets.MUI, maxPages: 5 }).
+ * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Presets.MUI.Strategies }).
  */
 exports.Plugins = {
-    RDG: rdg_1.RDG,
-    Glide: glide_1.Glide,
-    MUI: mui_1.MUI,
+    /** @deprecated Use `presets.rdg` */
+    RDG: Object.assign(Object.assign({}, presets_1.rdg), { Strategies: presets_1.rdg.strategies }),
+    /** @deprecated Use `presets.glide` */
+    Glide: Object.assign(Object.assign({}, presets_1.glide), { Strategies: presets_1.glide.strategies }),
+    /** @deprecated Use `presets.muiDataGrid` */
+    MUI: Object.assign(Object.assign({}, presets_1.muiDataGrid), { Strategies: presets_1.muiDataGrid.strategies }),
 };

package/dist/presets/index.d.ts

@@ -0,0 +1,3 @@
+export { muiTable, muiDataGrid } from './mui';
+export { RDG as rdg } from './rdg';
+export { Glide as glide } from './glide';

package/dist/presets/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.glide = exports.rdg = exports.muiDataGrid = exports.muiTable = void 0;
+var mui_1 = require("./mui");
+Object.defineProperty(exports, "muiTable", { enumerable: true, get: function () { return mui_1.muiTable; } });
+Object.defineProperty(exports, "muiDataGrid", { enumerable: true, get: function () { return mui_1.muiDataGrid; } });
+var rdg_1 = require("./rdg");
+Object.defineProperty(exports, "rdg", { enumerable: true, get: function () { return rdg_1.RDG; } });
+var glide_1 = require("./glide");
+Object.defineProperty(exports, "glide", { enumerable: true, get: function () { return glide_1.Glide; } });

package/dist/presets/mui.d.ts

@@ -0,0 +1,22 @@
+import { TableConfig } from '../types';
+/**
+ * Preset configuration for the standard Material UI `<Table />` component.
+ *
+ * Handles:
+ * - Selectors for `.MuiTableRow-root`, `.MuiTableCell-head`, etc.
+ * - Pagination via the standard `.MuiTablePagination-actions` footer.
+ * - Sorting via the `.MuiTableSortLabel-root` header classes.
+ * - Virtualized DOM deduplication (falls back to cell text if unvirtualized).
+ */
+export declare const muiTable: Partial<TableConfig>;
+/**
+ * Preset configuration for the MUI DataGrid component (@mui/x-data-grid).
+ *
+ * Handles:
+ * - Selectors for `.MuiDataGrid-row`, `.MuiDataGrid-cell`, and `.MuiDataGrid-columnHeader`.
+ * - Pagination via the `.MuiDataGrid-footerContainer` (handling React's async rendering).
+ * - Sorting via `aria-sort` on column headers.
+ * - Vertical Virtualization deduplication using `data-rowindex`.
+ * - Horizontal Virtualization support via `aria-colindex`.
+ */
+export declare const muiDataGrid: Partial<TableConfig>;

package/dist/presets/mui.js

@@ -0,0 +1,266 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.muiDataGrid = exports.muiTable = void 0;
+/**
+ * Safely wait for MUI pagination to stabilize.
+ * Polls for displayed row text changes and waits for loading overlays to disappear.
+ */
+function waitForMuiPaginationStabilization(context, displayedRows, oldText) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        let retries = 50; // 5 second timeout for client-side render
+        while (oldText && retries-- > 0 && (yield displayedRows.innerText().catch(() => '')) === oldText) {
+            yield context.page.waitForTimeout(100);
+        }
+        // Standard MUI loading strategy check
+        if ((_a = context.config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isTableLoading) {
+            let loadingRetries = 30;
+            while (loadingRetries-- > 0 && (yield context.config.strategies.loading.isTableLoading(context))) {
+                yield context.page.waitForTimeout(100);
+            }
+        }
+        // DataGrid specific fallback (if not using loading strategy)
+        const overlay = context.root.locator('.MuiDataGrid-overlay');
+        if ((yield overlay.count()) > 0) {
+            let loadingRetries = 30;
+            while (loadingRetries-- > 0 && (yield overlay.isVisible().catch(() => false))) {
+                yield context.page.waitForTimeout(100);
+            }
+        }
+    });
+}
+/** safely locate the pagination container related to our table context */
+function getPaginationRoot(context) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // 1. If the user initialized useTable on the layout wrapper itself
+        const inside = context.root.locator('.MuiTablePagination-root').first();
+        if ((yield inside.count()) > 0)
+            return inside;
+        // 2. If the user initialized on the Table, look up to the closest Paper wrapper
+        const paper = context.root.locator('xpath=ancestor::*[contains(@class, "MuiPaper-root")][1]').first();
+        if ((yield paper.count()) > 0) {
+            const inPaper = paper.locator('.MuiTablePagination-root').first();
+            if ((yield inPaper.count()) > 0)
+                return inPaper;
+        }
+        // 3. Fallback: find the first pagination footer that follows this context in the DOM
+        return context.root.locator('xpath=following::div[contains(@class, "MuiTablePagination-root")][1]').first();
+    });
+}
+/**
+ * Preset configuration for the standard Material UI `<Table />` component.
+ *
+ * Handles:
+ * - Selectors for `.MuiTableRow-root`, `.MuiTableCell-head`, etc.
+ * - Pagination via the standard `.MuiTablePagination-actions` footer.
+ * - Sorting via the `.MuiTableSortLabel-root` header classes.
+ * - Virtualized DOM deduplication (falls back to cell text if unvirtualized).
+ */
+exports.muiTable = {
+    rowSelector: 'tbody tr, tbody .MuiTableRow-root',
+    cellSelector: 'td, th, .MuiTableCell-body',
+    headerSelector: 'thead th, .MuiTableCell-head',
+    headerTransformer: ({ text }) => text.replace(/\s*sorted\s+(a|de)scending/i, '').trim(),
+    strategies: {
+        pagination: {
+            goNext: (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const root = yield getPaginationRoot(context);
+                const nextBtn = root.locator('button[aria-label="Go to next page"]');
+                if ((yield nextBtn.count()) === 0 || (yield nextBtn.isDisabled()))
+                    return false;
+                const displayedRows = root.locator('.MuiTablePagination-displayedRows');
+                const oldText = yield displayedRows.innerText().catch(() => '');
+                // Force click ignores cookie banners obscuring the footer
+                yield nextBtn.click({ force: true });
+                yield waitForMuiPaginationStabilization(context, displayedRows, oldText);
+                return true;
+            }),
+            goPrevious: (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const root = yield getPaginationRoot(context);
+                const prevBtn = root.locator('button[aria-label="Go to previous page"]');
+                if ((yield prevBtn.count()) === 0 || (yield prevBtn.isDisabled()))
+                    return false;
+                const displayedRows = root.locator('.MuiTablePagination-displayedRows');
+                const oldText = yield displayedRows.innerText().catch(() => '');
+                yield prevBtn.click({ force: true });
+                yield waitForMuiPaginationStabilization(context, displayedRows, oldText);
+                return true;
+            }),
+            goToFirst: (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const root = yield getPaginationRoot(context);
+                const prevBtn = root.locator('button[aria-label="Go to previous page"]');
+                const displayedRows = root.locator('.MuiTablePagination-displayedRows');
+                let maxRetries = 50;
+                let clicked = false;
+                while (maxRetries-- > 0 && (yield prevBtn.count()) > 0 && !(yield prevBtn.isDisabled())) {
+                    const oldText = yield displayedRows.innerText().catch(() => '');
+                    yield prevBtn.click();
+                    yield waitForMuiPaginationStabilization(context, displayedRows, oldText);
+                    clicked = true;
+                }
+                return clicked;
+            })
+        },
+        sorting: {
+            getSortState: (_a) => __awaiter(void 0, [_a], void 0, function* ({ columnName, context }) {
+                if (!context.getHeaderCell)
+                    return 'none';
+                const header = yield context.getHeaderCell(columnName);
+                const sortLabel = header.locator('.MuiTableSortLabel-root').first();
+                if (!(yield sortLabel.isVisible().catch(() => false)))
+                    return 'none';
+                const className = (yield sortLabel.getAttribute('class')) || '';
+                if (className.includes('directionAsc'))
+                    return 'asc';
+                if (className.includes('directionDesc'))
+                    return 'desc';
+                // Often, if the label is active but lacks explicit direction classes, MUI defaults to ascending
+                if (className.includes('active'))
+                    return 'asc';
+                return 'none';
+            }),
+            doSort: (_a) => __awaiter(void 0, [_a], void 0, function* ({ columnName, direction, context }) {
+                var _b, _c;
+                if (!context.getHeaderCell)
+                    return;
+                const header = yield context.getHeaderCell(columnName);
+                const sortLabel = header.locator('.MuiTableSortLabel-root').first();
+                const target = (yield sortLabel.isVisible().catch(() => false)) ? sortLabel : header;
+                let current = (yield ((_b = context.config.strategies.sorting) === null || _b === void 0 ? void 0 : _b.getSortState({ columnName, context }))) || 'none';
+                let attempts = 0;
+                // Click until the state matches the target direction, max 3 times (none -> asc -> desc)
+                while (current !== direction && attempts < 3) {
+                    yield target.click();
+                    yield context.page.waitForTimeout(100);
+                    current = (yield ((_c = context.config.strategies.sorting) === null || _c === void 0 ? void 0 : _c.getSortState({ columnName, context }))) || 'none';
+                    attempts++;
+                }
+            })
+        },
+        dedupe: (row) => __awaiter(void 0, void 0, void 0, function* () {
+            // MUI virtualized tables attach data-index to rows 
+            const dataIndex = yield row.getAttribute('data-index');
+            if (dataIndex !== null)
+                return dataIndex;
+            // Unvirtualized tables don't recycle nodes, but if they do duplicate, fallback to first cell's text
+            const text = yield row.locator('td, th').first().innerText().catch(() => '');
+            return text || String(Math.random());
+        })
+    }
+};
+/**
+ * Preset configuration for the MUI DataGrid component (@mui/x-data-grid).
+ *
+ * Handles:
+ * - Selectors for `.MuiDataGrid-row`, `.MuiDataGrid-cell`, and `.MuiDataGrid-columnHeader`.
+ * - Pagination via the `.MuiDataGrid-footerContainer` (handling React's async rendering).
+ * - Sorting via `aria-sort` on column headers.
+ * - Vertical Virtualization deduplication using `data-rowindex`.
+ * - Horizontal Virtualization support via `aria-colindex`.
+ */
+exports.muiDataGrid = {
+    rowSelector: '.MuiDataGrid-row',
+    cellSelector: '.MuiDataGrid-cell',
+    headerSelector: '.MuiDataGrid-columnHeader',
+    strategies: {
+        pagination: {
+            goNext: (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const footer = context.root.locator('.MuiDataGrid-footerContainer');
+                const nextBtn = footer.locator('button[aria-label="Go to next page"]');
+                try {
+                    yield nextBtn.waitFor({ state: 'visible', timeout: 2000 });
+                }
+                catch (e) {
+                    return false;
+                }
+                if (yield nextBtn.isDisabled())
+                    return false;
+                const displayedRows = footer.locator('.MuiTablePagination-displayedRows');
+                const oldText = yield displayedRows.innerText().catch(() => '');
+                yield nextBtn.scrollIntoViewIfNeeded().catch(() => { });
+                yield nextBtn.click({ force: true });
+                yield waitForMuiPaginationStabilization(context, displayedRows, oldText);
+                return true;
+            }),
+            goPrevious: (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const footer = context.root.locator('.MuiDataGrid-footerContainer');
+                const prevBtn = footer.locator('button[aria-label="Go to previous page"]');
+                try {
+                    yield prevBtn.waitFor({ state: 'visible', timeout: 2000 });
+                }
+                catch (e) {
+                    return false;
+                }
+                if (yield prevBtn.isDisabled())
+                    return false;
+                const displayedRows = footer.locator('.MuiTablePagination-displayedRows');
+                const oldText = yield displayedRows.innerText().catch(() => '');
+                yield prevBtn.scrollIntoViewIfNeeded().catch(() => { });
+                yield prevBtn.click({ force: true });
+                yield waitForMuiPaginationStabilization(context, displayedRows, oldText);
+                return true;
+            })
+        },
+        sorting: {
+            getSortState: (_a) => __awaiter(void 0, [_a], void 0, function* ({ columnName, context }) {
+                if (!context.getHeaderCell)
+                    return 'none';
+                const header = yield context.getHeaderCell(columnName);
+                const sortAttr = yield header.getAttribute('aria-sort');
+                if (sortAttr === 'ascending')
+                    return 'asc';
+                if (sortAttr === 'descending')
+                    return 'desc';
+                return 'none';
+            }),
+            doSort: (_a) => __awaiter(void 0, [_a], void 0, function* ({ columnName, direction, context }) {
+                var _b, _c;
+                if (!context.getHeaderCell)
+                    return;
+                const header = yield context.getHeaderCell(columnName);
+                let current = (yield ((_b = context.config.strategies.sorting) === null || _b === void 0 ? void 0 : _b.getSortState({ columnName, context }))) || 'none';
+                let attempts = 0;
+                while (current !== direction && attempts < 3) {
+                    const clickTarget = header.locator('.MuiDataGrid-columnHeaderTitleContainer').first();
+                    if (yield clickTarget.isVisible()) {
+                        yield clickTarget.click({ force: true });
+                    }
+                    else {
+                        yield header.click({ force: true });
+                    }
+                    // Sorting can trigger large re-renders/virtualization shifts
+                    yield context.page.waitForTimeout(500);
+                    // Wait for stabilization (using DataGrid specific overlay check inside helper)
+                    const displayedRows = context.root.locator('.MuiTablePagination-displayedRows');
+                    const text = yield displayedRows.innerText().catch(() => '');
+                    yield waitForMuiPaginationStabilization(context, displayedRows, text);
+                    current = (yield ((_c = context.config.strategies.sorting) === null || _c === void 0 ? void 0 : _c.getSortState({ columnName, context }))) || 'none';
+                    attempts++;
+                }
+            })
+        },
+        dedupe: (row) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            // DataGrid uses data-rowindex for its own virtualization management
+            return (_a = (yield row.getAttribute('data-rowindex').catch(() => null))) !== null && _a !== void 0 ? _a : '';
+        }),
+        getCellLocator: ({ row, columnIndex }) => {
+            // Horizontal virtualization uses aria-colindex (1-indexed)
+            return row.locator(`[aria-colindex="${columnIndex + 1}"]`);
+        },
+        loading: {
+            isTableLoading: (context) => __awaiter(void 0, void 0, void 0, function* () {
+                return yield context.root.locator('.MuiDataGrid-overlay').isVisible().catch(() => false);
+            })
+        }
+    }
+};

package/dist/{plugins/rdg/index.d.ts → presets/rdg.d.ts}

@@ -1,4 +1,4 @@
-import { TableContext, TableConfig } from '../../types';
+import { TableContext, TableConfig } from '../types';
 /** Full strategies for React Data Grid. Use when you want to supply your own selectors: strategies: Plugins.RDG.Strategies */
 export declare const RDGStrategies: {
     header: (context: TableContext) => Promise<string[]>;
@@ -10,7 +10,7 @@ export declare const RDGStrategies: {
         goUp: ({ root, page }: any) => Promise<void>;
         goHome: ({ root, page }: any) => Promise<void>;
     };
-    pagination: import("../../types").PaginationPrimitives;
+    pagination: import("../types").PaginationPrimitives;
 };
 export declare const RDG: Partial<TableConfig> & {
     Strategies: typeof RDGStrategies;

package/dist/{plugins/rdg/index.js → presets/rdg.js}

@@ -10,8 +10,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RDG = exports.RDGStrategies = void 0;
-const pagination_1 = require("../../strategies/pagination");
-const stabilization_1 = require("../../strategies/stabilization");
+const pagination_1 = require("../strategies/pagination");
+const stabilization_1 = require("../strategies/stabilization");
 /**
  * Scrolls the grid horizontally to collect all column headers.
  * Handles empty headers by labeling them (e.g. "Checkbox").

package/dist/smartRow.js

@@ -32,7 +32,7 @@ const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function*
         });
         // Optimization: Check if we are ALREADY at the target cell
         if (activeCell && activeCell.rowIndex === rowIndex && activeCell.columnIndex === index) {
-            // Skip navigation - we're already there!
+            (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: Already at target cell {row: ${rowIndex}, col: ${index}}`);
             return activeCell.locator;
         }
     }
@@ -61,18 +61,22 @@ const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function*
         // Navigate vertically
         for (let i = 0; i < Math.abs(rowDiff); i++) {
             if (rowDiff > 0 && nav.goDown) {
+                (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving down');
                 yield nav.goDown(context);
             }
             else if (rowDiff < 0 && nav.goUp) {
+                (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving up');
                 yield nav.goUp(context);
             }
         }
         // Navigate horizontally
         for (let i = 0; i < Math.abs(colDiff); i++) {
             if (colDiff > 0 && nav.goRight) {
+                (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving right');
                 yield nav.goRight(context);
             }
             else if (colDiff < 0 && nav.goLeft) {
+                (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving left');
                 yield nav.goLeft(context);
             }
         }

package/dist/strategies/headers.d.ts

@@ -10,4 +10,13 @@ export declare const HeaderStrategies: {
      * This is fast but won't find virtualized columns off-screen.
      */
     visible: ({ config, resolve, root }: StrategyContext) => Promise<string[]>;
+    /**
+     * Physically scrolls the table horizontally to force virtualized columns to mount,
+     * collecting their names along the way.
+     */
+    horizontalScroll: (options?: {
+        limit?: number;
+        selector?: string;
+        scrollAmount?: number;
+    }) => HeaderStrategy;
 };

package/dist/strategies/headers.js

@@ -26,5 +26,64 @@ exports.HeaderStrategies = {
         }
         const texts = yield headerLoc.allInnerTexts();
         return texts.map(t => t.trim());
-    })
+    }),
+    /**
+     * Physically scrolls the table horizontally to force virtualized columns to mount,
+     * collecting their names along the way.
+     */
+    horizontalScroll: (options) => {
+        return (context) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b;
+            const { resolve, config, root, page } = context;
+            const limit = (_a = options === null || options === void 0 ? void 0 : options.limit) !== null && _a !== void 0 ? _a : 20;
+            const scrollAmount = (_b = options === null || options === void 0 ? void 0 : options.scrollAmount) !== null && _b !== void 0 ? _b : 300;
+            const collectedHeaders = new Set();
+            const getVisible = () => __awaiter(void 0, void 0, void 0, function* () {
+                const headerLoc = resolve(config.headerSelector, root);
+                const texts = yield headerLoc.allInnerTexts();
+                return texts.map(t => t.trim());
+            });
+            let currentHeaders = yield getVisible();
+            currentHeaders.forEach(h => collectedHeaders.add(h));
+            const scrollerHandle = yield root.evaluateHandle((el, selector) => {
+                if (selector && el.matches(selector))
+                    return el;
+                // Try finding common scrollable containers or fallback to root
+                const effectiveSelector = selector || '.dvn-scroller, .rdg-viewport, [role="grid"]';
+                const ancestor = el.closest(effectiveSelector);
+                if (ancestor)
+                    return ancestor;
+                const child = el.querySelector(effectiveSelector);
+                if (child)
+                    return child;
+                return el;
+            }, options === null || options === void 0 ? void 0 : options.selector);
+            const isScrollerFound = yield scrollerHandle.evaluate(el => !!el);
+            if (isScrollerFound) {
+                yield scrollerHandle.evaluate(el => el.scrollLeft = 0);
+                yield page.waitForTimeout(200);
+                for (let i = 0; i < limit; i++) {
+                    const sizeBefore = collectedHeaders.size;
+                    yield scrollerHandle.evaluate((el, amount) => el.scrollLeft += amount, scrollAmount);
+                    yield page.waitForTimeout(300);
+                    const newHeaders = yield getVisible();
+                    newHeaders.forEach(h => collectedHeaders.add(h));
+                    if (collectedHeaders.size === sizeBefore) {
+                        yield scrollerHandle.evaluate((el, amount) => el.scrollLeft += amount, scrollAmount);
+                        yield page.waitForTimeout(300);
+                        const retryHeaders = yield getVisible();
+                        retryHeaders.forEach(h => collectedHeaders.add(h));
+                        if (collectedHeaders.size === sizeBefore)
+                            break;
+                    }
+                }
+            }
+            else {
+                console.warn("HeaderStrategies.horizontalScroll: Could not find scroller. Returning visible headers.");
+            }
+            yield scrollerHandle.evaluate(el => el.scrollLeft = 0);
+            yield page.waitForTimeout(200);
+            return Array.from(collectedHeaders);
+        });
+    }
 };

package/dist/strategies/index.d.ts

@@ -38,6 +38,11 @@ export declare const Strategies: {
     };
     Header: {
         visible: ({ config, resolve, root }: import("..").StrategyContext) => Promise<string[]>;
+        horizontalScroll: (options?: {
+            limit?: number;
+            selector?: string;
+            scrollAmount?: number;
+        }) => import("./headers").HeaderStrategy;
     };
     Fill: {
         default: ({ row, columnName, value, fillOptions, config, table }: Parameters<import("../types").FillStrategy>[0]) => Promise<void>;

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 * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in toJSON (and columnOverrides.read).\n * Use this to scroll off-screen columns into view in horizontally virtualized tables,\n * wait for lazy-rendered content, or perform any pre-read setup.\n *\n * @example\n * // Scroll the column header into view to trigger horizontal virtualization render\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded();\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/**\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 Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /**\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\nexport type PaginationStrategy = PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell.\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\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/**\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\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n\n  /**\n   * Unified interface for reading and writing data to specific columns.\n   * Overrides both default extraction (toJSON) and filling (smartFill) logic.\n   */\n  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;\n}\n\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: string | ((root: Locator) => Locator);\n  rowSelector: string;\n  cellSelector: string | ((row: Locator) => Locator);\n  maxPages: number;\n  autoScroll: boolean;\n  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  rowIndex: number;\n  stop: () => void;\n};\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   * Whether to process rows within a page concurrently.\n   * @default false for forEach/filter, true for map\n   */\n  parallel?: boolean;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n  /**\n   * When true, use goNextBulk (if present) to advance pages during iteration.\n   * @default false \u2014 uses goNext for one-page-at-a-time advancement\n   */\n  useBulkPagination?: boolean;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.\n   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 0-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 0-based row index\n   */\n  getRowByIndex: (\n    index: number\n  ) => SmartRow;\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>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match (omit or pass {} for all rows)\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters?: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `parallel: true`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `{ parallel: false }` to avoid concurrent\n   * > interactions interfering with each other.\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 must use parallel: false\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   * }, { parallel: false });\n   */\n  map<R>(\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   * @example\n   * const active = await table.filter(async ({ row }) =>\n   *   await row.getCell('Status').innerText() === 'Active'\n   * );\n   */\n  filter(\n    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,\n    options?: RowIterationOptions\n  ): Promise<SmartRowArray<T>>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   * Automatically throws an Error containing the prompt.\n   */\n  generateConfig: () => Promise<void>;\n\n  /**\n   * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.\n   */\n  generateConfigPrompt: () => Promise<void>;\n}\n";
+export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in toJSON (and columnOverrides.read).\n * Use this to scroll off-screen columns into view in horizontally virtualized tables,\n * wait for lazy-rendered content, or perform any pre-read setup.\n *\n * @example\n * // Scroll the column header into view to trigger horizontal virtualization render\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded();\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/**\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 Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /**\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\nexport type PaginationStrategy = PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell.\n   * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\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/**\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\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n\n  /**\n   * Unified interface for reading and writing data to specific columns.\n   * Overrides both default extraction (toJSON) and filling (smartFill) logic.\n   */\n  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;\n}\n\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: string | ((root: Locator) => Locator);\n  rowSelector: string;\n  cellSelector: string | ((row: Locator) => Locator);\n  maxPages: number;\n  autoScroll: boolean;\n  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  rowIndex: number;\n  stop: () => void;\n};\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   * Whether to process rows within a page concurrently.\n   * @default false for forEach/filter, true for map\n   */\n  parallel?: boolean;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n  /**\n   * When true, use goNextBulk (if present) to advance pages during iteration.\n   * @default false \u2014 uses goNext for one-page-at-a-time advancement\n   */\n  useBulkPagination?: boolean;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.\n   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 0-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 0-based row index\n   */\n  getRowByIndex: (\n    index: number\n  ) => SmartRow;\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>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match (omit or pass {} for all rows)\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters?: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `parallel: true`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `{ parallel: false }` to avoid concurrent\n   * > interactions interfering with each other.\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 must use parallel: false\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   * }, { parallel: false });\n   */\n  map<R>(\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   * @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

@@ -275,6 +275,7 @@ export type FillStrategy = (options: {
 export interface ColumnOverride<TValue = any> {
   /** 
    * How to extract the value from the cell.
+   * \`context\` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.
    */
   read?: (cell: Locator) => Promise<TValue> | TValue;
 

package/dist/types.d.ts

@@ -238,6 +238,7 @@ export type FillStrategy = (options: {
 export interface ColumnOverride<TValue = any> {
     /**
      * How to extract the value from the cell.
+     * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.
      */
     read?: (cell: Locator) => Promise<TValue> | TValue;
     /**

package/dist/useTable.js

@@ -137,19 +137,31 @@ const useTable = (rootLocator, configOptions = {}) => {
         const context = createStrategyContext();
         const pagination = config.strategies.pagination;
         let rawResult;
+        let primitive;
         if (useBulk && (pagination === null || pagination === void 0 ? void 0 : pagination.goNextBulk)) {
+            primitive = 'goNextBulk';
             rawResult = yield pagination.goNextBulk(context);
         }
         else if (pagination === null || pagination === void 0 ? void 0 : pagination.goNext) {
+            primitive = 'goNext';
             rawResult = yield pagination.goNext(context);
         }
         else if (pagination === null || pagination === void 0 ? void 0 : pagination.goNextBulk) {
+            primitive = 'goNextBulk (fallback)';
             rawResult = yield pagination.goNextBulk(context);
         }
+        else {
+            log('_advancePage: no pagination primitive available — returning false');
+            return false;
+        }
         const didAdvance = rawResult !== undefined && (0, validation_1.validatePaginationResult)(rawResult, 'Pagination Strategy');
         const pagesJumped = typeof rawResult === 'number' ? rawResult : (didAdvance ? 1 : 0);
         if (pagesJumped > 0) {
             tableState.currentPageIndex += pagesJumped;
+            log(`_advancePage: ${primitive} advanced ${pagesJumped} page(s) — now at page ${tableState.currentPageIndex}`);
+        }
+        else {
+            log(`_advancePage: ${primitive} returned false — end of data`);
         }
         return didAdvance;
     });
@@ -211,7 +223,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         getRow: (filters, options = { exact: false }) => {
             const map = tableMapper.getMapSync();
             if (!map)
-                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.findRows() which auto-initialize.');
+                throw new Error('Initialization Error: You attempted to access a row before the table structure was mapped. Please call "await table.init()" once before using synchronous row access.');
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = filterEngine.applyFilters(allRows, filters, map, options.exact || false, rootLocator.page(), rootLocator);
             const rowLocator = matchedRows.first();
@@ -220,7 +232,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         getRowByIndex: (index) => {
             const map = tableMapper.getMapSync();
             if (!map)
-                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.findRows() which auto-initialize.');
+                throw new Error('Initialization Error: You attempted to access a row before the table structure was mapped. Please call "await table.init()" once before using synchronous row access.');
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(index);
             return _makeSmart(rowLocator, map, index);
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.7.7",
+  "version": "6.7.8",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -29,11 +29,28 @@
     "test": "npm run test:unit && npx playwright test",
     "test:unit": "vitest run --coverage --reporter=verbose --reporter=html",
     "test:unit:ui": "vitest --ui",
+    "test:mutate": "npx stryker run",
     "pretest:e2e": "npm run clean-port",
     "posttest:e2e": "npm run clean-port",
     "test:e2e": "npx playwright test",
+    "dev:playground": "cd playground && npm run dev",
+    "dev:mui": "cd tests/apps/mui-datagrid && npm run dev",
     "prepare": "husky install"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./presets": {
+      "types": "./dist/presets/index.d.ts",
+      "default": "./dist/presets/index.js"
+    },
+    "./presets/mui": {
+      "types": "./dist/presets/mui.d.ts",
+      "default": "./dist/presets/mui.js"
+    }
+  },
   "keywords": [
     "playwright",
     "testing",
@@ -44,14 +61,16 @@
     "@playwright/test": "^1.40.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.49.1",
-    "@types/node": "^22.10.5",
-    "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/ui": "^4.0.18",
-    "happy-dom": "^20.6.1",
+    "@playwright/test": "^1.58.2",
+    "@stryker-mutator/core": "^9.6.0",
+    "@stryker-mutator/vitest-runner": "^9.6.0",
+    "@types/node": "^25.3.5",
+    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/ui": "^4.1.0",
+    "happy-dom": "^20.8.3",
     "husky": "^9.1.7",
     "typescript": "^5.7.2",
     "vitepress": "^1.6.4",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }

package/dist/plugins/mui/index.d.ts

@@ -1,8 +0,0 @@
-import type { TableConfig } from '../../types';
-/** Full strategies for MUI Data Grid. Use when you want to supply your own selectors: strategies: Plugins.MUI.Strategies */
-export declare const MUIStrategies: {
-    pagination: import("../../types").PaginationPrimitives;
-};
-export declare const MUI: Partial<TableConfig> & {
-    Strategies: typeof MUIStrategies;
-};

package/dist/plugins/mui/index.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MUI = exports.MUIStrategies = void 0;
-const pagination_1 = require("../../strategies/pagination");
-/** Default strategies for the MUI preset (used when you spread Plugins.MUI). */
-const MUIDefaultStrategies = {
-    pagination: pagination_1.PaginationStrategies.click({
-        next: (root) => root.getByRole('button', { name: 'Go to next page' }),
-    }),
-};
-/** Full strategies for MUI Data Grid. Use when you want to supply your own selectors: strategies: Plugins.MUI.Strategies */
-exports.MUIStrategies = MUIDefaultStrategies;
-/**
- * Full preset for MUI Data Grid (selectors + headerTransformer + default strategies).
- * Spread: useTable(loc, { ...Plugins.MUI, maxPages: 5 }).
- * Strategies only: useTable(loc, { rowSelector: '...', strategies: Plugins.MUI.Strategies }).
- */
-const MUIPreset = {
-    rowSelector: '.MuiDataGrid-row',
-    headerSelector: '.MuiDataGrid-columnHeader',
-    cellSelector: '.MuiDataGrid-cell',
-    headerTransformer: ({ text }) => (text.includes('__col_') ? 'Actions' : text),
-    strategies: MUIDefaultStrategies,
-};
-exports.MUI = Object.defineProperty(MUIPreset, 'Strategies', { get: () => exports.MUIStrategies, enumerable: false });