@rickcedwhat/playwright-smart-table 6.7.3 → 6.7.4

package/README.md

@@ -99,6 +99,8 @@ for await (const { row, rowIndex } of table) {
 }
 ```
 
+When your pagination strategy supports bulk jumps (`goNextBulk`), pass `{ useBulkPagination: true }` to `map`/`forEach`/`filter` to advance by multiple pages at once.
+
 > **`map` + UI interactions:** `map` defaults to `parallel: true`. If your callback opens popovers,
 > fills inputs, or otherwise mutates UI state, pass `{ parallel: false }` to avoid overlapping interactions.
 

package/dist/engine/rowFinder.js

@@ -48,7 +48,7 @@ class RowFinder {
     }
     findRows(filters, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a, _b, _c, _d;
             const filtersRecord = filters || {};
             const map = yield this.tableMapper.getMap();
             const allRows = [];
@@ -85,19 +85,14 @@ class RowFinder {
                         page: this.rootLocator.page()
                     };
                     let paginationResult;
-                    if (typeof this.config.strategies.pagination === 'function') {
-                        paginationResult = yield this.config.strategies.pagination(context);
+                    if ((_c = this.config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNextBulk) {
+                        paginationResult = yield this.config.strategies.pagination.goNextBulk(context);
+                    }
+                    else if ((_d = this.config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) {
+                        paginationResult = yield this.config.strategies.pagination.goNext(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;
-                        }
+                        break;
                     }
                     const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                     if (!didPaginate)
@@ -116,7 +111,7 @@ class RowFinder {
     }
     findRowLocator(filters_1) {
         return __awaiter(this, arguments, void 0, function* (filters, options = {}) {
-            var _a, _b;
+            var _a, _b, _c, _d;
             const map = yield this.tableMapper.getMap();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages;
             let pagesScanned = 1;
@@ -166,20 +161,15 @@ class RowFinder {
                         page: this.rootLocator.page()
                     };
                     let paginationResult;
-                    if (typeof this.config.strategies.pagination === 'function') {
-                        paginationResult = yield this.config.strategies.pagination(context);
+                    if ((_c = this.config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNextBulk) {
+                        paginationResult = yield this.config.strategies.pagination.goNextBulk(context);
+                    }
+                    else if ((_d = this.config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) {
+                        paginationResult = yield this.config.strategies.pagination.goNext(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 {
-                            this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (no goNext or goNextBulk primitive).`);
-                            return null;
-                        }
+                        this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (no goNext or goNextBulk primitive).`);
+                        return null;
                     }
                     const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                     if (didLoadMore) {

package/dist/minimalConfigContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-config-types.mjs
  * It contains minimal type definitions for config generation prompts.
  */
-export declare const MINIMAL_CONFIG_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string or function returning a Locator.\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);\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\n/**\n * Configuration options for useTable - focus on selectors and basic setup\n */\nexport interface TableConfig<T = any> {\n  /** CSS selector or function for table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for table rows */\n  rowSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  \n  /** Transform header text (e.g., normalize, deduplicate) */\n  headerTransformer?: (args: { \n    text: string; \n    index: number; \n    locator: Locator;\n    seenHeaders: Set<string>;\n  }) => string | Promise<string>;\n  \n  /** Automatically scroll to table on init (default: true) */\n  autoScroll?: boolean;\n  \n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  \n  /** Advanced: Custom strategies for pagination, sorting, navigation, etc. */\n  strategies?: TableStrategies;\n  \n  /** Custom data mappers for extracting complex types (boolean, number) */\n  dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;\n}\n\n/**\n * Example usage:\n */\n// const table = useTable(page.locator('table'), {\n//   headerSelector: 'thead th',\n//   rowSelector: 'tbody tr',\n//   cellSelector: 'td',\n//   headerTransformer: ({ text }) => text.trim()\n// });\n\n";
+export declare const MINIMAL_CONFIG_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string or function returning a Locator.\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);\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\n/**\n * Configuration options for useTable - focus on selectors and basic setup\n */\nexport interface TableConfig<T = any> {\n  /** CSS selector or function for table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for table rows */\n  rowSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  \n  /** Transform header text (e.g., normalize, deduplicate) */\n  headerTransformer?: (args: { \n    text: string; \n    index: number; \n    locator: Locator;\n    seenHeaders: Set<string>;\n  }) => string | Promise<string>;\n  \n  /** Automatically scroll to table on init (default: true) */\n  autoScroll?: boolean;\n  \n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  \n  /** Advanced: Custom strategies for pagination, sorting, navigation, etc. */\n  strategies?: TableStrategies;\n}\n\n/**\n * Example usage:\n */\n// const table = useTable(page.locator('table'), {\n//   headerSelector: 'thead th',\n//   rowSelector: 'tbody tr',\n//   cellSelector: 'td',\n//   headerTransformer: ({ text }) => text.trim()\n// });\n\n";

package/dist/minimalConfigContext.js

@@ -60,9 +60,6 @@ export interface TableConfig<T = any> {
   
   /** Advanced: Custom strategies for pagination, sorting, navigation, etc. */
   strategies?: TableStrategies;
-  
-  /** Custom data mappers for extracting complex types (boolean, number) */
-  dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;
 }
 
 /**

package/dist/plugins.d.ts

@@ -10,14 +10,14 @@ export declare const Plugins: {
                 goUp: ({ root, page }: any) => Promise<void>;
                 goHome: ({ root, page }: any) => Promise<void>;
             };
-            pagination: import("./types").PaginationStrategy;
+            pagination: import("./types").PaginationPrimitives;
         };
     };
     Glide: {
         Strategies: {
             fill: import("./types").FillStrategy;
             fillSimple: import("./types").FillStrategy;
-            pagination: import("./types").PaginationStrategy;
+            pagination: import("./types").PaginationPrimitives;
             header: (context: import("./types").StrategyContext, options?: {
                 limit?: number;
                 selector?: string;

package/dist/smartRow.js

@@ -13,6 +13,7 @@ exports.createSmartRow = void 0;
 const fill_1 = require("./strategies/fill");
 const stringUtils_1 = require("./utils/stringUtils");
 const debugUtils_1 = require("./utils/debugUtils");
+const paginationPath_1 = require("./utils/paginationPath");
 /**
  * Internal helper to navigate to a cell with active cell optimization.
  * Uses navigation primitives (goUp, goDown, goLeft, goRight, goHome) for orchestration.
@@ -257,43 +258,37 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             throw new Error('Cannot bring row into view - row index is unknown. Use getRowByIndex() instead of getRow().');
         }
         const parentTable = smart.table;
-        // Cross-page Navigation using PaginationPrimitives
+        // Cross-page Navigation: when goToPage exists use retry loop (supports windowed UIs); otherwise use path planner or goToFirst+goNext
         if (tablePageIndex !== undefined && config.strategies.pagination) {
             const primitives = config.strategies.pagination;
-            // Only orchestrate if it's an object of primitives, not a single function
-            if (typeof config.strategies.pagination !== 'function') {
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                if (primitives.goToPage) {
-                    (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Jumping to page ${tablePageIndex} using goToPage primitive`);
-                    yield primitives.goToPage(tablePageIndex, context);
-                }
-                else if (primitives.goPrevious) {
-                    (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Looping goPrevious until we reach page ${tablePageIndex}`);
-                    const diff = parentTable.currentPageIndex - tablePageIndex;
-                    for (let i = 0; i < diff; i++) {
-                        const success = yield primitives.goPrevious(context);
-                        if (!success) {
-                            throw new Error(`bringIntoView: Failed to paginate backwards. Strategy aborted before reaching page ${tablePageIndex}.`);
-                        }
-                    }
+            const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+            const getCurrent = () => parentTable.currentPageIndex;
+            const setCurrent = (n) => { parentTable.currentPageIndex = n; };
+            if (primitives.goToPage) {
+                (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Navigating to page ${tablePageIndex} (goToPage retry loop)`);
+                yield (0, paginationPath_1.executeNavigationWithGoToPageRetry)(tablePageIndex, primitives, context, getCurrent, setCurrent);
+            }
+            else {
+                const path = (0, paginationPath_1.planNavigationPath)(getCurrent(), tablePageIndex, primitives);
+                if (path.length > 0) {
+                    (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Executing navigation path to page ${tablePageIndex} (${path.length} step(s))`);
+                    yield (0, paginationPath_1.executeNavigationPath)(path, primitives, context, getCurrent, setCurrent);
                 }
-                else if (primitives.goToFirst && primitives.goNext) {
+                else if (primitives.goToFirst && primitives.goNext && tablePageIndex >= 0) {
                     (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: going to first page and looping goNext until we reach page ${tablePageIndex}`);
                     yield primitives.goToFirst(context);
                     for (let i = 0; i < tablePageIndex; i++) {
-                        yield primitives.goNext(context);
+                        const ok = yield primitives.goNext(context);
+                        if (!ok)
+                            throw new Error(`bringIntoView: goNext failed before reaching page ${tablePageIndex}.`);
                     }
+                    parentTable.currentPageIndex = tablePageIndex;
                 }
                 else {
-                    (0, debugUtils_1.logDebug)(config, 'error', `Cannot bring row on page ${tablePageIndex} into view. No backwards pagination strategies (goToPage, goPrevious, or goToFirst) provided.`);
+                    (0, debugUtils_1.logDebug)(config, 'error', `Cannot bring row on page ${tablePageIndex} into view. No backwards pagination strategies (goToPage, goPrevious, goPreviousBulk, or goToFirst+goNext) provided.`);
                     throw new Error(`Cannot bring row on page ${tablePageIndex} into view: Row is on a different page and no backward pagination primitive found.`);
                 }
             }
-            else {
-                throw new Error(`Cannot bring row on page ${tablePageIndex} into view: Pagination is a single function. Provide an object with 'goPrevious', 'goToPage', or 'goToFirst' primitives.`);
-            }
-            // Successfully orchestrated backwards navigation, now update the state pointer
-            parentTable.currentPageIndex = tablePageIndex;
         }
         // Delay after pagination/finding before scrolling
         yield (0, debugUtils_1.debugDelay)(config, 'findRow');

package/dist/strategies/glide.d.ts

@@ -10,7 +10,7 @@ export declare const glideFillStrategy: FillStrategy;
  * This is faster but may not work for all Glide configurations.
  */
 export declare const glideFillSimple: FillStrategy;
-export declare const glidePaginationStrategy: import("../types").PaginationStrategy;
+export declare const glidePaginationStrategy: import("../types").PaginationPrimitives;
 export declare const glideGetCellLocator: ({ row, columnIndex }: any) => any;
 export declare const glideGetActiveCell: ({ page }: any) => Promise<{
     rowIndex: number;
@@ -20,7 +20,7 @@ export declare const glideGetActiveCell: ({ page }: any) => Promise<{
 export declare const GlideStrategies: {
     fill: FillStrategy;
     fillSimple: FillStrategy;
-    pagination: import("../types").PaginationStrategy;
+    pagination: import("../types").PaginationPrimitives;
     header: (context: import("../types").StrategyContext, options?: {
         limit?: number;
         selector?: string;

package/dist/strategies/pagination.js

@@ -29,12 +29,16 @@ exports.PaginationStrategies = {
                 })).then(stabilized => stabilized ? returnVal : false);
             });
         };
+        const nextBulk = (_b = options.nextBulkPages) !== null && _b !== void 0 ? _b : 10;
+        const prevBulk = (_c = options.previousBulkPages) !== null && _c !== void 0 ? _c : 10;
         return {
             goNext: createClicker(selectors.next),
             goPrevious: createClicker(selectors.previous),
-            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)
+            goNextBulk: createClicker(selectors.nextBulk, nextBulk),
+            goPreviousBulk: createClicker(selectors.previousBulk, prevBulk),
+            goToFirst: createClicker(selectors.first),
+            nextBulkPages: nextBulk,
+            previousBulkPages: prevBulk,
         };
     },
     /**
@@ -78,9 +82,26 @@ exports.PaginationStrategies = {
                 return yield stabilization(context, doScroll);
             });
         };
+        const createGoToFirst = () => {
+            return (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const { root, resolve } = context;
+                const scrollTarget = options.scrollTarget
+                    ? resolve(options.scrollTarget, root)
+                    : root;
+                const doScroll = () => __awaiter(void 0, void 0, void 0, function* () {
+                    yield scrollTarget.evaluate((el) => {
+                        el.scrollTop = 0;
+                        el.scrollLeft = 0;
+                    });
+                });
+                // Stabilization: Wait for content to reset
+                return yield stabilization(context, doScroll);
+            });
+        };
         return {
             goNext: createScroller(1),
-            goPrevious: createScroller(-1)
+            goPrevious: createScroller(-1),
+            goToFirst: createGoToFirst()
         };
     }
 };

package/dist/strategies/rdg.d.ts

@@ -12,7 +12,7 @@ export declare const rdgGetCellLocator: ({ row, columnIndex }: any) => any;
 /**
  * Scrolls the grid vertically to load more virtualized rows.
  */
-export declare const rdgPaginationStrategy: import("../types").PaginationStrategy;
+export declare const rdgPaginationStrategy: import("../types").PaginationPrimitives;
 export declare const rdgNavigation: {
     goRight: ({ root, page }: any) => Promise<void>;
     goLeft: ({ root, page }: any) => Promise<void>;
@@ -30,5 +30,5 @@ export declare const RDGStrategies: {
         goUp: ({ root, page }: any) => Promise<void>;
         goHome: ({ root, page }: any) => Promise<void>;
     };
-    pagination: import("../types").PaginationStrategy;
+    pagination: import("../types").PaginationPrimitives;
 };

package/dist/strategies/validation.d.ts

@@ -1,15 +1,10 @@
-import type { PaginationStrategy, SortingStrategy, FillStrategy } from '../types';
+import type { SortingStrategy, FillStrategy } from '../types';
 /**
- * Validates that a pagination strategy returns a boolean.
+ * Validates that a pagination strategy returns a boolean or number (pages jumped).
  * @param result - The result from a pagination strategy
  * @param strategyName - Name of the strategy for error messages
  */
 export declare function validatePaginationResult(result: any, strategyName?: string): boolean;
-/**
- * Validates that a pagination strategy is properly configured.
- * @param strategy - The pagination strategy to validate
- */
-export declare function validatePaginationStrategy(strategy: any): strategy is PaginationStrategy;
 /**
  * Validates that a sorting strategy has the required methods.
  * @param strategy - The sorting strategy to validate

package/dist/strategies/validation.js

@@ -1,11 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validatePaginationResult = validatePaginationResult;
-exports.validatePaginationStrategy = validatePaginationStrategy;
 exports.validateSortingStrategy = validateSortingStrategy;
 exports.validateFillStrategy = validateFillStrategy;
 /**
- * Validates that a pagination strategy returns a boolean.
+ * Validates that a pagination strategy returns a boolean or number (pages jumped).
  * @param result - The result from a pagination strategy
  * @param strategyName - Name of the strategy for error messages
  */
@@ -19,16 +18,6 @@ function validatePaginationResult(result, strategyName = 'Custom Pagination Stra
     }
     return result;
 }
-/**
- * Validates that a pagination strategy is properly configured.
- * @param strategy - The pagination strategy to validate
- */
-function validatePaginationStrategy(strategy) {
-    if (typeof strategy !== 'function') {
-        throw new Error(`Pagination strategy must be a function. Received: ${typeof strategy}`);
-    }
-    return true;
-}
 /**
  * Validates that a sorting strategy has the required methods.
  * @param strategy - The sorting strategy to validate

package/dist/typeContext.d.ts

@@ -1,6 +1,6 @@
 /**
  * 🤖 AUTO-GENERATED FILE. DO NOT EDIT.
- * This file is generated by scripts/embed-types.js
+ * This file is generated by scripts/embed-types.mjs
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in toJSON (and columnOverrides.read).\n * Use this to scroll off-screen columns into view in horizontally virtualized tables,\n * wait for lazy-rendered content, or perform any pre-read setup.\n *\n * @example\n * // Scroll the column header into view to trigger horizontal virtualization render\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded();\n *   }\n * }\n */\nexport type BeforeCellReadFn = (args: {\n  /** The resolved cell locator */\n  cell: Locator;\n  columnName: string;\n  columnIndex: number;\n  row: Locator;\n  page: Page;\n  root: Locator;\n  /** Resolves a column name to its header cell locator */\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n}) => Promise<void>;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** 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";
+export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in toJSON (and columnOverrides.read).\n * Use this to scroll off-screen columns into view in horizontally virtualized tables,\n * wait for lazy-rendered content, or perform any pre-read setup.\n *\n * @example\n * // Scroll the column header into view to trigger horizontal virtualization render\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded();\n *   }\n * }\n */\nexport type BeforeCellReadFn = (args: {\n  /** The resolved cell locator */\n  cell: Locator;\n  columnName: string;\n  columnIndex: number;\n  row: Locator;\n  page: Page;\n  root: Locator;\n  /** Resolves a column name to its header cell locator */\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n}) => Promise<void>;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /**\n   * Jump to specific page index (0-indexed).\n   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6\u201314).\n   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.\n   */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n\n  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */\n  nextBulkPages?: number;\n\n  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */\n  previousBulkPages?: number;\n}\n\nexport type PaginationStrategy = PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell.\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\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   * When true, use goNextBulk (if present) to advance pages during iteration.\n   * @default false \u2014 uses goNext for one-page-at-a-time advancement\n   */\n  useBulkPagination?: boolean;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 0-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 0-based row index\n   */\n  getRowByIndex: (\n    index: number\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `parallel: true`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `{ parallel: false }` to avoid concurrent\n   * > interactions interfering with each other.\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 must use parallel: false\n   * const assignees = await table.map(async ({ row }) => {\n   *   await row.getCell('Assignee').locator('button').click();\n   *   const name = await page.locator('.popover .name').innerText();\n   *   await page.keyboard.press('Escape');\n   *   return name;\n   * }, { parallel: false });\n   */\n  map<R>(\n    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.\n   * Rows are returned as-is \u2014 call `bringIntoView()` on each if needed.\n   * Execution is sequential by default.\n   *\n   * @example\n   * const active = await table.filter(async ({ row }) =>\n   *   await row.getCell('Status').innerText() === 'Active'\n   * );\n   */\n  filter(\n    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,\n    options?: RowIterationOptions\n  ): Promise<SmartRowArray<T>>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   * Automatically throws an Error containing the prompt.\n   */\n  generateConfig: () => Promise<void>;\n\n  /**\n   * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.\n   */\n  generateConfigPrompt: () => Promise<void>;\n}\n";

package/dist/typeContext.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TYPE_CONTEXT = void 0;
 /**
  * 🤖 AUTO-GENERATED FILE. DO NOT EDIT.
- * This file is generated by scripts/embed-types.js
+ * This file is generated by scripts/embed-types.mjs
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
 exports.TYPE_CONTEXT = `
@@ -240,11 +240,21 @@ export interface PaginationPrimitives {
   /** Jump to first page / scroll to top */
   goToFirst?: (context: TableContext) => Promise<boolean>;
 
-  /** Jump to specific page index (0-indexed) */
+  /**
+   * Jump to specific page index (0-indexed).
+   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6–14).
+   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.
+   */
   goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
+
+  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */
+  nextBulkPages?: number;
+
+  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
+  previousBulkPages?: number;
 }
 
-export type PaginationStrategy = ((context: TableContext) => Promise<boolean | number>) | PaginationPrimitives;
+export type PaginationStrategy = PaginationPrimitives;
 
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 
@@ -417,6 +427,11 @@ export type RowIterationOptions = {
    * (e.g. infinite scroll tables). Returns a unique key per row.
    */
   dedupe?: DedupeStrategy;
+  /**
+   * When true, use goNextBulk (if present) to advance pages during iteration.
+   * @default false — uses goNext for one-page-at-a-time advancement
+   */
+  useBulkPagination?: boolean;
 };
 
 export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {
@@ -451,10 +466,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   ) => SmartRow;
 
   /**
-   * Gets a row by 1-based index on the current page.
+   * Gets a row by 0-based index on the current page.
    * Throws error if table is not initialized.
-   * @param index 1-based row index
-   * @param options Optional settings including bringIntoView
+   * @param index 0-based row index
    */
   getRowByIndex: (
     index: number
@@ -581,6 +595,11 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
    * Automatically throws an Error containing the prompt.
    */
+  generateConfig: () => Promise<void>;
+
+  /**
+   * @deprecated Use \`generateConfig()\` instead. Will be removed in v7.0.0.
+   */
   generateConfigPrompt: () => Promise<void>;
 }
 `;

package/dist/types.d.ts

@@ -211,10 +211,18 @@ export interface PaginationPrimitives {
     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) */
+    /**
+     * Jump to specific page index (0-indexed).
+     * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6–14).
+     * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.
+     */
     goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
+    /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */
+    nextBulkPages?: number;
+    /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
+    previousBulkPages?: number;
 }
-export type PaginationStrategy = ((context: TableContext) => Promise<boolean | number>) | PaginationPrimitives;
+export type PaginationStrategy = PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export type FillStrategy = (options: {
     row: SmartRow;
@@ -387,6 +395,11 @@ export type RowIterationOptions = {
      * (e.g. infinite scroll tables). Returns a unique key per row.
      */
     dedupe?: DedupeStrategy;
+    /**
+     * When true, use goNextBulk (if present) to advance pages during iteration.
+     * @default false — uses goNext for one-page-at-a-time advancement
+     */
+    useBulkPagination?: boolean;
 };
 export interface TableResult<T = any> extends AsyncIterable<{
     row: SmartRow<T>;
@@ -419,10 +432,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
         exact?: boolean;
     }) => SmartRow;
     /**
-     * Gets a row by 1-based index on the current page.
+     * Gets a row by 0-based index on the current page.
      * Throws error if table is not initialized.
-     * @param index 1-based row index
-     * @param options Optional settings including bringIntoView
+     * @param index 0-based row index
      */
     getRowByIndex: (index: number) => SmartRow;
     /**
@@ -526,5 +538,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
      * Automatically throws an Error containing the prompt.
      */
+    generateConfig: () => Promise<void>;
+    /**
+     * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.
+     */
     generateConfigPrompt: () => Promise<void>;
 }

package/dist/useTable.js

@@ -24,6 +24,7 @@ var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _ar
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useTable = void 0;
 const minimalConfigContext_1 = require("./minimalConfigContext");
+const validation_1 = require("./strategies/validation");
 const loading_1 = require("./strategies/loading");
 const fill_1 = require("./strategies/fill");
 const headers_1 = require("./strategies/headers");
@@ -45,7 +46,7 @@ const useTable = (rootLocator, configOptions = {}) => {
     const defaultStrategies = {
         fill: fill_1.FillStrategies.default,
         header: headers_1.HeaderStrategies.visible,
-        pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }),
+        pagination: {},
         loading: {
             isHeaderLoading: loading_1.LoadingStrategies.Headers.stable(200)
         }
@@ -125,20 +126,26 @@ const useTable = (rootLocator, configOptions = {}) => {
     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;
+    // Default: goNext (one page). Pass useBulk true to prefer goNextBulk. "How far" uses numeric return when strategy provides it.
+    const _advancePage = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (useBulk = false) {
         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));
+        const pagination = config.strategies.pagination;
+        let rawResult;
+        if (useBulk && (pagination === null || pagination === void 0 ? void 0 : pagination.goNextBulk)) {
+            rawResult = yield pagination.goNextBulk(context);
         }
-        else {
-            advanced = !!(((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goNext) && (yield config.strategies.pagination.goNext(context)));
+        else if (pagination === null || pagination === void 0 ? void 0 : pagination.goNext) {
+            rawResult = yield pagination.goNext(context);
         }
-        if (advanced) {
-            tableState.currentPageIndex++;
+        else if (pagination === null || pagination === void 0 ? void 0 : pagination.goNextBulk) {
+            rawResult = yield pagination.goNextBulk(context);
         }
-        return advanced;
+        const didAdvance = rawResult !== undefined && (0, validation_1.validatePaginationResult)(rawResult, 'Pagination Strategy');
+        const pagesJumped = typeof rawResult === 'number' ? rawResult : (didAdvance ? 1 : 0);
+        if (pagesJumped > 0) {
+            tableState.currentPageIndex += pagesJumped;
+        }
+        return didAdvance;
     });
     const result = {
         get currentPageIndex() { return tableState.currentPageIndex; },
@@ -178,7 +185,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             log("Resetting table...");
             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)) {
+            if ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goToFirst) {
                 log("Auto-navigating to first page...");
                 yield config.strategies.pagination.goToFirst(context);
             }
@@ -268,6 +275,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 const map = tableMapper.getMapSync();
                 const effectiveMaxPages = config.maxPages;
                 const tracker = new elementTracker_1.ElementTracker('iterator');
+                const useBulk = false; // iterator has no options; default goNext
                 try {
                     let rowIndex = 0;
                     let pagesScanned = 1;
@@ -281,7 +289,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         }
                         if (pagesScanned >= effectiveMaxPages)
                             break;
-                        if (!(yield __await(_advancePage())))
+                        if (!(yield __await(_advancePage(useBulk))))
                             break;
                         pagesScanned++;
                     }
@@ -293,13 +301,14 @@ const useTable = (rootLocator, configOptions = {}) => {
         },
         // ─── 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;
+            var _a, _b, _c, _d;
             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;
             const dedupeKeys = dedupeStrategy ? new Set() : null;
             const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
+            const useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
             const tracker = new elementTracker_1.ElementTracker('forEach');
             try {
                 let rowIndex = 0;
@@ -340,7 +349,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     rowIndex += smartRows.length;
                     if (stopped || pagesScanned >= effectiveMaxPages)
                         break;
-                    if (!(yield _advancePage()))
+                    if (!(yield _advancePage(useBulk)))
                         break;
                     pagesScanned++;
                 }
@@ -350,13 +359,14 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
         }),
         map: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             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;
             const dedupeKeys = dedupeStrategy ? new Set() : null;
             const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : true;
+            const useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
             const tracker = new elementTracker_1.ElementTracker('map');
             const results = [];
             try {
@@ -401,7 +411,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     rowIndex += smartRows.length;
                     if (stopped || pagesScanned >= effectiveMaxPages)
                         break;
-                    if (!(yield _advancePage()))
+                    if (!(yield _advancePage(useBulk)))
                         break;
                     pagesScanned++;
                 }
@@ -412,13 +422,14 @@ const useTable = (rootLocator, configOptions = {}) => {
             return results;
         }),
         filter: (predicate_1, ...args_1) => __awaiter(void 0, [predicate_1, ...args_1], void 0, function* (predicate, options = {}) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             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;
             const dedupeKeys = dedupeStrategy ? new Set() : null;
             const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
+            const useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
             const tracker = new elementTracker_1.ElementTracker('filter');
             const matched = [];
             try {
@@ -462,7 +473,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     rowIndex += smartRows.length;
                     if (stopped || pagesScanned >= effectiveMaxPages)
                         break;
-                    if (!(yield _advancePage()))
+                    if (!(yield _advancePage(useBulk)))
                         break;
                     pagesScanned++;
                 }
@@ -472,12 +483,16 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return (0, smartRowArray_1.createSmartRowArray)(matched);
         }),
-        generateConfigPrompt: () => __awaiter(void 0, void 0, void 0, function* () {
+        generateConfig: () => __awaiter(void 0, void 0, void 0, function* () {
             const html = yield _getCleanHtml(rootLocator);
             const separator = "=".repeat(50);
             const content = `\n${separator} \n🤖 COPY INTO GEMINI / ChatGPT 🤖\n${separator} \nI am using 'playwright-smart-table'.\nTarget Table Locator: ${rootLocator.toString()} \nGenerate config for: \n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n${separator}\n`;
             yield _handlePrompt('Smart Table Config', content);
         }),
+        generateConfigPrompt: () => __awaiter(void 0, void 0, void 0, function* () {
+            console.warn('⚠️ [playwright-smart-table] generateConfigPrompt() is deprecated and will be removed in v7.0.0. Please use generateConfig() instead.');
+            return result.generateConfig();
+        }),
     };
     finalTable = result;
     return result;

package/dist/utils/paginationPath.d.ts

@@ -0,0 +1,37 @@
+import type { PaginationPrimitives, TableContext } from '../types';
+/** A single step in a navigation plan (e.g. "goNextBulk 3 times"). */
+export type NavigationStep = {
+    type: 'goToPage';
+    pageIndex: number;
+} | {
+    type: 'goNextBulk';
+    count: number;
+} | {
+    type: 'goNext';
+    count: number;
+} | {
+    type: 'goPreviousBulk';
+    count: number;
+} | {
+    type: 'goPrevious';
+    count: number;
+};
+/**
+ * Plans an optimal path from currentPageIndex to targetPageIndex using available primitives.
+ * Prefers goToPage when present; otherwise uses bulk steps (goNextBulk / goPreviousBulk) then
+ * single steps (goNext / goPrevious). May choose to overshoot with bulk then step back when
+ * that reduces total primitive calls (e.g. page 3 → 12 with bulk 10: goNextBulk once, goPrevious once).
+ */
+export declare function planNavigationPath(currentPageIndex: number, targetPageIndex: number, primitives: PaginationPrimitives): NavigationStep[];
+/**
+ * Navigate to targetPageIndex when goToPage is available but may be "windowed"
+ * (e.g. only works for visible page links 6–14). Tries goToPage(target); on false,
+ * steps once toward target (goNextBulk/goNext or goPreviousBulk/goPrevious), then retries.
+ * Example: from 3 to 38 with windowed goToPage → goToPage(38) false, goNextBulk(), goToPage(38) false, … goToPage(38) true.
+ */
+export declare function executeNavigationWithGoToPageRetry(targetPageIndex: number, primitives: PaginationPrimitives, context: TableContext, getCurrentPage: () => number, setCurrentPage: (n: number) => void): Promise<void>;
+/**
+ * Executes a navigation path by calling the corresponding primitives.
+ * Updates currentPageIndex via the provided setter as steps run.
+ */
+export declare function executeNavigationPath(path: NavigationStep[], primitives: PaginationPrimitives, context: TableContext, getCurrentPage: () => number, setCurrentPage: (n: number) => void): Promise<void>;

package/dist/utils/paginationPath.js

@@ -0,0 +1,227 @@
+"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.planNavigationPath = planNavigationPath;
+exports.executeNavigationWithGoToPageRetry = executeNavigationWithGoToPageRetry;
+exports.executeNavigationPath = executeNavigationPath;
+/**
+ * Plans an optimal path from currentPageIndex to targetPageIndex using available primitives.
+ * Prefers goToPage when present; otherwise uses bulk steps (goNextBulk / goPreviousBulk) then
+ * single steps (goNext / goPrevious). May choose to overshoot with bulk then step back when
+ * that reduces total primitive calls (e.g. page 3 → 12 with bulk 10: goNextBulk once, goPrevious once).
+ */
+function planNavigationPath(currentPageIndex, targetPageIndex, primitives) {
+    var _a, _b;
+    if (currentPageIndex === targetPageIndex)
+        return [];
+    if (primitives.goToPage) {
+        return [{ type: 'goToPage', pageIndex: targetPageIndex }];
+    }
+    const nextBulkSize = (_a = primitives.nextBulkPages) !== null && _a !== void 0 ? _a : 1;
+    const prevBulkSize = (_b = primitives.previousBulkPages) !== null && _b !== void 0 ? _b : 1;
+    if (targetPageIndex > currentPageIndex) {
+        // Forward: current → target
+        const stepsForward = targetPageIndex - currentPageIndex;
+        const hasBulk = !!(primitives.goNextBulk && nextBulkSize > 0);
+        const hasPrev = !!primitives.goPrevious;
+        if (!hasBulk || nextBulkSize <= 0) {
+            if (primitives.goNext) {
+                return [{ type: 'goNext', count: stepsForward }];
+            }
+            return [];
+        }
+        const bulkCountA = Math.floor(stepsForward / nextBulkSize);
+        const remA = stepsForward % nextBulkSize;
+        const totalA = bulkCountA + remA;
+        let totalB = Infinity;
+        let bulkCountB = 0;
+        let overB = 0;
+        if (hasPrev && primitives.goPreviousBulk && prevBulkSize > 0) {
+            bulkCountB = Math.ceil(stepsForward / nextBulkSize);
+            overB = bulkCountB * nextBulkSize - stepsForward;
+            totalB = bulkCountB + overB;
+        }
+        if (totalB < totalA) {
+            const path = [];
+            if (bulkCountB > 0)
+                path.push({ type: 'goNextBulk', count: bulkCountB });
+            if (overB > 0)
+                path.push({ type: 'goPrevious', count: overB });
+            return path;
+        }
+        const path = [];
+        if (bulkCountA > 0)
+            path.push({ type: 'goNextBulk', count: bulkCountA });
+        if (remA > 0)
+            path.push({ type: 'goNext', count: remA });
+        return path;
+    }
+    // Backward: current → target
+    const stepsBack = currentPageIndex - targetPageIndex;
+    const hasPrevBulk = !!(primitives.goPreviousBulk && prevBulkSize > 0);
+    const hasNext = !!primitives.goNext;
+    if (!hasPrevBulk || prevBulkSize <= 0) {
+        if (primitives.goPrevious) {
+            return [{ type: 'goPrevious', count: stepsBack }];
+        }
+        // goToFirst + goNext loop is handled by caller (bringIntoView) when path is empty
+        return [];
+    }
+    const bulkCountA = Math.floor(stepsBack / prevBulkSize);
+    const remA = stepsBack % prevBulkSize;
+    const totalA = bulkCountA + remA;
+    let totalB = Infinity;
+    let bulkCountB = 0;
+    let overB = 0;
+    if (hasNext) {
+        bulkCountB = Math.ceil(stepsBack / prevBulkSize);
+        overB = bulkCountB * prevBulkSize - stepsBack;
+        totalB = bulkCountB + overB;
+    }
+    if (totalB < totalA) {
+        const path = [];
+        if (bulkCountB > 0)
+            path.push({ type: 'goPreviousBulk', count: bulkCountB });
+        if (overB > 0)
+            path.push({ type: 'goNext', count: overB });
+        return path;
+    }
+    const path = [];
+    if (bulkCountA > 0)
+        path.push({ type: 'goPreviousBulk', count: bulkCountA });
+    if (remA > 0)
+        path.push({ type: 'goPrevious', count: remA });
+    return path;
+}
+const MAX_GO_TO_PAGE_RETRIES = 200;
+/**
+ * Navigate to targetPageIndex when goToPage is available but may be "windowed"
+ * (e.g. only works for visible page links 6–14). Tries goToPage(target); on false,
+ * steps once toward target (goNextBulk/goNext or goPreviousBulk/goPrevious), then retries.
+ * Example: from 3 to 38 with windowed goToPage → goToPage(38) false, goNextBulk(), goToPage(38) false, … goToPage(38) true.
+ */
+function executeNavigationWithGoToPageRetry(targetPageIndex, primitives, context, getCurrentPage, setCurrentPage) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (!primitives.goToPage)
+            return;
+        for (let i = 0; i < MAX_GO_TO_PAGE_RETRIES; i++) {
+            const current = getCurrentPage();
+            if (current === targetPageIndex)
+                return;
+            const ok = yield primitives.goToPage(targetPageIndex, context);
+            if (ok) {
+                setCurrentPage(targetPageIndex);
+                return;
+            }
+            // Step once toward target. Don't use bulk if it would overshoot and we can't step back (no goPrevious/goNext).
+            if (targetPageIndex > current) {
+                const nextBulkSize = (_a = primitives.nextBulkPages) !== null && _a !== void 0 ? _a : 1;
+                const wouldOvershoot = (current + nextBulkSize) > targetPageIndex;
+                const canStepBack = !!primitives.goPrevious;
+                const useBulk = primitives.goNextBulk && (!wouldOvershoot || canStepBack);
+                if (useBulk && primitives.goNextBulk) {
+                    const result = yield primitives.goNextBulk(context);
+                    if (!result)
+                        throw new Error('bringIntoView: goNextBulk failed during goToPage retry');
+                    const jumped = typeof result === 'number' ? result : nextBulkSize;
+                    setCurrentPage(getCurrentPage() + jumped);
+                }
+                else if (primitives.goNext) {
+                    const stepped = yield primitives.goNext(context);
+                    if (!stepped)
+                        throw new Error('bringIntoView: goNext failed during goToPage retry');
+                    setCurrentPage(getCurrentPage() + 1);
+                }
+                else {
+                    throw new Error(`bringIntoView: goToPage(${targetPageIndex}) returned false and no goNext/goNextBulk to advance`);
+                }
+            }
+            else {
+                const prevBulkSize = (_b = primitives.previousBulkPages) !== null && _b !== void 0 ? _b : 1;
+                const wouldOvershoot = (current - prevBulkSize) < targetPageIndex;
+                const canStepBack = !!primitives.goNext;
+                const useBulk = primitives.goPreviousBulk && (!wouldOvershoot || canStepBack);
+                if (useBulk && primitives.goPreviousBulk) {
+                    const result = yield primitives.goPreviousBulk(context);
+                    if (!result)
+                        throw new Error('bringIntoView: goPreviousBulk failed during goToPage retry');
+                    const jumped = typeof result === 'number' ? result : prevBulkSize;
+                    setCurrentPage(getCurrentPage() - jumped);
+                }
+                else if (primitives.goPrevious) {
+                    const stepped = yield primitives.goPrevious(context);
+                    if (!stepped)
+                        throw new Error('bringIntoView: goPrevious failed during goToPage retry');
+                    setCurrentPage(getCurrentPage() - 1);
+                }
+                else {
+                    throw new Error(`bringIntoView: goToPage(${targetPageIndex}) returned false and no goPrevious/goPreviousBulk to step back`);
+                }
+            }
+        }
+        throw new Error(`bringIntoView: failed to reach page ${targetPageIndex} after ${MAX_GO_TO_PAGE_RETRIES} goToPage retries`);
+    });
+}
+/**
+ * Executes a navigation path by calling the corresponding primitives.
+ * Updates currentPageIndex via the provided setter as steps run.
+ */
+function executeNavigationPath(path, primitives, context, getCurrentPage, setCurrentPage) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const step of path) {
+            switch (step.type) {
+                case 'goToPage':
+                    if (primitives.goToPage) {
+                        const ok = yield primitives.goToPage(step.pageIndex, context);
+                        if (!ok)
+                            throw new Error(`goToPage(${step.pageIndex}) failed`);
+                        setCurrentPage(step.pageIndex);
+                    }
+                    break;
+                case 'goNextBulk':
+                    for (let i = 0; i < step.count && primitives.goNextBulk; i++) {
+                        const result = yield primitives.goNextBulk(context);
+                        if (!result)
+                            throw new Error('goNextBulk failed');
+                        const jumped = typeof result === 'number' ? result : 1;
+                        setCurrentPage(getCurrentPage() + jumped);
+                    }
+                    break;
+                case 'goNext':
+                    for (let i = 0; i < step.count && primitives.goNext; i++) {
+                        const ok = yield primitives.goNext(context);
+                        if (!ok)
+                            throw new Error('goNext failed');
+                        setCurrentPage(getCurrentPage() + 1);
+                    }
+                    break;
+                case 'goPreviousBulk':
+                    for (let i = 0; i < step.count && primitives.goPreviousBulk; i++) {
+                        const result = yield primitives.goPreviousBulk(context);
+                        if (!result)
+                            throw new Error('goPreviousBulk failed');
+                        const jumped = typeof result === 'number' ? result : 1;
+                        setCurrentPage(getCurrentPage() - jumped);
+                    }
+                    break;
+                case 'goPrevious':
+                    for (let i = 0; i < step.count && primitives.goPrevious; i++) {
+                        const ok = yield primitives.goPrevious(context);
+                        if (!ok)
+                            throw new Error('goPrevious failed');
+                        setCurrentPage(getCurrentPage() - 1);
+                    }
+                    break;
+            }
+        }
+    });
+}

package/package.json

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