@rickcedwhat/playwright-smart-table 6.7.1 → 6.7.3

package/dist/engine/rowFinder.js

@@ -13,6 +13,7 @@ exports.RowFinder = void 0;
 const debugUtils_1 = require("../utils/debugUtils");
 const smartRowArray_1 = require("../utils/smartRowArray");
 const validation_1 = require("../strategies/validation");
+const elementTracker_1 = require("../utils/elementTracker");
 class RowFinder {
     constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow, tableState = { currentPageIndex: 0 }) {
         this.rootLocator = rootLocator;
@@ -53,54 +54,62 @@ 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;
-            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(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;
-                for (let i = 0; i < currentRows.length; i++) {
-                    const smartRow = this.makeSmartRow(currentRows[i], map, allRows.length + i, this.tableState.currentPageIndex);
-                    if (isRowLoading && (yield isRowLoading(smartRow)))
-                        continue;
-                    allRows.push(smartRow);
-                }
-            });
-            // Scan first page
-            yield collectMatches();
-            // Pagination Loop - Corrected logic
-            // We always scan at least 1 page.
-            // If maxPages > 1, and we have a pagination strategy, we try to go next.
-            while (pagesScanned < effectiveMaxPages && this.config.strategies.pagination) {
-                const context = {
-                    root: this.rootLocator,
-                    config: this.config,
-                    resolve: this.resolve,
-                    page: this.rootLocator.page()
-                };
-                // Check if we should stop? (e.g. if we found enough rows? No, findRows finds ALL)
-                let paginationResult;
-                if (typeof this.config.strategies.pagination === 'function') {
-                    paginationResult = yield this.config.strategies.pagination(context);
-                }
-                else {
-                    // It's a PaginationPrimitives object, use goNext by default for findRows
-                    if (!this.config.strategies.pagination.goNext) {
-                        break; // Cannot paginate forward
+            const tracker = new elementTracker_1.ElementTracker('findRows');
+            try {
+                const collectMatches = () => __awaiter(this, void 0, void 0, function* () {
+                    var _a, _b;
+                    let rowLocators = this.resolve(this.config.rowSelector, this.rootLocator);
+                    // Only apply filters if we have them
+                    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());
                     }
-                    paginationResult = yield this.config.strategies.pagination.goNext(context);
-                }
-                const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
-                if (!didPaginate)
-                    break;
-                this.tableState.currentPageIndex++;
-                pagesScanned++;
-                // Wait for reload logic if needed? Usually pagination handles it.
+                    // Get only newly seen matched rows
+                    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;
+                    for (const idx of newIndices) {
+                        const smartRow = this.makeSmartRow(currentRows[idx], map, allRows.length, this.tableState.currentPageIndex);
+                        if (isRowLoading && (yield isRowLoading(smartRow)))
+                            continue;
+                        allRows.push(smartRow);
+                    }
+                });
+                // Scan first page
                 yield collectMatches();
+                // Pagination Loop
+                while (pagesScanned < effectiveMaxPages && this.config.strategies.pagination) {
+                    const context = {
+                        root: this.rootLocator,
+                        config: this.config,
+                        resolve: this.resolve,
+                        page: this.rootLocator.page()
+                    };
+                    let paginationResult;
+                    if (typeof this.config.strategies.pagination === 'function') {
+                        paginationResult = yield this.config.strategies.pagination(context);
+                    }
+                    else {
+                        if (this.config.strategies.pagination.goNextBulk) {
+                            paginationResult = yield this.config.strategies.pagination.goNextBulk(context);
+                        }
+                        else if (this.config.strategies.pagination.goNext) {
+                            paginationResult = yield this.config.strategies.pagination.goNext(context);
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
+                    if (!didPaginate)
+                        break;
+                    const pagesJumped = typeof paginationResult === 'number' ? paginationResult : 1;
+                    this.tableState.currentPageIndex += pagesJumped;
+                    pagesScanned += pagesJumped;
+                    yield collectMatches();
+                }
+            }
+            finally {
+                yield tracker.cleanup(this.rootLocator.page());
             }
             return (0, smartRowArray_1.createSmartRowArray)(allRows);
         });
@@ -161,16 +170,22 @@ class RowFinder {
                         paginationResult = yield this.config.strategies.pagination(context);
                     }
                     else {
-                        if (!this.config.strategies.pagination.goNext) {
-                            this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (no goNext primitive).`);
+                        if (this.config.strategies.pagination.goNextBulk) {
+                            paginationResult = yield this.config.strategies.pagination.goNextBulk(context);
+                        }
+                        else if (this.config.strategies.pagination.goNext) {
+                            paginationResult = yield this.config.strategies.pagination.goNext(context);
+                        }
+                        else {
+                            this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (no goNext or goNextBulk primitive).`);
                             return null;
                         }
-                        paginationResult = yield this.config.strategies.pagination.goNext(context);
                     }
                     const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                     if (didLoadMore) {
-                        this.tableState.currentPageIndex++;
-                        pagesScanned++;
+                        const pagesJumped = typeof paginationResult === 'number' ? paginationResult : 1;
+                        this.tableState.currentPageIndex += pagesJumped;
+                        pagesScanned += pagesJumped;
                         continue;
                     }
                     else {

package/dist/plugins.d.ts

@@ -30,6 +30,9 @@ export declare const Plugins: {
                 goRight: (context: import("./types").StrategyContext) => Promise<void>;
                 goHome: (context: import("./types").StrategyContext) => Promise<void>;
             };
+            loading: {
+                isHeaderLoading: () => Promise<boolean>;
+            };
             getCellLocator: ({ row, columnIndex }: any) => any;
             getActiveCell: ({ page }: any) => Promise<{
                 rowIndex: number;

package/dist/strategies/glide.d.ts

@@ -33,6 +33,9 @@ export declare const GlideStrategies: {
         goRight: (context: import("../types").StrategyContext) => Promise<void>;
         goHome: (context: import("../types").StrategyContext) => Promise<void>;
     };
+    loading: {
+        isHeaderLoading: () => Promise<boolean>;
+    };
     getCellLocator: ({ row, columnIndex }: any) => any;
     getActiveCell: ({ page }: any) => Promise<{
         rowIndex: number;

package/dist/strategies/glide.js

@@ -115,6 +115,9 @@ exports.GlideStrategies = {
         goRight: columns_1.glideGoRight,
         goHome: columns_1.glideGoHome
     },
+    loading: {
+        isHeaderLoading: () => __awaiter(void 0, void 0, void 0, function* () { return false; }) // Glide renders headers on a canvas, there is no innerText delay
+    },
     getCellLocator: exports.glideGetCellLocator,
     getActiveCell: exports.glideGetActiveCell
 };

package/dist/strategies/index.d.ts

@@ -15,6 +15,8 @@ export declare const Strategies: {
             previousBulk?: import("..").Selector;
             first?: import("..").Selector;
         }, options?: {
+            nextBulkPages?: number;
+            previousBulkPages?: number;
             stabilization?: import("./stabilization").StabilizationStrategy;
             timeout?: number;
         }) => import("../types").PaginationStrategy;

package/dist/strategies/pagination.d.ts

@@ -8,6 +8,8 @@ export declare const PaginationStrategies: {
         previousBulk?: Selector;
         first?: Selector;
     }, options?: {
+        nextBulkPages?: number;
+        previousBulkPages?: number;
         stabilization?: StabilizationStrategy;
         timeout?: number;
     }) => PaginationStrategy;

package/dist/strategies/pagination.js

@@ -13,9 +13,9 @@ exports.PaginationStrategies = void 0;
 const stabilization_1 = require("./stabilization");
 exports.PaginationStrategies = {
     click: (selectors, options = {}) => {
-        var _a;
+        var _a, _b, _c;
         const defaultStabilize = (_a = options.stabilization) !== null && _a !== void 0 ? _a : stabilization_1.StabilizationStrategies.contentChanged({ scope: 'first', timeout: options.timeout });
-        const createClicker = (selector) => {
+        const createClicker = (selector, returnVal = true) => {
             if (!selector)
                 return undefined;
             return (context) => __awaiter(void 0, void 0, void 0, function* () {
@@ -26,14 +26,14 @@ exports.PaginationStrategies = {
                 }
                 return yield defaultStabilize(context, () => __awaiter(void 0, void 0, void 0, function* () {
                     yield btn.click({ timeout: 2000 }).catch(() => { });
-                }));
+                })).then(stabilized => stabilized ? returnVal : false);
             });
         };
         return {
             goNext: createClicker(selectors.next),
             goPrevious: createClicker(selectors.previous),
-            goNextBulk: createClicker(selectors.nextBulk),
-            goPreviousBulk: createClicker(selectors.previousBulk),
+            goNextBulk: createClicker(selectors.nextBulk, (_b = options.nextBulkPages) !== null && _b !== void 0 ? _b : 10),
+            goPreviousBulk: createClicker(selectors.previousBulk, (_c = options.previousBulkPages) !== null && _c !== void 0 ? _c : 10),
             goToFirst: createClicker(selectors.first)
         };
     },

package/dist/strategies/validation.js

@@ -10,10 +10,13 @@ exports.validateFillStrategy = validateFillStrategy;
  * @param strategyName - Name of the strategy for error messages
  */
 function validatePaginationResult(result, strategyName = 'Custom Pagination Strategy') {
-    if (typeof result !== 'boolean') {
-        throw new Error(`[${strategyName}] Pagination strategy must return a boolean (true if paginated, false if no more pages). ` +
+    if (typeof result !== 'boolean' && typeof result !== 'number') {
+        throw new Error(`[${strategyName}] Pagination strategy must return a boolean (true if paginated, false if no more pages) or a number (pages jumped). ` +
             `Received: ${typeof result} (${JSON.stringify(result)})`);
     }
+    if (typeof result === 'number') {
+        return result > 0;
+    }
     return result;
 }
 /**

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 * 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";
+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  /** Jump to specific page index (0-indexed) */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n}\n\nexport type PaginationStrategy = ((context: TableContext) => Promise<boolean | number>) | 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

@@ -231,11 +231,11 @@ export interface PaginationPrimitives {
   /** Classic "Previous Page" or "Scroll Up" */
   goPrevious?: (context: TableContext) => Promise<boolean>;
 
-  /** Bulk skip forward multiple pages at once */
-  goNextBulk?: (context: TableContext) => Promise<boolean>;
+  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */
+  goNextBulk?: (context: TableContext) => Promise<boolean | number>;
 
-  /** Bulk skip backward multiple pages at once */
-  goPreviousBulk?: (context: TableContext) => Promise<boolean>;
+  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */
+  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;
 
   /** Jump to first page / scroll to top */
   goToFirst?: (context: TableContext) => Promise<boolean>;
@@ -244,7 +244,7 @@ export interface PaginationPrimitives {
   goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
 }
 
-export type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | PaginationPrimitives;
+export type PaginationStrategy = ((context: TableContext) => Promise<boolean | number>) | PaginationPrimitives;
 
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 

package/dist/types.d.ts

@@ -205,16 +205,16 @@ export interface PaginationPrimitives {
     goNext?: (context: TableContext) => Promise<boolean>;
     /** Classic "Previous Page" or "Scroll Up" */
     goPrevious?: (context: TableContext) => Promise<boolean>;
-    /** Bulk skip forward multiple pages at once */
-    goNextBulk?: (context: TableContext) => Promise<boolean>;
-    /** Bulk skip backward multiple pages at once */
-    goPreviousBulk?: (context: TableContext) => Promise<boolean>;
+    /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */
+    goNextBulk?: (context: TableContext) => Promise<boolean | number>;
+    /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */
+    goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;
     /** Jump to first page / scroll to top */
     goToFirst?: (context: TableContext) => Promise<boolean>;
     /** Jump to specific page index (0-indexed) */
     goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
 }
-export type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | PaginationPrimitives;
+export type PaginationStrategy = ((context: TableContext) => Promise<boolean | number>) | PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export type FillStrategy = (options: {
     row: SmartRow;

package/dist/useTable.js

@@ -33,6 +33,7 @@ const tableMapper_1 = require("./engine/tableMapper");
 const rowFinder_1 = require("./engine/rowFinder");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
+const elementTracker_1 = require("./utils/elementTracker");
 /**
  * Main hook to interact with a table.
  */
@@ -266,19 +267,27 @@ const useTable = (rootLocator, configOptions = {}) => {
                 yield __await(_autoInit());
                 const map = tableMapper.getMapSync();
                 const effectiveMaxPages = config.maxPages;
-                let rowIndex = 0;
-                let pagesScanned = 1;
-                while (true) {
-                    const pageRows = yield __await(resolve(config.rowSelector, rootLocator).all());
-                    for (const rowLocator of pageRows) {
-                        yield yield __await({ row: _makeSmart(rowLocator, map, rowIndex), rowIndex });
-                        rowIndex++;
+                const tracker = new elementTracker_1.ElementTracker('iterator');
+                try {
+                    let rowIndex = 0;
+                    let pagesScanned = 1;
+                    while (true) {
+                        const rowLocators = resolve(config.rowSelector, rootLocator);
+                        const newIndices = yield __await(tracker.getUnseenIndices(rowLocators));
+                        const pageRows = yield __await(rowLocators.all());
+                        for (const idx of newIndices) {
+                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex), rowIndex });
+                            rowIndex++;
+                        }
+                        if (pagesScanned >= effectiveMaxPages)
+                            break;
+                        if (!(yield __await(_advancePage())))
+                            break;
+                        pagesScanned++;
                     }
-                    if (pagesScanned >= effectiveMaxPages)
-                        break;
-                    if (!(yield __await(_advancePage())))
-                        break;
-                    pagesScanned++;
+                }
+                finally {
+                    yield __await(tracker.cleanup(rootLocator.page()));
                 }
             });
         },
@@ -291,45 +300,53 @@ const useTable = (rootLocator, configOptions = {}) => {
             const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
             const dedupeKeys = dedupeStrategy ? new Set() : null;
             const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
-            let rowIndex = 0;
-            let stopped = false;
-            let pagesScanned = 1;
-            const stop = () => { stopped = true; };
-            while (!stopped) {
-                const pageRows = yield resolve(config.rowSelector, rootLocator).all();
-                const smartRows = pageRows.map((r, i) => _makeSmart(r, map, rowIndex + i));
-                if (parallel) {
-                    yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
-                        if (stopped)
-                            return;
-                        if (dedupeKeys) {
-                            const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
+            const tracker = new elementTracker_1.ElementTracker('forEach');
+            try {
+                let rowIndex = 0;
+                let stopped = false;
+                let pagesScanned = 1;
+                const stop = () => { stopped = true; };
+                while (!stopped) {
+                    const rowLocators = resolve(config.rowSelector, rootLocator);
+                    const newIndices = yield tracker.getUnseenIndices(rowLocators);
+                    const pageRows = yield rowLocators.all();
+                    const smartRows = newIndices.map((idx, i) => _makeSmart(pageRows[idx], map, rowIndex + i));
+                    if (parallel) {
+                        yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
+                            if (stopped)
                                 return;
-                            dedupeKeys.add(key);
-                        }
-                        yield callback({ row, rowIndex: row.rowIndex, stop });
-                    })));
-                }
-                else {
-                    for (const row of smartRows) {
-                        if (stopped)
-                            break;
-                        if (dedupeKeys) {
-                            const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
-                                continue;
-                            dedupeKeys.add(key);
+                            if (dedupeKeys) {
+                                const key = yield dedupeStrategy(row);
+                                if (dedupeKeys.has(key))
+                                    return;
+                                dedupeKeys.add(key);
+                            }
+                            yield callback({ row, rowIndex: row.rowIndex, stop });
+                        })));
+                    }
+                    else {
+                        for (const row of smartRows) {
+                            if (stopped)
+                                break;
+                            if (dedupeKeys) {
+                                const key = yield dedupeStrategy(row);
+                                if (dedupeKeys.has(key))
+                                    continue;
+                                dedupeKeys.add(key);
+                            }
+                            yield callback({ row, rowIndex: row.rowIndex, stop });
                         }
-                        yield callback({ row, rowIndex: row.rowIndex, stop });
                     }
+                    rowIndex += smartRows.length;
+                    if (stopped || pagesScanned >= effectiveMaxPages)
+                        break;
+                    if (!(yield _advancePage()))
+                        break;
+                    pagesScanned++;
                 }
-                rowIndex += smartRows.length;
-                if (stopped || pagesScanned >= effectiveMaxPages)
-                    break;
-                if (!(yield _advancePage()))
-                    break;
-                pagesScanned++;
+            }
+            finally {
+                yield tracker.cleanup(rootLocator.page());
             }
         }),
         map: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
@@ -340,49 +357,57 @@ const useTable = (rootLocator, configOptions = {}) => {
             const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
             const dedupeKeys = dedupeStrategy ? new Set() : null;
             const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : true;
+            const tracker = new elementTracker_1.ElementTracker('map');
             const results = [];
-            let rowIndex = 0;
-            let stopped = false;
-            let pagesScanned = 1;
-            const stop = () => { stopped = true; };
-            while (!stopped) {
-                const pageRows = yield resolve(config.rowSelector, rootLocator).all();
-                const smartRows = pageRows.map((r, i) => _makeSmart(r, map, rowIndex + i));
-                if (parallel) {
-                    const SKIP = Symbol('skip');
-                    const pageResults = yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
-                        if (dedupeKeys) {
-                            const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
-                                return SKIP;
-                            dedupeKeys.add(key);
+            try {
+                let rowIndex = 0;
+                let stopped = false;
+                let pagesScanned = 1;
+                const stop = () => { stopped = true; };
+                while (!stopped) {
+                    const rowLocators = resolve(config.rowSelector, rootLocator);
+                    const newIndices = yield tracker.getUnseenIndices(rowLocators);
+                    const pageRows = yield rowLocators.all();
+                    const smartRows = newIndices.map((idx, i) => _makeSmart(pageRows[idx], map, rowIndex + i));
+                    if (parallel) {
+                        const SKIP = Symbol('skip');
+                        const pageResults = yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
+                            if (dedupeKeys) {
+                                const key = yield dedupeStrategy(row);
+                                if (dedupeKeys.has(key))
+                                    return SKIP;
+                                dedupeKeys.add(key);
+                            }
+                            return callback({ row, rowIndex: row.rowIndex, stop });
+                        })));
+                        for (const r of pageResults) {
+                            if (r !== SKIP)
+                                results.push(r);
                         }
-                        return callback({ row, rowIndex: row.rowIndex, stop });
-                    })));
-                    for (const r of pageResults) {
-                        if (r !== SKIP)
-                            results.push(r);
                     }
-                }
-                else {
-                    for (const row of smartRows) {
-                        if (stopped)
-                            break;
-                        if (dedupeKeys) {
-                            const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
-                                continue;
-                            dedupeKeys.add(key);
+                    else {
+                        for (const row of smartRows) {
+                            if (stopped)
+                                break;
+                            if (dedupeKeys) {
+                                const key = yield dedupeStrategy(row);
+                                if (dedupeKeys.has(key))
+                                    continue;
+                                dedupeKeys.add(key);
+                            }
+                            results.push(yield callback({ row, rowIndex: row.rowIndex, stop }));
                         }
-                        results.push(yield callback({ row, rowIndex: row.rowIndex, stop }));
                     }
+                    rowIndex += smartRows.length;
+                    if (stopped || pagesScanned >= effectiveMaxPages)
+                        break;
+                    if (!(yield _advancePage()))
+                        break;
+                    pagesScanned++;
                 }
-                rowIndex += smartRows.length;
-                if (stopped || pagesScanned >= effectiveMaxPages)
-                    break;
-                if (!(yield _advancePage()))
-                    break;
-                pagesScanned++;
+            }
+            finally {
+                yield tracker.cleanup(rootLocator.page());
             }
             return results;
         }),
@@ -394,48 +419,56 @@ const useTable = (rootLocator, configOptions = {}) => {
             const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
             const dedupeKeys = dedupeStrategy ? new Set() : null;
             const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
+            const tracker = new elementTracker_1.ElementTracker('filter');
             const matched = [];
-            let rowIndex = 0;
-            let stopped = false;
-            let pagesScanned = 1;
-            const stop = () => { stopped = true; };
-            while (!stopped) {
-                const pageRows = yield resolve(config.rowSelector, rootLocator).all();
-                const smartRows = pageRows.map((r, i) => _makeSmart(r, map, rowIndex + i, pagesScanned - 1));
-                if (parallel) {
-                    const flags = yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
-                        if (dedupeKeys) {
-                            const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
-                                return false;
-                            dedupeKeys.add(key);
-                        }
-                        return predicate({ row, rowIndex: row.rowIndex, stop });
-                    })));
-                    smartRows.forEach((row, i) => { if (flags[i])
-                        matched.push(row); });
-                }
-                else {
-                    for (const row of smartRows) {
-                        if (stopped)
-                            break;
-                        if (dedupeKeys) {
-                            const key = yield dedupeStrategy(row);
-                            if (dedupeKeys.has(key))
-                                continue;
-                            dedupeKeys.add(key);
-                        }
-                        if (yield predicate({ row, rowIndex: row.rowIndex, stop })) {
-                            matched.push(row);
+            try {
+                let rowIndex = 0;
+                let stopped = false;
+                let pagesScanned = 1;
+                const stop = () => { stopped = true; };
+                while (!stopped) {
+                    const rowLocators = resolve(config.rowSelector, rootLocator);
+                    const newIndices = yield tracker.getUnseenIndices(rowLocators);
+                    const pageRows = yield rowLocators.all();
+                    const smartRows = newIndices.map((idx, i) => _makeSmart(pageRows[idx], map, rowIndex + i, pagesScanned - 1));
+                    if (parallel) {
+                        const flags = yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
+                            if (dedupeKeys) {
+                                const key = yield dedupeStrategy(row);
+                                if (dedupeKeys.has(key))
+                                    return false;
+                                dedupeKeys.add(key);
+                            }
+                            return predicate({ row, rowIndex: row.rowIndex, stop });
+                        })));
+                        smartRows.forEach((row, i) => { if (flags[i])
+                            matched.push(row); });
+                    }
+                    else {
+                        for (const row of smartRows) {
+                            if (stopped)
+                                break;
+                            if (dedupeKeys) {
+                                const key = yield dedupeStrategy(row);
+                                if (dedupeKeys.has(key))
+                                    continue;
+                                dedupeKeys.add(key);
+                            }
+                            if (yield predicate({ row, rowIndex: row.rowIndex, stop })) {
+                                matched.push(row);
+                            }
                         }
                     }
+                    rowIndex += smartRows.length;
+                    if (stopped || pagesScanned >= effectiveMaxPages)
+                        break;
+                    if (!(yield _advancePage()))
+                        break;
+                    pagesScanned++;
                 }
-                rowIndex += smartRows.length;
-                if (stopped || pagesScanned >= effectiveMaxPages)
-                    break;
-                if (!(yield _advancePage()))
-                    break;
-                pagesScanned++;
+            }
+            finally {
+                yield tracker.cleanup(rootLocator.page());
             }
             return (0, smartRowArray_1.createSmartRowArray)(matched);
         }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.7.1",
+  "version": "6.7.3",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -23,11 +23,16 @@
     "docs:build": "vitepress build docs",
     "build": "npm run generate-types && npm run generate-config-types && npm run generate-docs && npm run generate-all-api-docs && npm run update-all-api-signatures && tsc",
     "prepublishOnly": "npm run build",
+    "clean-port": "lsof -ti:3000 | xargs kill -9 || true",
+    "pretest": "npm run clean-port",
+    "posttest": "npm run clean-port",
     "test": "npm run test:unit && npx playwright test",
     "test:unit": "vitest run --reporter=verbose --reporter=html",
     "test:unit:ui": "vitest --ui",
+    "pretest:e2e": "npm run clean-port",
+    "posttest:e2e": "npm run clean-port",
     "test:e2e": "npx playwright test",
-    "test:compatibility": "npx playwright test compatibility",
+    "test:compatibility": "npm run clean-port && npx playwright test compatibility",
     "prepare": "husky install"
   },
   "keywords": [