@rickcedwhat/playwright-smart-table 6.7.0 → 6.7.1

package/README.md

@@ -128,6 +128,32 @@ const expensive = await table.filter(async ({ row }) => {
 });
 ```
 
+### Advanced: `columnOverrides`
+
+For complex DOM structures, custom data extraction, or specialized input widgets, use `columnOverrides` to intercept how Smart Table interacts with specific columns:
+
+```typescript
+const table = useTable(page.locator('#table'), {
+  columnOverrides: {
+    // Override how data is read from the 'Status' column (e.g., for .toJSON())
+    Status: {
+      read: async (cell) => {
+        const isChecked = await cell.locator('input[type="checkbox"]').isChecked();
+        return isChecked ? 'Active' : 'Inactive';
+      }
+    },
+    // Override how data is written to the 'Tags' column (for .smartFill())
+    Tags: {
+      write: async (cell, value) => {
+        await cell.click();
+        await page.keyboard.type(value);
+        await page.keyboard.press('Enter');
+      }
+    }
+  }
+});
+```
+
 ## Key Features
 
 - 🎯 **Smart Locators** - Find rows by content, not position

package/dist/engine/rowFinder.d.ts

@@ -19,10 +19,7 @@ export declare class RowFinder<T = any> {
         exact?: boolean;
         maxPages?: number;
     }): Promise<SmartRow<T>>;
-    findRows(filtersOrOptions?: (Partial<T> | Record<string, FilterValue>) & ({
-        exact?: boolean;
-        maxPages?: number;
-    }), legacyOptions?: {
+    findRows(filters?: Partial<T> | Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
     }): Promise<SmartRowArray<T>>;

package/dist/engine/rowFinder.js

@@ -8,17 +8,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RowFinder = void 0;
 const debugUtils_1 = require("../utils/debugUtils");
@@ -51,46 +40,26 @@ class RowFinder {
             yield (0, debugUtils_1.debugDelay)(this.config, 'findRow');
             const sentinel = this.resolve(this.config.rowSelector, this.rootLocator)
                 .filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
-            return this.makeSmartRow(sentinel, yield this.tableMapper.getMap(), 0);
+            const smartRow = this.makeSmartRow(sentinel, yield this.tableMapper.getMap(), 0);
+            smartRow._isSentinel = true;
+            return smartRow;
         });
     }
-    findRows(filtersOrOptions, 
-    // Deprecated: verify legacy usage pattern support
-    legacyOptions) {
+    findRows(filters, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Detect argument pattern:
-            // Pattern A: findRows({ Name: 'Alice' }, { maxPages: 5 })
-            // Pattern B: findRows({ maxPages: 5 })  <-- No filters, just options
-            // Pattern C: findRows({ Name: 'Alice' }) <-- Only filters
             var _a, _b;
-            let filters = {};
-            let options = {};
-            if (legacyOptions) {
-                // Pattern A
-                filters = filtersOrOptions;
-                options = legacyOptions;
-            }
-            else {
-                // Pattern B or C
-                // We need to separate unknown keys (filters) from known options (exact, maxPages)
-                // However, filtersOrOptions can be null/undefined
-                if (filtersOrOptions) {
-                    const _c = filtersOrOptions, { exact, maxPages } = _c, rest = __rest(_c, ["exact", "maxPages"]);
-                    options = { exact, maxPages };
-                    filters = rest;
-                }
-            }
+            const filtersRecord = filters || {};
             const map = yield this.tableMapper.getMap();
             const allRows = [];
-            const effectiveMaxPages = (_b = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
+            const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
             let pagesScanned = 1;
             const collectMatches = () => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b;
                 // ... logic ...
                 let rowLocators = this.resolve(this.config.rowSelector, this.rootLocator);
                 // Only apply filters if we have them
-                if (Object.keys(filters).length > 0) {
-                    rowLocators = this.filterEngine.applyFilters(rowLocators, filters, map, (_a = options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page());
+                if (Object.keys(filtersRecord).length > 0) {
+                    rowLocators = this.filterEngine.applyFilters(rowLocators, filtersRecord, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page());
                 }
                 const currentRows = yield rowLocators.all();
                 const isRowLoading = (_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isRowLoading;
@@ -125,7 +94,7 @@ class RowFinder {
                     }
                     paginationResult = yield this.config.strategies.pagination.goNext(context);
                 }
-                const didPaginate = yield (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
+                const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                 if (!didPaginate)
                     break;
                 this.tableState.currentPageIndex++;

package/dist/engine/tableMapper.js

@@ -105,7 +105,7 @@ class TableMapper {
                     text = yield this.config.headerTransformer({
                         text,
                         index: i,
-                        locator: this.rootLocator.locator(this.config.headerSelector).nth(i),
+                        locator: this.resolve(this.config.headerSelector, this.rootLocator).nth(i),
                         seenHeaders
                     });
                 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { useTable } from './useTable';
-export type { TableConfig, TableResult, SmartRow, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, } from './types';
+export type { TableConfig, TableResult, SmartRow, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, } from './types';
 export { Strategies } from './strategies';
 export { Plugins } from './plugins';

package/dist/plugins.d.ts

@@ -3,7 +3,6 @@ export declare const Plugins: {
         Strategies: {
             header: (context: import("./types").TableContext) => Promise<string[]>;
             getCellLocator: ({ row, columnIndex }: any) => any;
-            cellNavigation: ({ root, page, index }: any) => Promise<void>;
             navigation: {
                 goRight: ({ root, page }: any) => Promise<void>;
                 goLeft: ({ root, page }: any) => Promise<void>;

package/dist/smartRow.js

@@ -16,7 +16,6 @@ const debugUtils_1 = require("./utils/debugUtils");
 /**
  * Internal helper to navigate to a cell with active cell optimization.
  * Uses navigation primitives (goUp, goDown, goLeft, goRight, goHome) for orchestration.
- * Falls back to cellNavigation for backward compatibility.
  * Returns the target cell locator after navigation.
  */
 const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function* () {
@@ -91,7 +90,6 @@ const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function*
         }
         return null;
     }
-    ;
     return null;
 });
 /**
@@ -121,10 +119,23 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         }
         return resolve(config.cellSelector, rowLocator).nth(idx);
     };
+    smart.wasFound = () => {
+        return !smart._isSentinel;
+    };
     smart.toJSON = (options) => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
         const result = {};
         const page = rootLocator.page();
+        // Build a getHeaderCell helper for the beforeCellRead context.
+        // Uses the table reference if available, otherwise falls back to index-based lookup.
+        const getHeaderCell = (table === null || table === void 0 ? void 0 : table.getHeaderCell)
+            ? table.getHeaderCell.bind(table)
+            : (colName) => __awaiter(void 0, void 0, void 0, function* () {
+                const idx = map.get(colName);
+                if (idx === undefined)
+                    throw new Error(`Column "${colName}" not found`);
+                return resolve(config.headerSelector, rootLocator).nth(idx);
+            });
         for (const [col, idx] of map.entries()) {
             if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(col)) {
                 continue;
@@ -132,13 +143,6 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             // Check if we have a column override for this column
             const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col];
             const mapper = columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read;
-            if (mapper) {
-                // Use custom mapper
-                // Ensure we have the cell first (same navigation logic)
-                // ... wait, the navigation logic below assumes we need to navigate.
-                // If we have a mapper, we still need the cell locator.
-                // Let's reuse the navigation logic to get targetCell
-            }
             // --- Navigation Logic Start ---
             const cell = config.strategies.getCellLocator
                 ? config.strategies.getCellLocator({
@@ -168,6 +172,19 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 }
             }
             // --- Navigation Logic End ---
+            // Call beforeCellRead hook if configured.
+            // Fires for BOTH columnOverrides.read and the default innerText path.
+            if (config.strategies.beforeCellRead) {
+                yield config.strategies.beforeCellRead({
+                    cell: targetCell,
+                    columnName: col,
+                    columnIndex: idx,
+                    row: rowLocator,
+                    page,
+                    root: rootLocator,
+                    getHeaderCell,
+                });
+            }
             if (mapper) {
                 // Apply mapper
                 const mappedValue = yield mapper(targetCell);
@@ -182,6 +199,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         return result;
     });
     smart.smartFill = (data, fillOptions) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
         (0, debugUtils_1.logDebug)(config, 'info', 'Filling row', data);
         for (const [colName, value] of Object.entries(data)) {
             if (value === undefined)
@@ -200,19 +218,35 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 rowLocator,
                 rowIndex
             });
-            const strategy = config.strategies.fill || fill_1.FillStrategies.default;
-            (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);
-            yield strategy({
-                row: smart,
-                columnName: colName,
-                value,
-                index: rowIndex !== null && rowIndex !== void 0 ? rowIndex : -1,
-                page: rowLocator.page(),
-                rootLocator,
-                config,
-                table: table,
-                fillOptions
-            });
+            const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[colName];
+            if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) {
+                const cellLocator = smart.getCell(colName);
+                let currentValue;
+                if (columnOverride.read) {
+                    currentValue = yield columnOverride.read(cellLocator);
+                }
+                yield columnOverride.write({
+                    cell: cellLocator,
+                    targetValue: value,
+                    currentValue,
+                    row: smart
+                });
+            }
+            else {
+                const strategy = config.strategies.fill || fill_1.FillStrategies.default;
+                (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);
+                yield strategy({
+                    row: smart,
+                    columnName: colName,
+                    value,
+                    index: rowIndex !== null && rowIndex !== void 0 ? rowIndex : -1,
+                    page: rowLocator.page(),
+                    rootLocator,
+                    config,
+                    table: table,
+                    fillOptions
+                });
+            }
             // Delay after filling
             yield (0, debugUtils_1.debugDelay)(config, 'getCell');
         }

package/dist/strategies/index.d.ts

@@ -33,7 +33,7 @@ export declare const Strategies: {
         default: () => Promise<void>;
     };
     Header: {
-        visible: ({ config, resolve, root }: import("../types").StrategyContext) => Promise<string[]>;
+        visible: ({ config, resolve, root }: import("..").StrategyContext) => Promise<string[]>;
     };
     Fill: {
         default: ({ row, columnName, value, fillOptions, config, table }: Parameters<import("../types").FillStrategy>[0]) => Promise<void>;
@@ -46,8 +46,8 @@ export declare const Strategies: {
     };
     Loading: {
         Table: {
-            hasSpinner: (selector?: string) => ({ root }: import("../types").TableContext) => Promise<boolean>;
-            custom: (fn: (context: import("../types").TableContext) => Promise<boolean>) => (context: import("../types").TableContext) => Promise<boolean>;
+            hasSpinner: (selector?: string) => ({ root }: import("..").TableContext) => Promise<boolean>;
+            custom: (fn: (context: import("..").TableContext) => Promise<boolean>) => (context: import("..").TableContext) => Promise<boolean>;
             never: () => Promise<boolean>;
         };
         Row: {
@@ -57,7 +57,7 @@ export declare const Strategies: {
             never: () => Promise<boolean>;
         };
         Headers: {
-            stable: (duration?: number) => (context: import("../types").TableContext) => Promise<boolean>;
+            stable: (duration?: number) => (context: import("..").TableContext) => Promise<boolean>;
             never: () => Promise<boolean>;
         };
     };

package/dist/strategies/rdg.d.ts

@@ -9,10 +9,6 @@ export declare const scrollRightHeaderRDG: (context: TableContext) => Promise<st
  * changing during pagination/scrolling.
  */
 export declare const rdgGetCellLocator: ({ row, columnIndex }: any) => any;
-/**
- * Scrolls virtualized columns into view before reading.
- */
-export declare const rdgCellNavigation: ({ root, page, index }: any) => Promise<void>;
 /**
  * Scrolls the grid vertically to load more virtualized rows.
  */
@@ -27,7 +23,6 @@ export declare const rdgNavigation: {
 export declare const RDGStrategies: {
     header: (context: TableContext) => Promise<string[]>;
     getCellLocator: ({ row, columnIndex }: any) => any;
-    cellNavigation: ({ root, page, index }: any) => Promise<void>;
     navigation: {
         goRight: ({ root, page }: any) => Promise<void>;
         goLeft: ({ root, page }: any) => Promise<void>;

package/dist/strategies/rdg.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RDGStrategies = exports.rdgNavigation = exports.rdgPaginationStrategy = exports.rdgCellNavigation = exports.rdgGetCellLocator = exports.scrollRightHeaderRDG = void 0;
+exports.RDGStrategies = exports.rdgNavigation = exports.rdgPaginationStrategy = exports.rdgGetCellLocator = exports.scrollRightHeaderRDG = void 0;
 /**
  * Scrolls the grid horizontally to collect all column headers.
  * Handles empty headers by labeling them (e.g. "Checkbox").
@@ -64,22 +64,6 @@ const rdgGetCellLocator = ({ row, columnIndex }) => {
     return row.locator(`[role="gridcell"][aria-colindex="${ariaColIndex}"]`);
 };
 exports.rdgGetCellLocator = rdgGetCellLocator;
-/**
- * Scrolls virtualized columns into view before reading.
- */
-const rdgCellNavigation = (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, page, index }) {
-    // Check if the column header is visible and scroll horizontally if needed
-    const headerCell = root.locator(`[role="columnheader"][aria-colindex="${index + 1}"]`);
-    const isVisible = yield headerCell.isVisible().catch(() => false);
-    if (!isVisible) {
-        const estimatedScroll = index * 150;
-        yield root.evaluate((el, scrollAmount) => {
-            el.scrollLeft = scrollAmount;
-        }, estimatedScroll);
-        yield page.waitForTimeout(300);
-    }
-});
-exports.rdgCellNavigation = rdgCellNavigation;
 /**
  * Scrolls the grid vertically to load more virtualized rows.
  */
@@ -136,7 +120,6 @@ exports.rdgNavigation = {
 exports.RDGStrategies = {
     header: exports.scrollRightHeaderRDG,
     getCellLocator: exports.rdgGetCellLocator,
-    cellNavigation: exports.rdgCellNavigation,
     navigation: exports.rdgNavigation,
     pagination: exports.rdgPaginationStrategy
 };

package/dist/strategies/sorting.js

@@ -23,21 +23,16 @@ exports.SortingStrategies = {
         return {
             doSort(_a) {
                 return __awaiter(this, arguments, void 0, function* ({ columnName, direction, context }) {
-                    const { getHeaderCell } = context;
-                    if (!getHeaderCell)
-                        throw new Error('getHeaderCell is required in StrategyContext for sorting.');
+                    // getHeaderCell is always present on TableContext after table is initialized
+                    const targetHeader = yield context.getHeaderCell(columnName);
                     // The table engine handles verify-and-retry. We only provide the trigger here.
-                    const targetHeader = yield getHeaderCell(columnName);
                     yield targetHeader.click();
                 });
             },
             getSortState(_a) {
                 return __awaiter(this, arguments, void 0, function* ({ columnName, context }) {
-                    const { getHeaderCell } = context;
                     try {
-                        if (!getHeaderCell)
-                            throw new Error('getHeaderCell is required');
-                        const targetHeader = yield getHeaderCell(columnName);
+                        const targetHeader = yield context.getHeaderCell(columnName);
                         const ariaSort = yield targetHeader.getAttribute('aria-sort');
                         if (ariaSort === 'ascending')
                             return 'asc';
@@ -46,7 +41,7 @@ exports.SortingStrategies = {
                         return 'none';
                     }
                     catch (_b) {
-                        return 'none'; // Header not found, so it's not sorted
+                        return 'none'; // Header not found, treat as unsorted
                     }
                 });
             },

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.js
  * 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 * 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\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n  /** Helper to reliably get a header cell locator by name */\n  getHeaderCell?: (headerName: string) => Promise<Locator>;\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}\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 */\n  goNextBulk?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip backward multiple pages at once */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to specific page index (0-indexed) */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n}\n\nexport type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | 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. (Replaces dataMapper logic)\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.\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.\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  /** Custom helper to check if a table is fully loaded/ready */\n  isTableLoaded?: (args: TableContext) => Promise<boolean>;\n  /** Custom helper to check if a row is fully loaded/ready */\n  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;\n  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */\n  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;\n  /** Strategy for detecting loading states */\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;\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;\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\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   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\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\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  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 */\n  goNextBulk?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip backward multiple pages at once */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to specific page index (0-indexed) */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n}\n\nexport type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | 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.\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.\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   * 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  /** Custom helper to check if a table is fully loaded/ready */\n  isTableLoaded?: (args: TableContext) => Promise<boolean>;\n  /** Custom helper to check if a row is fully loaded/ready */\n  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;\n  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */\n  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;\n  /** Strategy for detecting loading states */\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;\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;\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\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   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\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\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  generateConfigPrompt: () => Promise<void>;\n}\n";

package/dist/typeContext.js

@@ -43,6 +43,32 @@ export type GetCellLocatorFn = (args: {
   page: Page;
 }) => Locator;
 
+/**
+ * Hook called before each cell value is read in toJSON (and columnOverrides.read).
+ * Use this to scroll off-screen columns into view in horizontally virtualized tables,
+ * wait for lazy-rendered content, or perform any pre-read setup.
+ *
+ * @example
+ * // Scroll the column header into view to trigger horizontal virtualization render
+ * strategies: {
+ *   beforeCellRead: async ({ columnName, getHeaderCell }) => {
+ *     const header = await getHeaderCell(columnName);
+ *     await header.scrollIntoViewIfNeeded();
+ *   }
+ * }
+ */
+export type BeforeCellReadFn = (args: {
+  /** The resolved cell locator */
+  cell: Locator;
+  columnName: string;
+  columnIndex: number;
+  row: Locator;
+  page: Page;
+  root: Locator;
+  /** Resolves a column name to its header cell locator */
+  getHeaderCell: (columnName: string) => Promise<Locator>;
+}) => Promise<void>;
+
 /**
  * Function to get the currently active/focused cell.
  * Returns null if no cell is active.
@@ -126,13 +152,16 @@ export type SmartRow<T = any> = Locator & {
    * );
    */
   smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
+
+  /**
+   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).
+   */
+  wasFound(): boolean;
 };
 
 export type StrategyContext = TableContext & {
   rowLocator?: Locator;
   rowIndex?: number;
-  /** Helper to reliably get a header cell locator by name */
-  getHeaderCell?: (headerName: string) => Promise<Locator>;
 };
 
 /**
@@ -187,6 +216,12 @@ export interface TableContext<T = any> {
   config: FinalTableConfig<T>;
   page: Page;
   resolve: (selector: Selector, parent: Locator | Page) => Locator;
+  /** Resolves a column name to its header cell locator. Available after table is initialized. */
+  getHeaderCell?: (columnName: string) => Promise<Locator>;
+  /** Returns all column names in order. Available after table is initialized. */
+  getHeaders?: () => Promise<string[]>;
+  /** Scrolls the table horizontally to bring the given column's header into view. */
+  scrollToColumn?: (columnName: string) => Promise<void>;
 }
 
 export interface PaginationPrimitives {
@@ -229,7 +264,7 @@ export type FillStrategy = (options: {
 
 export interface ColumnOverride<TValue = any> {
   /** 
-   * How to extract the value from the cell. (Replaces dataMapper logic)
+   * How to extract the value from the cell.
    */
   read?: (cell: Locator) => Promise<TValue> | TValue;
 
@@ -294,6 +329,12 @@ export interface TableStrategies {
   getCellLocator?: GetCellLocatorFn;
   /** Function to get the currently active/focused cell */
   getActiveCell?: GetActiveCellFn;
+  /**
+   * Hook called before each cell value is read in toJSON and columnOverrides.read.
+   * Fires for both the default innerText extraction and custom read mappers.
+   * Useful for scrolling off-screen columns into view in horizontally virtualized tables.
+   */
+  beforeCellRead?: BeforeCellReadFn;
   /** Custom helper to check if a table is fully loaded/ready */
   isTableLoaded?: (args: TableContext) => Promise<boolean>;
   /** Custom helper to check if a row is fully loaded/ready */
@@ -416,8 +457,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * @param options Optional settings including bringIntoView
    */
   getRowByIndex: (
-    index: number,
-    options?: { bringIntoView?: boolean }
+    index: number
   ) => SmartRow;
 
   /**

package/dist/types.d.ts

@@ -33,6 +33,31 @@ export type GetCellLocatorFn = (args: {
     rowIndex?: number;
     page: Page;
 }) => Locator;
+/**
+ * Hook called before each cell value is read in toJSON (and columnOverrides.read).
+ * Use this to scroll off-screen columns into view in horizontally virtualized tables,
+ * wait for lazy-rendered content, or perform any pre-read setup.
+ *
+ * @example
+ * // Scroll the column header into view to trigger horizontal virtualization render
+ * strategies: {
+ *   beforeCellRead: async ({ columnName, getHeaderCell }) => {
+ *     const header = await getHeaderCell(columnName);
+ *     await header.scrollIntoViewIfNeeded();
+ *   }
+ * }
+ */
+export type BeforeCellReadFn = (args: {
+    /** The resolved cell locator */
+    cell: Locator;
+    columnName: string;
+    columnIndex: number;
+    row: Locator;
+    page: Page;
+    root: Locator;
+    /** Resolves a column name to its header cell locator */
+    getHeaderCell: (columnName: string) => Promise<Locator>;
+}) => Promise<void>;
 /**
  * Function to get the currently active/focused cell.
  * Returns null if no cell is active.
@@ -110,12 +135,14 @@ export type SmartRow<T = any> = Locator & {
      * );
      */
     smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
+    /**
+     * Returns whether the row exists in the DOM (i.e. is not a sentinel row).
+     */
+    wasFound(): boolean;
 };
 export type StrategyContext = TableContext & {
     rowLocator?: Locator;
     rowIndex?: number;
-    /** Helper to reliably get a header cell locator by name */
-    getHeaderCell?: (headerName: string) => Promise<Locator>;
 };
 /**
  * Defines the contract for a sorting strategy.
@@ -166,6 +193,12 @@ export interface TableContext<T = any> {
     config: FinalTableConfig<T>;
     page: Page;
     resolve: (selector: Selector, parent: Locator | Page) => Locator;
+    /** Resolves a column name to its header cell locator. Available after table is initialized. */
+    getHeaderCell?: (columnName: string) => Promise<Locator>;
+    /** Returns all column names in order. Available after table is initialized. */
+    getHeaders?: () => Promise<string[]>;
+    /** Scrolls the table horizontally to bring the given column's header into view. */
+    scrollToColumn?: (columnName: string) => Promise<void>;
 }
 export interface PaginationPrimitives {
     /** Classic "Next Page" or "Scroll Down" */
@@ -196,7 +229,7 @@ export type FillStrategy = (options: {
 }) => Promise<void>;
 export interface ColumnOverride<TValue = any> {
     /**
-     * How to extract the value from the cell. (Replaces dataMapper logic)
+     * How to extract the value from the cell.
      */
     read?: (cell: Locator) => Promise<TValue> | TValue;
     /**
@@ -259,6 +292,12 @@ export interface TableStrategies {
     getCellLocator?: GetCellLocatorFn;
     /** Function to get the currently active/focused cell */
     getActiveCell?: GetActiveCellFn;
+    /**
+     * Hook called before each cell value is read in toJSON and columnOverrides.read.
+     * Fires for both the default innerText extraction and custom read mappers.
+     * Useful for scrolling off-screen columns into view in horizontally virtualized tables.
+     */
+    beforeCellRead?: BeforeCellReadFn;
     /** Custom helper to check if a table is fully loaded/ready */
     isTableLoaded?: (args: TableContext) => Promise<boolean>;
     /** Custom helper to check if a row is fully loaded/ready */
@@ -385,9 +424,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * @param index 1-based row index
      * @param options Optional settings including bringIntoView
      */
-    getRowByIndex: (index: number, options?: {
-        bringIntoView?: boolean;
-    }) => SmartRow;
+    getRowByIndex: (index: number) => SmartRow;
     /**
      * ASYNC: Searches for a single row across pages using pagination.
      * Auto-initializes the table if not already initialized.

package/dist/useTable.js

@@ -121,9 +121,24 @@ const useTable = (rootLocator, configOptions = {}) => {
         console.log(`⚠️ Throwing error to display [${promptName}] cleanly...`);
         throw new Error(finalPrompt);
     });
-    const _ensureInitialized = () => __awaiter(void 0, void 0, void 0, function* () {
+    const _autoInit = () => __awaiter(void 0, void 0, void 0, function* () {
         yield tableMapper.getMap();
     });
+    const _advancePage = () => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
+        const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell, getHeaders: result.getHeaders, scrollToColumn: result.scrollToColumn };
+        let advanced;
+        if (typeof config.strategies.pagination === 'function') {
+            advanced = !!(yield config.strategies.pagination(context));
+        }
+        else {
+            advanced = !!(((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goNext) && (yield config.strategies.pagination.goNext(context)));
+        }
+        if (advanced) {
+            tableState.currentPageIndex++;
+        }
+        return advanced;
+    });
     const result = {
         get currentPageIndex() { return tableState.currentPageIndex; },
         set currentPageIndex(v) { tableState.currentPageIndex = v; },
@@ -160,7 +175,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
             var _a;
             log("Resetting table...");
-            const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+            const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell };
             yield config.onReset(context);
             if (typeof config.strategies.pagination !== 'function' && ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goToFirst)) {
                 log("Auto-navigating to first page...");
@@ -172,7 +187,8 @@ const useTable = (rootLocator, configOptions = {}) => {
             _hasPaginated = false;
             tableState.currentPageIndex = 0;
             tableMapper.clear();
-            log("Table reset complete.");
+            log("Table reset complete. Calling autoInit to restore state.");
+            yield _autoInit();
         }),
         revalidate: () => __awaiter(void 0, void 0, void 0, function* () {
             log("Revalidating table structure...");
@@ -182,16 +198,16 @@ 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.getRows() which auto-initialize.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.findRows() which auto-initialize.');
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = filterEngine.applyFilters(allRows, filters, map, options.exact || false, rootLocator.page());
             const rowLocator = matchedRows.first();
             return _makeSmart(rowLocator, map, 0); // fallback index 0
         },
-        getRowByIndex: (index, options = {}) => {
+        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.getRows() which auto-initialize.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.findRows() which auto-initialize.');
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(index);
             return _makeSmart(rowLocator, map, index);
         },
@@ -208,7 +224,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         sorting: {
             apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
                 var _a;
-                yield _ensureInitialized();
+                yield _autoInit();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
                 log(`Applying sort for column "${columnName}" (${direction})`);
@@ -237,7 +253,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw new Error(`Failed to sort column "${columnName}" to "${direction}" after ${maxRetries} attempts.`);
             }),
             getState: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
-                yield _ensureInitialized();
+                yield _autoInit();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
                 const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell };
@@ -247,8 +263,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         // ─── Shared async row iterator ───────────────────────────────────────────
         [Symbol.asyncIterator]() {
             return __asyncGenerator(this, arguments, function* _a() {
-                var _b;
-                yield __await(_ensureInitialized());
+                yield __await(_autoInit());
                 const map = tableMapper.getMapSync();
                 const effectiveMaxPages = config.maxPages;
                 let rowIndex = 0;
@@ -261,25 +276,16 @@ const useTable = (rootLocator, configOptions = {}) => {
                     }
                     if (pagesScanned >= effectiveMaxPages)
                         break;
-                    const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                    let advanced;
-                    if (typeof config.strategies.pagination === 'function') {
-                        advanced = !!(yield __await(config.strategies.pagination(context)));
-                    }
-                    else {
-                        advanced = !!(((_b = config.strategies.pagination) === null || _b === void 0 ? void 0 : _b.goNext) && (yield __await(config.strategies.pagination.goNext(context))));
-                    }
-                    if (!advanced)
+                    if (!(yield __await(_advancePage())))
                         break;
-                    tableState.currentPageIndex++;
                     pagesScanned++;
                 }
             });
         },
         // ─── Private row-iteration engine ────────────────────────────────────────
         forEach: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
-            var _a, _b, _c, _d;
-            yield _ensureInitialized();
+            var _a, _b, _c;
+            yield _autoInit();
             const map = tableMapper.getMapSync();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
             const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
@@ -321,23 +327,14 @@ const useTable = (rootLocator, configOptions = {}) => {
                 rowIndex += smartRows.length;
                 if (stopped || pagesScanned >= effectiveMaxPages)
                     break;
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                let advanced;
-                if (typeof config.strategies.pagination === 'function') {
-                    advanced = !!(yield config.strategies.pagination(context));
-                }
-                else {
-                    advanced = !!(((_d = config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) && (yield config.strategies.pagination.goNext(context)));
-                }
-                if (!advanced)
+                if (!(yield _advancePage()))
                     break;
-                tableState.currentPageIndex++;
                 pagesScanned++;
             }
         }),
         map: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
-            var _a, _b, _c, _d;
-            yield _ensureInitialized();
+            var _a, _b, _c;
+            yield _autoInit();
             const map = tableMapper.getMapSync();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
             const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
@@ -383,24 +380,15 @@ const useTable = (rootLocator, configOptions = {}) => {
                 rowIndex += smartRows.length;
                 if (stopped || pagesScanned >= effectiveMaxPages)
                     break;
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                let advanced;
-                if (typeof config.strategies.pagination === 'function') {
-                    advanced = !!(yield config.strategies.pagination(context));
-                }
-                else {
-                    advanced = !!(((_d = config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) && (yield config.strategies.pagination.goNext(context)));
-                }
-                if (!advanced)
+                if (!(yield _advancePage()))
                     break;
-                tableState.currentPageIndex++;
                 pagesScanned++;
             }
             return results;
         }),
         filter: (predicate_1, ...args_1) => __awaiter(void 0, [predicate_1, ...args_1], void 0, function* (predicate, options = {}) {
-            var _a, _b, _c, _d;
-            yield _ensureInitialized();
+            var _a, _b, _c;
+            yield _autoInit();
             const map = tableMapper.getMapSync();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
             const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
@@ -432,7 +420,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         if (stopped)
                             break;
                         if (dedupeKeys) {
-                            const key = yield options.dedupe(row);
+                            const key = yield dedupeStrategy(row);
                             if (dedupeKeys.has(key))
                                 continue;
                             dedupeKeys.add(key);
@@ -445,17 +433,8 @@ const useTable = (rootLocator, configOptions = {}) => {
                 rowIndex += smartRows.length;
                 if (stopped || pagesScanned >= effectiveMaxPages)
                     break;
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                let advanced;
-                if (typeof config.strategies.pagination === 'function') {
-                    advanced = !!(yield config.strategies.pagination(context));
-                }
-                else {
-                    advanced = !!(((_d = config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) && (yield config.strategies.pagination.goNext(context)));
-                }
-                if (!advanced)
+                if (!(yield _advancePage()))
                     break;
-                tableState.currentPageIndex++;
                 pagesScanned++;
             }
             return (0, smartRowArray_1.createSmartRowArray)(matched);

package/dist/utils/elementTracker.d.ts

@@ -0,0 +1,15 @@
+import { Locator } from '@playwright/test';
+export declare class ElementTracker {
+    readonly id: string;
+    constructor(prefix?: string);
+    /**
+     * Finds the indices of newly seen elements in the browser, storing their text signature
+     * in a WeakMap. This gracefully handles both append-only DOMs (by identity) and
+     * virtualized DOMs (by text signature if nodes are recycled).
+     */
+    getUnseenIndices(locators: Locator): Promise<number[]>;
+    /**
+     * Cleans up the tracking map from the browser window object.
+     */
+    cleanup(page: any): Promise<void>;
+}

package/dist/utils/elementTracker.js

@@ -0,0 +1,60 @@
+"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.ElementTracker = void 0;
+class ElementTracker {
+    constructor(prefix = 'tracker') {
+        this.id = `__smartTable_${prefix}_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    }
+    /**
+     * Finds the indices of newly seen elements in the browser, storing their text signature
+     * in a WeakMap. This gracefully handles both append-only DOMs (by identity) and
+     * virtualized DOMs (by text signature if nodes are recycled).
+     */
+    getUnseenIndices(locators) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield locators.evaluateAll((elements, trackerId) => {
+                const win = window;
+                if (!win[trackerId]) {
+                    win[trackerId] = new WeakMap();
+                }
+                const seenMap = win[trackerId];
+                const newIndices = [];
+                elements.forEach((el, index) => {
+                    // Determine a lightweight signature for the row (textContent strips HTML, fast)
+                    const signature = el.textContent || '';
+                    // If it's a new element, OR a recycled element with new data
+                    if (seenMap.get(el) !== signature) {
+                        seenMap.set(el, signature);
+                        newIndices.push(index);
+                    }
+                });
+                return newIndices;
+            }, this.id);
+        });
+    }
+    /**
+     * Cleans up the tracking map from the browser window object.
+     */
+    cleanup(page) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield page.evaluate((trackerId) => {
+                    delete window[trackerId];
+                }, this.id);
+            }
+            catch (e) {
+                // Ignore context destroyed errors during cleanup
+            }
+        });
+    }
+}
+exports.ElementTracker = ElementTracker;

package/package.json

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