@rickcedwhat/playwright-smart-table 6.6.0 → 6.7.0

package/README.md

@@ -76,13 +76,66 @@ const email = await row.getCell('Email').textContent();
 const allActive = await table.findRows({ Status: 'Active' });
 ```
 
+### Iterating Across Pages
+
+```typescript
+// forEach — sequential, safe for interactions (parallel: false default)
+await table.forEach(async ({ row, rowIndex, stop }) => {
+  if (await row.getCell('Status').innerText() === 'Done') stop();
+  await row.getCell('Checkbox').click();
+});
+
+// map — parallel within page, safe for reads (parallel: true default)
+const emails = await table.map(({ row }) => row.getCell('Email').innerText());
+
+// filter — async predicate across all pages, returns SmartRowArray
+const active = await table.filter(async ({ row }) =>
+  await row.getCell('Status').innerText() === 'Active'
+);
+
+// for await...of — low-level page-by-page iteration
+for await (const { row, rowIndex } of table) {
+  console.log(rowIndex, await row.getCell('Name').innerText());
+}
+```
+
+> **`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.
+
+### `filter` vs `findRows`
+
+| Use case | Best tool |
+|---|---|
+| Match by column value / regex / locator | `findRows` |
+| Computed value (math, range, derived) | `filter` |
+| Cross-column OR logic | `filter` |
+| Multi-step interaction in predicate (click, read, close) | `filter` |
+| Early exit after N matches | `filter` + `stop()` |
+
+**`findRows` is faster** for column-value matches — Playwright evaluates the locator natively with no DOM reads. **`filter` is more flexible** for logic that a CSS selector can't express.
+
+```typescript
+// findRows — structural match, no DOM reads, fast
+const notStarted = await table.findRows({
+  Status: (cell) => cell.locator('[class*="gray"]')
+});
+
+// filter — arbitrary async logic
+const expensive = await table.filter(async ({ row }) => {
+  const price = parseFloat(await row.getCell('Price').innerText());
+  const qty = parseFloat(await row.getCell('Qty').innerText());
+  return price * qty > 1000;
+});
+```
+
 ## Key Features
 
 - 🎯 **Smart Locators** - Find rows by content, not position
-- 🧠 **Fuzzy Matching** - Smart suggestions for typos (e.g., incorrectly typed "Firstname" suggests "First Name" in error messages)
+- 🧠 **Fuzzy Matching** - Smart suggestions for typos in column names
 - ⚡ **Smart Initialization** - Handles loading states and dynamic headers automatically
 - 📄 **Auto-Pagination** - Search across all pages automatically
 - 🔍 **Column-Aware Access** - Access cells by column name
+- 🔁 **Iteration Methods** - `forEach`, `map`, `filter`, and `for await...of` across all pages
 - 🛠️ **Debug Mode** - Visual debugging with slow motion and logging
 - 🔌 **[Extensible Strategies](docs/concepts/strategies.md)** - Support any table implementation
 - 💪 **Type-Safe** - Full TypeScript support
@@ -108,11 +161,21 @@ const allActive = await table.findRows({ Status: 'Active' });
 
 ### ⚠️ Important Note on Pagination & Interactions
 
-When using `findRows` across multiple pages, the returned `SmartRow` locators represent elements that may no longer be attached to the current DOM if the table paginated past them.
+When `findRows` or `filter` paginates across pages, returned `SmartRow` locators point to rows that may be off the current DOM page.
 
-- **Data Extraction:** Safe. You can use `table.iterateThroughTable()` to extract data (`await row.toJSON()`) while the row is visible.
-- **Interactions:** Unsafe directly. You cannot do `await row.click()` if the row is on Page 1 but the table is currently showing Page 3. 
-- **Solution:** If you need to interact with a row found on a previous page, you may be able to use `await row.bringIntoView()` before interacting with it to force the table to paginate back to that row (Note: this specific cross-page interaction flow is currently under testing).
+- **Data extraction:** Safe — `toJSON()` and cell reads work while the row is visible during iteration.
+- **Interactions after pagination:** Use `await row.bringIntoView()` first — it navigates back to the page the row was originally found on, then you can safely click/fill.
+
+```typescript
+const active = await table.filter(async ({ row }) =>
+  await row.getCell('Status').innerText() === 'Active'
+);
+
+for (const row of active) {
+  await row.bringIntoView(); // navigate back to the row's page
+  await row.getCell('Checkbox').click(); // safe to interact
+}
+```
 
 ## Documentation
 

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,20 +1,10 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./useTable"), exports);
-__exportStar(require("./types"), exports);
-__exportStar(require("./plugins"), exports);
-__exportStar(require("./strategies"), exports);
+exports.Plugins = exports.Strategies = exports.useTable = void 0;
+var useTable_1 = require("./useTable");
+Object.defineProperty(exports, "useTable", { enumerable: true, get: function () { return useTable_1.useTable; } });
+// Export namespace-like strategy collections
+var strategies_1 = require("./strategies");
+Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
+var plugins_1 = require("./plugins");
+Object.defineProperty(exports, "Plugins", { enumerable: true, get: function () { return plugins_1.Plugins; } });

package/dist/smartRow.js

@@ -122,16 +122,16 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         return resolve(config.cellSelector, rowLocator).nth(idx);
     };
     smart.toJSON = (options) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b;
+        var _a;
         const result = {};
         const page = rootLocator.page();
         for (const [col, idx] of map.entries()) {
             if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(col)) {
                 continue;
             }
-            // Check if we have a column override or data mapper for this column
+            // Check if we have a column override for this column
             const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col];
-            const mapper = (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) || ((_b = config.dataMapper) === null || _b === void 0 ? void 0 : _b[col]);
+            const mapper = columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read;
             if (mapper) {
                 // Use custom mapper
                 // Ensure we have the cell first (same navigation logic)

package/dist/strategies/index.d.ts

@@ -8,25 +8,23 @@ export * from './dedupe';
 export * from './loading';
 export declare const Strategies: {
     Pagination: {
-        clickNext: (nextButtonSelector: import("..").Selector, options?: {
-            stabilization?: import("./stabilization").StabilizationStrategy;
-            timeout?: number;
-        }) => import("..").PaginationStrategy;
         click: (selectors: {
             next?: import("..").Selector;
             previous?: import("..").Selector;
+            nextBulk?: import("..").Selector;
+            previousBulk?: import("..").Selector;
             first?: import("..").Selector;
         }, options?: {
             stabilization?: import("./stabilization").StabilizationStrategy;
             timeout?: number;
-        }) => import("..").PaginationStrategy;
+        }) => import("../types").PaginationStrategy;
         infiniteScroll: (options?: {
             action?: "scroll" | "js-scroll";
             scrollTarget?: import("..").Selector;
             scrollAmount?: number;
             stabilization?: import("./stabilization").StabilizationStrategy;
             timeout?: number;
-        }) => import("..").PaginationStrategy;
+        }) => import("../types").PaginationStrategy;
     };
     Sorting: {
         AriaSort: () => import("..").SortingStrategy;
@@ -35,21 +33,21 @@ export declare const Strategies: {
         default: () => Promise<void>;
     };
     Header: {
-        visible: ({ config, resolve, root }: import("..").StrategyContext) => Promise<string[]>;
+        visible: ({ config, resolve, root }: import("../types").StrategyContext) => Promise<string[]>;
     };
     Fill: {
-        default: ({ row, columnName, value, fillOptions, config, table }: Parameters<import("..").FillStrategy>[0]) => Promise<void>;
+        default: ({ row, columnName, value, fillOptions, config, table }: Parameters<import("../types").FillStrategy>[0]) => Promise<void>;
     };
     Resolution: {
         default: import("./resolution").ColumnResolutionStrategy;
     };
     Dedupe: {
-        byTopPosition: (tolerance?: number) => import("..").DedupeStrategy;
+        byTopPosition: (tolerance?: number) => import("../types").DedupeStrategy;
     };
     Loading: {
         Table: {
-            hasSpinner: (selector?: string) => ({ root }: import("..").TableContext) => Promise<boolean>;
-            custom: (fn: (context: import("..").TableContext) => Promise<boolean>) => (context: import("..").TableContext) => Promise<boolean>;
+            hasSpinner: (selector?: string) => ({ root }: import("../types").TableContext) => Promise<boolean>;
+            custom: (fn: (context: import("../types").TableContext) => Promise<boolean>) => (context: import("../types").TableContext) => Promise<boolean>;
             never: () => Promise<boolean>;
         };
         Row: {
@@ -59,7 +57,7 @@ export declare const Strategies: {
             never: () => Promise<boolean>;
         };
         Headers: {
-            stable: (duration?: number) => (context: import("..").TableContext) => Promise<boolean>;
+            stable: (duration?: number) => (context: import("../types").TableContext) => Promise<boolean>;
             never: () => Promise<boolean>;
         };
     };

package/dist/strategies/pagination.d.ts

@@ -1,27 +1,11 @@
 import type { PaginationStrategy, Selector } from '../types';
 import { StabilizationStrategy } from './stabilization';
 export declare const PaginationStrategies: {
-    /**
-     * Strategy: Clicks a "Next" button and waits for stabilization.
-     * Backward compatibility for when only a single 'next' selector was needed.
-     * @deprecated Use `click` with `{ next: selector }` instead.
-     */
-    clickNext: (nextButtonSelector: Selector, options?: {
-        stabilization?: StabilizationStrategy;
-        timeout?: number;
-    }) => PaginationStrategy;
-    /**
-     * Strategy: Classic Pagination Buttons.
-     * Clicks 'Next', 'Previous', or 'First' buttons and waits for stabilization.
-     *
-     * @param selectors Selectors for pagination buttons.
-     * @param options.stabilization Strategy to determine when the page has updated.
-     *        Defaults to `contentChanged({ scope: 'first' })`.
-     * @param options.timeout Timeout for the click action.
-     */
     click: (selectors: {
         next?: Selector;
         previous?: Selector;
+        nextBulk?: Selector;
+        previousBulk?: Selector;
         first?: Selector;
     }, options?: {
         stabilization?: StabilizationStrategy;

package/dist/strategies/pagination.js

@@ -12,23 +12,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PaginationStrategies = void 0;
 const stabilization_1 = require("./stabilization");
 exports.PaginationStrategies = {
-    /**
-     * Strategy: Clicks a "Next" button and waits for stabilization.
-     * Backward compatibility for when only a single 'next' selector was needed.
-     * @deprecated Use `click` with `{ next: selector }` instead.
-     */
-    clickNext: (nextButtonSelector, options = {}) => {
-        return exports.PaginationStrategies.click({ next: nextButtonSelector }, options);
-    },
-    /**
-     * Strategy: Classic Pagination Buttons.
-     * Clicks 'Next', 'Previous', or 'First' buttons and waits for stabilization.
-     *
-     * @param selectors Selectors for pagination buttons.
-     * @param options.stabilization Strategy to determine when the page has updated.
-     *        Defaults to `contentChanged({ scope: 'first' })`.
-     * @param options.timeout Timeout for the click action.
-     */
     click: (selectors, options = {}) => {
         var _a;
         const defaultStabilize = (_a = options.stabilization) !== null && _a !== void 0 ? _a : stabilization_1.StabilizationStrategies.contentChanged({ scope: 'first', timeout: options.timeout });
@@ -49,6 +32,8 @@ exports.PaginationStrategies = {
         return {
             goNext: createClicker(selectors.next),
             goPrevious: createClicker(selectors.previous),
+            goNextBulk: createClicker(selectors.nextBulk),
+            goPreviousBulk: createClicker(selectors.previousBulk),
             goToFirst: createClicker(selectors.first)
         };
     },

package/dist/strategies/sorting.js

@@ -23,44 +23,31 @@ exports.SortingStrategies = {
         return {
             doSort(_a) {
                 return __awaiter(this, arguments, void 0, function* ({ columnName, direction, context }) {
-                    const { resolve, config, root } = context;
-                    const headerLoc = resolve(config.headerSelector, root);
-                    const headers = yield headerLoc.all();
-                    const headerTexts = yield Promise.all(headers.map(h => h.innerText()));
-                    const columnIndex = headerTexts.findIndex(text => text.trim() === columnName);
-                    if (columnIndex === -1) {
-                        throw new Error(`[AriaSort] Header with text "${columnName}" not found.`);
-                    }
-                    const targetHeader = headers[columnIndex];
-                    // Click repeatedly to cycle through sort states
-                    for (let i = 0; i < 3; i++) { // Max 3 clicks to prevent infinite loops (none -> asc -> desc)
-                        const currentState = yield targetHeader.getAttribute('aria-sort');
-                        const mappedState = currentState === 'ascending' ? 'asc' : currentState === 'descending' ? 'desc' : 'none';
-                        if (mappedState === direction) {
-                            return; // Desired state achieved
-                        }
-                        yield targetHeader.click();
-                    }
-                    throw new Error(`[AriaSort] Could not achieve sort direction "${direction}" for column "${columnName}" after 3 clicks.`);
+                    const { getHeaderCell } = context;
+                    if (!getHeaderCell)
+                        throw new Error('getHeaderCell is required in StrategyContext for sorting.');
+                    // The table engine handles verify-and-retry. We only provide the trigger here.
+                    const targetHeader = yield getHeaderCell(columnName);
+                    yield targetHeader.click();
                 });
             },
             getSortState(_a) {
                 return __awaiter(this, arguments, void 0, function* ({ columnName, context }) {
-                    const { resolve, config, root } = context;
-                    const headerLoc = resolve(config.headerSelector, root);
-                    const headers = yield headerLoc.all();
-                    const headerTexts = yield Promise.all(headers.map(h => h.innerText()));
-                    const columnIndex = headerTexts.findIndex(text => text.trim() === columnName);
-                    if (columnIndex === -1) {
+                    const { getHeaderCell } = context;
+                    try {
+                        if (!getHeaderCell)
+                            throw new Error('getHeaderCell is required');
+                        const targetHeader = yield getHeaderCell(columnName);
+                        const ariaSort = yield targetHeader.getAttribute('aria-sort');
+                        if (ariaSort === 'ascending')
+                            return 'asc';
+                        if (ariaSort === 'descending')
+                            return 'desc';
+                        return 'none';
+                    }
+                    catch (_b) {
                         return 'none'; // Header not found, so it's not sorted
                     }
-                    const targetHeader = headers[columnIndex];
-                    const ariaSort = yield targetHeader.getAttribute('aria-sort');
-                    if (ariaSort === 'ascending')
-                        return 'asc';
-                    if (ariaSort === 'descending')
-                        return 'desc';
-                    return 'none';
                 });
             },
         };

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.js
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to specific page index (0-indexed) */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n}\n\nexport type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell. (Replaces dataMapper logic)\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: FilterValue };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n  isHeaderLoading?: (context: TableContext) => Promise<boolean>;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */\n  navigation?: NavigationPrimitives;\n\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /** Custom helper to check if a table is fully loaded/ready */\n  isTableLoaded?: (args: TableContext) => Promise<boolean>;\n  /** Custom helper to check if a row is fully loaded/ready */\n  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;\n  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */\n  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;\n  /** Strategy for detecting loading states */\n  loading?: LoadingStrategy;\n}\n\n\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n  /**\n   * @deprecated Use `columnOverrides` instead. `dataMapper` will be removed in v7.0.0.\n   * Custom data mappers for specific columns.\n   * Allows extracting complex data types (boolean, number) instead of just string.\n   */\n  dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;\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 * Options for generateConfigPrompt\n */\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  /**\n   * Include TypeScript type definitions in the prompt\n   * @default true\n   */\n  includeTypes?: boolean;\n}\n\n/** Callback context passed to forEach, map, and filter. */\nexport type RowIterationContext<T = any> = {\n  row: SmartRow<T>;\n  rowIndex: number;\n  stop: () => void;\n};\n\n/** Shared options for forEach, map, and filter. */\nexport type RowIterationOptions = {\n  /** Maximum number of pages to iterate. Defaults to config.maxPages. */\n  maxPages?: number;\n  /**\n   * Whether to process rows within a page concurrently.\n   * @default false for forEach/filter, true for map\n   */\n  parallel?: boolean;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * @example\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\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   * Scans a specific column across all pages and returns the values.\n   * @deprecated Use `table.map(({ row }) => row.getCell(column).innerText())` instead.\n   *             Will be removed in v7.0.0.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\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   * Iterates through paginated table data, calling the callback for each iteration.\n   * Callback return values are automatically appended to allData, which is returned.\n   * @deprecated Use `forEach`, `map`, or `filter` instead for cleaner cross-page iteration.\n   *             Only use this for advanced scenarios (batchSize, beforeFirst/afterLast hooks).\n   *             Will be removed in v7.0.0.\n   */\n  iterateThroughTable: <T = any>(\n    callback: (context: {\n      index: number;\n      isFirst: boolean;\n      isLast: boolean;\n      rows: SmartRowArray;\n      allData: T[];\n      table: RestrictedTableResult;\n      batchInfo?: {\n        startIndex: number;\n        endIndex: number;\n        size: number;\n      };\n\n    }) => T | T[] | Promise<T | T[]>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      batchSize?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      beforeFirst?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;\n      afterLast?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;\n      /**\n       * If true, flattens array results from callback into the main data array.\n       * If false (default), pushes the return value as-is (preserves batching/arrays).\n       */\n      autoFlatten?: boolean;\n    }\n  ) => Promise<T[]>;\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   */\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n}\n\n/**\n * Restricted table result that excludes methods that shouldn't be called during iteration.\n */\nexport type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;\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 * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n  /** Helper to reliably get a header cell locator by name */\n  getHeaderCell?: (headerName: string) => Promise<Locator>;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once */\n  goNextBulk?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip backward multiple pages at once */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to specific page index (0-indexed) */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n}\n\nexport type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell. (Replaces dataMapper logic)\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: FilterValue };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n  isHeaderLoading?: (context: TableContext) => Promise<boolean>;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */\n  navigation?: NavigationPrimitives;\n\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /** Custom helper to check if a table is fully loaded/ready */\n  isTableLoaded?: (args: TableContext) => Promise<boolean>;\n  /** Custom helper to check if a row is fully loaded/ready */\n  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;\n  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */\n  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;\n  /** Strategy for detecting loading states */\n  loading?: LoadingStrategy;\n}\n\n\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n\n  /**\n   * Unified interface for reading and writing data to specific columns.\n   * Overrides both default extraction (toJSON) and filling (smartFill) logic.\n   */\n  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;\n}\n\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: string | ((root: Locator) => Locator);\n  rowSelector: string;\n  cellSelector: string;\n  maxPages: number;\n  autoScroll: boolean;\n  debug?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\n\n\n/** Callback context passed to forEach, map, and filter. */\nexport type RowIterationContext<T = any> = {\n  row: SmartRow<T>;\n  rowIndex: number;\n  stop: () => void;\n};\n\n/** Shared options for forEach, map, and filter. */\nexport type RowIterationOptions = {\n  /** Maximum number of pages to iterate. Defaults to config.maxPages. */\n  maxPages?: number;\n  /**\n   * Whether to process rows within a page concurrently.\n   * @default false for forEach/filter, true for map\n   */\n  parallel?: boolean;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `parallel: true`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `{ parallel: false }` to avoid concurrent\n   * > interactions interfering with each other.\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 must use parallel: false\n   * const assignees = await table.map(async ({ row }) => {\n   *   await row.getCell('Assignee').locator('button').click();\n   *   const name = await page.locator('.popover .name').innerText();\n   *   await page.keyboard.press('Escape');\n   *   return name;\n   * }, { parallel: false });\n   */\n  map<R>(\n    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.\n   * Rows are returned as-is \u2014 call `bringIntoView()` on each if needed.\n   * Execution is sequential by default.\n   *\n   * @example\n   * const active = await table.filter(async ({ row }) =>\n   *   await row.getCell('Status').innerText() === 'Active'\n   * );\n   */\n  filter(\n    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,\n    options?: RowIterationOptions\n  ): Promise<SmartRowArray<T>>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   * Automatically throws an Error containing the prompt.\n   */\n  generateConfigPrompt: () => Promise<void>;\n}\n";

package/dist/typeContext.js

@@ -128,7 +128,12 @@ export type SmartRow<T = any> = Locator & {
   smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 
-export type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };
+export type StrategyContext = TableContext & {
+  rowLocator?: Locator;
+  rowIndex?: number;
+  /** Helper to reliably get a header cell locator by name */
+  getHeaderCell?: (headerName: string) => Promise<Locator>;
+};
 
 /**
  * Defines the contract for a sorting strategy.
@@ -191,6 +196,12 @@ 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 backward multiple pages at once */
+  goPreviousBulk?: (context: TableContext) => Promise<boolean>;
+
   /** Jump to first page / scroll to top */
   goToFirst?: (context: TableContext) => Promise<boolean>;
 
@@ -313,12 +324,6 @@ export interface TableConfig<T = any> {
   onReset?: (context: TableContext) => Promise<void>;
   /** All interaction strategies */
   strategies?: TableStrategies;
-  /**
-   * @deprecated Use \`columnOverrides\` instead. \`dataMapper\` will be removed in v7.0.0.
-   * Custom data mappers for specific columns.
-   * Allows extracting complex data types (boolean, number) instead of just string.
-   */
-  dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;
 
   /**
    * Unified interface for reading and writing data to specific columns.
@@ -348,22 +353,7 @@ export interface FillOptions {
   inputMappers?: Record<string, (cell: Locator) => Locator>;
 }
 
-/**
- * Options for generateConfigPrompt
- */
-export interface PromptOptions {
-  /**
-   * Output Strategy:
-   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
-   * - 'console': Standard console logs (Default).
-   */
-  output?: 'console' | 'error';
-  /**
-   * Include TypeScript type definitions in the prompt
-   * @default true
-   */
-  includeTypes?: boolean;
-}
+
 
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
@@ -491,8 +481,22 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * Execution is parallel within each page by default (safe for reads).
    * Call \`stop()\` to halt after the current page finishes.
    *
+   * > **⚠️ UI Interactions:** \`map\` defaults to \`parallel: true\`. If your callback opens popovers,
+   * > fills inputs, or otherwise mutates UI state, pass \`{ parallel: false }\` to avoid concurrent
+   * > interactions interfering with each other.
+   *
    * @example
+   * // Data extraction — parallel is safe
    * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
+   *
+   * @example
+   * // UI interactions — must use parallel: false
+   * const assignees = await table.map(async ({ row }) => {
+   *   await row.getCell('Assignee').locator('button').click();
+   *   const name = await page.locator('.popover .name').innerText();
+   *   await page.keyboard.press('Escape');
+   *   return name;
+   * }, { parallel: false });
    */
   map<R>(
     callback: (ctx: RowIterationContext<T>) => R | Promise<R>,
@@ -514,13 +518,6 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
     options?: RowIterationOptions
   ): Promise<SmartRowArray<T>>;
 
-  /**
-   * Scans a specific column across all pages and returns the values.
-   * @deprecated Use \`table.map(({ row }) => row.getCell(column).innerText())\` instead.
-   *             Will be removed in v7.0.0.
-   */
-  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;
-
   /**
    * Provides access to sorting actions and assertions.
    */
@@ -539,54 +536,11 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
     getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
   };
 
-  /**
-   * Iterates through paginated table data, calling the callback for each iteration.
-   * Callback return values are automatically appended to allData, which is returned.
-   * @deprecated Use \`forEach\`, \`map\`, or \`filter\` instead for cleaner cross-page iteration.
-   *             Only use this for advanced scenarios (batchSize, beforeFirst/afterLast hooks).
-   *             Will be removed in v7.0.0.
-   */
-  iterateThroughTable: <T = any>(
-    callback: (context: {
-      index: number;
-      isFirst: boolean;
-      isLast: boolean;
-      rows: SmartRowArray;
-      allData: T[];
-      table: RestrictedTableResult;
-      batchInfo?: {
-        startIndex: number;
-        endIndex: number;
-        size: number;
-      };
-
-    }) => T | T[] | Promise<T | T[]>,
-    options?: {
-      pagination?: PaginationStrategy;
-      dedupeStrategy?: DedupeStrategy;
-      maxIterations?: number;
-      batchSize?: number;
-      getIsFirst?: (context: { index: number }) => boolean;
-      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;
-      beforeFirst?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;
-      afterLast?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;
-      /**
-       * If true, flattens array results from callback into the main data array.
-       * If false (default), pushes the return value as-is (preserves batching/arrays).
-       */
-      autoFlatten?: boolean;
-    }
-  ) => Promise<T[]>;
-
   /**
    * Generate an AI-friendly configuration prompt for debugging.
    * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
+   * Automatically throws an Error containing the prompt.
    */
-  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
+  generateConfigPrompt: () => Promise<void>;
 }
-
-/**
- * Restricted table result that excludes methods that shouldn't be called during iteration.
- */
-export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;
 `;

package/dist/types.d.ts

@@ -114,6 +114,8 @@ export type SmartRow<T = any> = Locator & {
 export type StrategyContext = TableContext & {
     rowLocator?: Locator;
     rowIndex?: number;
+    /** Helper to reliably get a header cell locator by name */
+    getHeaderCell?: (headerName: string) => Promise<Locator>;
 };
 /**
  * Defines the contract for a sorting strategy.
@@ -170,6 +172,10 @@ 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>;
     /** Jump to first page / scroll to top */
     goToFirst?: (context: TableContext) => Promise<boolean>;
     /** Jump to specific page index (0-indexed) */
@@ -293,12 +299,6 @@ export interface TableConfig<T = any> {
     onReset?: (context: TableContext) => Promise<void>;
     /** All interaction strategies */
     strategies?: TableStrategies;
-    /**
-     * @deprecated Use `columnOverrides` instead. `dataMapper` will be removed in v7.0.0.
-     * Custom data mappers for specific columns.
-     * Allows extracting complex data types (boolean, number) instead of just string.
-     */
-    dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;
     /**
      * Unified interface for reading and writing data to specific columns.
      * Overrides both default extraction (toJSON) and filling (smartFill) logic.
@@ -328,22 +328,6 @@ export interface FillOptions {
      */
     inputMappers?: Record<string, (cell: Locator) => Locator>;
 }
-/**
- * Options for generateConfigPrompt
- */
-export interface PromptOptions {
-    /**
-     * Output Strategy:
-     * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
-     * - 'console': Standard console logs (Default).
-     */
-    output?: 'console' | 'error';
-    /**
-     * Include TypeScript type definitions in the prompt
-     * @default true
-     */
-    includeTypes?: boolean;
-}
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
     row: SmartRow<T>;
@@ -454,8 +438,22 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Execution is parallel within each page by default (safe for reads).
      * Call `stop()` to halt after the current page finishes.
      *
+     * > **⚠️ UI Interactions:** `map` defaults to `parallel: true`. If your callback opens popovers,
+     * > fills inputs, or otherwise mutates UI state, pass `{ parallel: false }` to avoid concurrent
+     * > interactions interfering with each other.
+     *
      * @example
+     * // Data extraction — parallel is safe
      * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
+     *
+     * @example
+     * // UI interactions — must use parallel: false
+     * const assignees = await table.map(async ({ row }) => {
+     *   await row.getCell('Assignee').locator('button').click();
+     *   const name = await page.locator('.popover .name').innerText();
+     *   await page.keyboard.press('Escape');
+     *   return name;
+     * }, { parallel: false });
      */
     map<R>(callback: (ctx: RowIterationContext<T>) => R | Promise<R>, options?: RowIterationOptions): Promise<R[]>;
     /**
@@ -469,15 +467,6 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * );
      */
     filter(predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>, options?: RowIterationOptions): Promise<SmartRowArray<T>>;
-    /**
-     * Scans a specific column across all pages and returns the values.
-     * @deprecated Use `table.map(({ row }) => row.getCell(column).innerText())` instead.
-     *             Will be removed in v7.0.0.
-     */
-    getColumnValues: <V = string>(column: string, options?: {
-        mapper?: (cell: Locator) => Promise<V> | V;
-        maxPages?: number;
-    }) => Promise<V[]>;
     /**
      * Provides access to sorting actions and assertions.
      */
@@ -495,60 +484,10 @@ export interface TableResult<T = any> extends AsyncIterable<{
          */
         getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
     };
-    /**
-     * Iterates through paginated table data, calling the callback for each iteration.
-     * Callback return values are automatically appended to allData, which is returned.
-     * @deprecated Use `forEach`, `map`, or `filter` instead for cleaner cross-page iteration.
-     *             Only use this for advanced scenarios (batchSize, beforeFirst/afterLast hooks).
-     *             Will be removed in v7.0.0.
-     */
-    iterateThroughTable: <T = any>(callback: (context: {
-        index: number;
-        isFirst: boolean;
-        isLast: boolean;
-        rows: SmartRowArray;
-        allData: T[];
-        table: RestrictedTableResult;
-        batchInfo?: {
-            startIndex: number;
-            endIndex: number;
-            size: number;
-        };
-    }) => T | T[] | Promise<T | T[]>, options?: {
-        pagination?: PaginationStrategy;
-        dedupeStrategy?: DedupeStrategy;
-        maxIterations?: number;
-        batchSize?: number;
-        getIsFirst?: (context: {
-            index: number;
-        }) => boolean;
-        getIsLast?: (context: {
-            index: number;
-            paginationResult: boolean;
-        }) => boolean;
-        beforeFirst?: (context: {
-            index: number;
-            rows: SmartRowArray;
-            allData: any[];
-        }) => void | Promise<void>;
-        afterLast?: (context: {
-            index: number;
-            rows: SmartRowArray;
-            allData: any[];
-        }) => void | Promise<void>;
-        /**
-         * If true, flattens array results from callback into the main data array.
-         * If false (default), pushes the return value as-is (preserves batching/arrays).
-         */
-        autoFlatten?: boolean;
-    }) => Promise<T[]>;
     /**
      * Generate an AI-friendly configuration prompt for debugging.
      * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
+     * Automatically throws an Error containing the prompt.
      */
-    generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
+    generateConfigPrompt: () => Promise<void>;
 }
-/**
- * Restricted table result that excludes methods that shouldn't be called during iteration.
- */
-export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;

package/dist/useTable.js

@@ -24,7 +24,6 @@ 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");
@@ -116,17 +115,11 @@ const useTable = (rootLocator, configOptions = {}) => {
             return clone.outerHTML;
         });
     });
-    const _handlePrompt = (promptName_1, content_1, ...args_1) => __awaiter(void 0, [promptName_1, content_1, ...args_1], void 0, function* (promptName, content, options = {}) {
-        const { output = 'console', includeTypes = true } = options;
+    const _handlePrompt = (promptName, content) => __awaiter(void 0, void 0, void 0, function* () {
         let finalPrompt = content;
-        if (includeTypes) {
-            finalPrompt += `\n\n👇 Useful TypeScript Definitions 👇\n\`\`\`typescript\n${minimalConfigContext_1.MINIMAL_CONFIG_CONTEXT}\n\`\`\`\n`;
-        }
-        if (output === 'error') {
-            console.log(`⚠️ Throwing error to display [${promptName}] cleanly...`);
-            throw new Error(finalPrompt);
-        }
-        console.log(finalPrompt);
+        finalPrompt += `\n\n👇 Useful TypeScript Definitions 👇\n\`\`\`typescript\n${minimalConfigContext_1.MINIMAL_CONFIG_CONTEXT}\n\`\`\`\n`;
+        console.log(`⚠️ Throwing error to display [${promptName}] cleanly...`);
+        throw new Error(finalPrompt);
     });
     const _ensureInitialized = () => __awaiter(void 0, void 0, void 0, function* () {
         yield tableMapper.getMap();
@@ -165,10 +158,19 @@ const useTable = (rootLocator, configOptions = {}) => {
             return resolve(config.headerSelector, rootLocator).nth(idx);
         }),
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
             log("Resetting table...");
             const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
             yield config.onReset(context);
+            if (typeof config.strategies.pagination !== 'function' && ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goToFirst)) {
+                log("Auto-navigating to first page...");
+                yield config.strategies.pagination.goToFirst(context);
+            }
+            else if (hasPaginationInConfig) {
+                log("No goToFirst strategy configured. Table may not be on page 1.");
+            }
             _hasPaginated = false;
+            tableState.currentPageIndex = 0;
             tableMapper.clear();
             log("Table reset complete.");
         }),
@@ -177,49 +179,6 @@ const useTable = (rootLocator, configOptions = {}) => {
             yield tableMapper.remapHeaders();
             log("Table revalidated.");
         }),
-        getColumnValues: (column, options) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a, _b;
-            const map = yield tableMapper.getMap();
-            const colIdx = map.get(column);
-            if (colIdx === undefined)
-                throw _createColumnError(column, map);
-            const mapper = (_a = options === null || options === void 0 ? void 0 : options.mapper) !== null && _a !== void 0 ? _a : ((c) => c.innerText());
-            const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages;
-            let pagesScanned = 1;
-            const results = [];
-            log(`Getting column values for '${column}' (Pages: ${effectiveMaxPages})`);
-            while (true) {
-                const rows = yield resolve(config.rowSelector, rootLocator).all();
-                for (const row of rows) {
-                    const cell = typeof config.cellSelector === 'string'
-                        ? row.locator(config.cellSelector).nth(colIdx)
-                        : resolve(config.cellSelector, row).nth(colIdx);
-                    results.push(yield mapper(cell));
-                }
-                if (pagesScanned < effectiveMaxPages) {
-                    const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                    let pageRes;
-                    if (typeof config.strategies.pagination === 'function') {
-                        pageRes = yield config.strategies.pagination(context);
-                    }
-                    else {
-                        if (!config.strategies.pagination.goNext) {
-                            log('Cannot paginate: no goNext primitive found.');
-                            break;
-                        }
-                        pageRes = yield config.strategies.pagination.goNext(context);
-                    }
-                    if (yield (0, validation_1.validatePaginationResult)(pageRes, 'Pagination Strategy')) {
-                        _hasPaginated = true;
-                        tableState.currentPageIndex++;
-                        pagesScanned++;
-                        continue;
-                    }
-                }
-                break;
-            }
-            return results;
-        }),
         getRow: (filters, options = { exact: false }) => {
             const map = tableMapper.getMapSync();
             if (!map)
@@ -248,18 +207,40 @@ const useTable = (rootLocator, configOptions = {}) => {
         },
         sorting: {
             apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
+                var _a;
                 yield _ensureInitialized();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
                 log(`Applying sort for column "${columnName}" (${direction})`);
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                yield config.strategies.sorting.doSort({ columnName, direction, context });
+                const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell };
+                const maxRetries = 3;
+                for (let i = 0; i < maxRetries; i++) {
+                    const currentState = yield config.strategies.sorting.getSortState({ columnName, context });
+                    if (currentState === direction) {
+                        log(`Sort for "${columnName}" is already "${direction}".`);
+                        return;
+                    }
+                    yield config.strategies.sorting.doSort({ columnName, direction, context });
+                    if ((_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isTableLoading) {
+                        yield config.strategies.loading.isTableLoading(context);
+                    }
+                    else {
+                        yield rootLocator.page().waitForTimeout(200);
+                    }
+                    yield (0, debugUtils_1.debugDelay)(config, 'default');
+                    const newState = yield config.strategies.sorting.getSortState({ columnName, context });
+                    if (newState === direction) {
+                        log(`Successfully sorted "${columnName}" to "${direction}".`);
+                        return;
+                    }
+                }
+                throw new Error(`Failed to sort column "${columnName}" to "${direction}" after ${maxRetries} attempts.`);
             }),
             getState: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
                 yield _ensureInitialized();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+                const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell };
                 return config.strategies.sorting.getSortState({ columnName, context });
             })
         },
@@ -297,12 +278,13 @@ 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 _ensureInitialized();
             const map = tableMapper.getMapSync();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-            const dedupeKeys = options.dedupe ? new Set() : null;
-            const parallel = (_b = options.parallel) !== null && _b !== void 0 ? _b : false;
+            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;
@@ -315,7 +297,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         if (stopped)
                             return;
                         if (dedupeKeys) {
-                            const key = yield options.dedupe(row);
+                            const key = yield dedupeStrategy(row);
                             if (dedupeKeys.has(key))
                                 return;
                             dedupeKeys.add(key);
@@ -328,7 +310,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         if (stopped)
                             break;
                         if (dedupeKeys) {
-                            const key = yield options.dedupe(row);
+                            const key = yield dedupeStrategy(row);
                             if (dedupeKeys.has(key))
                                 continue;
                             dedupeKeys.add(key);
@@ -345,7 +327,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     advanced = !!(yield config.strategies.pagination(context));
                 }
                 else {
-                    advanced = !!(((_c = config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNext) && (yield config.strategies.pagination.goNext(context)));
+                    advanced = !!(((_d = config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) && (yield config.strategies.pagination.goNext(context)));
                 }
                 if (!advanced)
                     break;
@@ -354,12 +336,13 @@ 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 _ensureInitialized();
             const map = tableMapper.getMapSync();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-            const dedupeKeys = options.dedupe ? new Set() : null;
-            const parallel = (_b = options.parallel) !== null && _b !== void 0 ? _b : true;
+            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 results = [];
             let rowIndex = 0;
             let stopped = false;
@@ -372,7 +355,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     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 options.dedupe(row);
+                            const key = yield dedupeStrategy(row);
                             if (dedupeKeys.has(key))
                                 return SKIP;
                             dedupeKeys.add(key);
@@ -389,7 +372,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         if (stopped)
                             break;
                         if (dedupeKeys) {
-                            const key = yield options.dedupe(row);
+                            const key = yield dedupeStrategy(row);
                             if (dedupeKeys.has(key))
                                 continue;
                             dedupeKeys.add(key);
@@ -406,7 +389,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     advanced = !!(yield config.strategies.pagination(context));
                 }
                 else {
-                    advanced = !!(((_c = config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNext) && (yield config.strategies.pagination.goNext(context)));
+                    advanced = !!(((_d = config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) && (yield config.strategies.pagination.goNext(context)));
                 }
                 if (!advanced)
                     break;
@@ -416,12 +399,13 @@ 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 _ensureInitialized();
             const map = tableMapper.getMapSync();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-            const dedupeKeys = options.dedupe ? new Set() : null;
-            const parallel = (_b = options.parallel) !== null && _b !== void 0 ? _b : false;
+            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 matched = [];
             let rowIndex = 0;
             let stopped = false;
@@ -433,7 +417,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 if (parallel) {
                     const flags = yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
                         if (dedupeKeys) {
-                            const key = yield options.dedupe(row);
+                            const key = yield dedupeStrategy(row);
                             if (dedupeKeys.has(key))
                                 return false;
                             dedupeKeys.add(key);
@@ -467,7 +451,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     advanced = !!(yield config.strategies.pagination(context));
                 }
                 else {
-                    advanced = !!(((_c = config.strategies.pagination) === null || _c === void 0 ? void 0 : _c.goNext) && (yield config.strategies.pagination.goNext(context)));
+                    advanced = !!(((_d = config.strategies.pagination) === null || _d === void 0 ? void 0 : _d.goNext) && (yield config.strategies.pagination.goNext(context)));
                 }
                 if (!advanced)
                     break;
@@ -476,208 +460,11 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return (0, smartRowArray_1.createSmartRowArray)(matched);
         }),
-        iterateThroughTable: (callback, options) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g;
-            yield _ensureInitialized();
-            const paginationStrategy = (_a = options === null || options === void 0 ? void 0 : options.pagination) !== null && _a !== void 0 ? _a : config.strategies.pagination;
-            const hasPaginationInOptions = (options === null || options === void 0 ? void 0 : options.pagination) !== undefined;
-            if (!hasPaginationInOptions && !hasPaginationInConfig)
-                throw new Error('No pagination strategy provided.');
-            yield result.reset();
-            yield result.init();
-            const map = tableMapper.getMapSync();
-            const restrictedTable = {
-                get currentPageIndex() { return tableState.currentPageIndex; },
-                init: result.init,
-                getHeaders: result.getHeaders,
-                getHeaderCell: result.getHeaderCell,
-                getRow: result.getRow,
-                getRowByIndex: result.getRowByIndex,
-                findRow: result.findRow,
-                findRows: result.findRows,
-                getColumnValues: result.getColumnValues,
-                isInitialized: result.isInitialized,
-                sorting: result.sorting,
-                scrollToColumn: result.scrollToColumn,
-                revalidate: result.revalidate,
-                generateConfigPrompt: result.generateConfigPrompt,
-                forEach: result.forEach,
-                map: result.map,
-                filter: result.filter,
-                [Symbol.asyncIterator]: result[Symbol.asyncIterator].bind(result),
-            };
-            const getIsFirst = (_b = options === null || options === void 0 ? void 0 : options.getIsFirst) !== null && _b !== void 0 ? _b : (({ index }) => index === 0);
-            const getIsLast = (_c = options === null || options === void 0 ? void 0 : options.getIsLast) !== null && _c !== void 0 ? _c : (() => false);
-            const allData = [];
-            const effectiveMaxIterations = (_d = options === null || options === void 0 ? void 0 : options.maxIterations) !== null && _d !== void 0 ? _d : config.maxPages;
-            const batchSize = options === null || options === void 0 ? void 0 : options.batchSize;
-            const isBatching = batchSize !== undefined && batchSize > 1;
-            const autoFlatten = (_e = options === null || options === void 0 ? void 0 : options.autoFlatten) !== null && _e !== void 0 ? _e : false;
-            let index = 0;
-            let paginationResult = true;
-            let seenKeys = null;
-            let batchRows = [];
-            let batchStartIndex = 0;
-            log(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations}, batchSize: ${batchSize !== null && batchSize !== void 0 ? batchSize : 'none'})`);
-            while (index < effectiveMaxIterations) {
-                const rowLocators = yield resolve(config.rowSelector, rootLocator).all();
-                const smartRowsArray = [];
-                const isRowLoading = (_f = config.strategies.loading) === null || _f === void 0 ? void 0 : _f.isRowLoading;
-                for (let i = 0; i < rowLocators.length; i++) {
-                    const smartRow = _makeSmart(rowLocators[i], map, i);
-                    if (isRowLoading && (yield isRowLoading(smartRow)))
-                        continue;
-                    smartRowsArray.push(smartRow);
-                }
-                let rows = (0, smartRowArray_1.createSmartRowArray)(smartRowsArray);
-                const dedupeStrategy = (_g = options === null || options === void 0 ? void 0 : options.dedupeStrategy) !== null && _g !== void 0 ? _g : config.strategies.dedupe;
-                if (dedupeStrategy && rows.length > 0) {
-                    if (!seenKeys)
-                        seenKeys = new Set();
-                    const deduplicated = [];
-                    for (const row of rows) {
-                        const key = yield dedupeStrategy(row);
-                        if (!seenKeys.has(key)) {
-                            seenKeys.add(key);
-                            deduplicated.push(row);
-                        }
-                    }
-                    rows = (0, smartRowArray_1.createSmartRowArray)(deduplicated);
-                    log(`Deduplicated ${rowLocators.length} rows to ${rows.length} unique rows (total seen: ${seenKeys.size})`);
-                }
-                // Add rows to batch if batching is enabled
-                if (isBatching) {
-                    batchRows.push(...rows);
-                }
-                const isLastIteration = index === effectiveMaxIterations - 1;
-                // Determine if we should invoke the callback
-                const batchComplete = isBatching && (index - batchStartIndex + 1) >= batchSize;
-                const shouldInvokeCallback = !isBatching || batchComplete || isLastIteration;
-                if (shouldInvokeCallback) {
-                    const callbackRows = isBatching ? batchRows : rows;
-                    const callbackIndex = isBatching ? batchStartIndex : index;
-                    const isFirst = getIsFirst({ index: callbackIndex });
-                    let isLast = getIsLast({ index: callbackIndex, paginationResult });
-                    const isLastDueToMax = index === effectiveMaxIterations - 1;
-                    if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
-                        yield options.beforeFirst({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(callbackRows), allData });
-                    }
-                    const batchInfo = isBatching ? {
-                        startIndex: batchStartIndex,
-                        endIndex: index,
-                        size: index - batchStartIndex + 1
-                    } : undefined;
-                    const returnValue = yield callback({
-                        index: callbackIndex,
-                        isFirst,
-                        isLast,
-                        rows: (0, smartRowArray_1.createSmartRowArray)(callbackRows),
-                        allData,
-                        table: restrictedTable,
-                        batchInfo
-                    });
-                    if (autoFlatten && Array.isArray(returnValue)) {
-                        allData.push(...returnValue);
-                    }
-                    else {
-                        allData.push(returnValue);
-                    }
-                    // Determine if this is truly the last iteration
-                    let finalIsLast = isLastDueToMax;
-                    if (!isLastIteration) {
-                        const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                        if (typeof paginationStrategy === 'function') {
-                            paginationResult = yield paginationStrategy(context);
-                        }
-                        else {
-                            const pageObj = paginationStrategy;
-                            if (!pageObj.goNext)
-                                break;
-                            paginationResult = yield pageObj.goNext(context);
-                        }
-                        (0, debugUtils_1.logDebug)(config, 'info', `Pagination ${paginationResult ? 'succeeded' : 'failed'}`);
-                        yield (0, debugUtils_1.debugDelay)(config, 'pagination');
-                        finalIsLast = getIsLast({ index: callbackIndex, paginationResult }) || !paginationResult;
-                        if (paginationResult)
-                            tableState.currentPageIndex++;
-                    }
-                    if (finalIsLast && (options === null || options === void 0 ? void 0 : options.afterLast)) {
-                        yield options.afterLast({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(callbackRows), allData });
-                    }
-                    if (finalIsLast || !paginationResult) {
-                        log(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
-                        break;
-                    }
-                    // Reset batch
-                    if (isBatching) {
-                        batchRows = [];
-                        batchStartIndex = index + 1;
-                    }
-                }
-                else {
-                    // Continue paginating even when batching
-                    const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                    if (typeof paginationStrategy === 'function') {
-                        paginationResult = yield paginationStrategy(context);
-                    }
-                    else {
-                        const pageObj = paginationStrategy;
-                        if (!pageObj.goNext) {
-                            log(`Cannot paginate: no goNext primitive found.`);
-                            break;
-                        }
-                        paginationResult = yield pageObj.goNext(context);
-                    }
-                    (0, debugUtils_1.logDebug)(config, 'info', `Pagination ${paginationResult ? 'succeeded' : 'failed'} (batching mode)`);
-                    yield (0, debugUtils_1.debugDelay)(config, 'pagination');
-                    if (paginationResult)
-                        tableState.currentPageIndex++;
-                    if (!paginationResult) {
-                        // Pagination failed, invoke callback with current batch
-                        const callbackIndex = batchStartIndex;
-                        const isFirst = getIsFirst({ index: callbackIndex });
-                        const isLast = true;
-                        if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
-                            yield options.beforeFirst({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(batchRows), allData });
-                        }
-                        const batchInfo = {
-                            startIndex: batchStartIndex,
-                            endIndex: index,
-                            size: index - batchStartIndex + 1
-                        };
-                        const returnValue = yield callback({
-                            index: callbackIndex,
-                            isFirst,
-                            isLast,
-                            rows: (0, smartRowArray_1.createSmartRowArray)(batchRows),
-                            allData,
-                            table: restrictedTable,
-                            batchInfo
-                        });
-                        if (autoFlatten && Array.isArray(returnValue)) {
-                            allData.push(...returnValue);
-                        }
-                        else {
-                            allData.push(returnValue);
-                        }
-                        if (options === null || options === void 0 ? void 0 : options.afterLast) {
-                            yield options.afterLast({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(batchRows), allData });
-                        }
-                        log(`Pagination failed mid-batch (index: ${index})`);
-                        break;
-                    }
-                }
-                index++;
-                log(`Iteration ${index} completed, continuing...`);
-            }
-            log(`iterateThroughTable completed after ${index + 1} iterations, collected ${allData.length} items`);
-            return allData;
-        }),
-        generateConfigPrompt: (options) => __awaiter(void 0, void 0, void 0, function* () {
+        generateConfigPrompt: () => __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, options);
+            yield _handlePrompt('Smart Table Config', content);
         }),
     };
     finalTable = result;

package/package.json

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