@rickcedwhat/playwright-smart-table 6.7.8 → 6.8.0

package/dist/smartRow.js

@@ -16,11 +16,12 @@ const paginationPath_1 = require("./utils/paginationPath");
 const sentinel_1 = require("./utils/sentinel");
 /**
  * Internal helper to navigate to a cell with active cell optimization.
- * Uses navigation primitives (goUp, goDown, goLeft, goRight, goHome) for orchestration.
+ * Uses `strategies.navigation` primitives (goUp/goDown/goLeft/goRight, optional snap/seek/goHome).
  * Returns the target cell locator after navigation.
  */
 const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function* () {
-    const { config, rootLocator, page, resolve, column, index, rowLocator, rowIndex } = params;
+    const { config, rootLocator, page, resolve, column, index, rowLocator, rowIndex, barrier } = params;
+    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: navigating to column "${column}" (index ${index})`);
     // Get active cell if strategy is available
     let activeCell = null;
     if (config.strategies.getActiveCell) {
@@ -43,70 +44,196 @@ const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function*
         if (typeof rowIndex !== 'number') {
             throw new Error('Row index is required for navigation');
         }
-        // Determine starting position
-        let startRow = 0;
-        let startCol = 0;
-        if (activeCell && activeCell.rowIndex >= 0 && activeCell.columnIndex >= 0) {
-            // Use current position
-            startRow = activeCell.rowIndex;
-            startCol = activeCell.columnIndex;
-        }
-        else if (nav.goHome) {
-            // Reset to top-left
-            yield nav.goHome(context);
-        }
-        // Calculate movement needed
-        const rowDiff = rowIndex - startRow;
-        const colDiff = index - startCol;
-        // Navigate vertically
-        for (let i = 0; i < Math.abs(rowDiff); i++) {
-            if (rowDiff > 0 && nav.goDown) {
+        const navigateOnce = () => __awaiter(void 0, void 0, void 0, function* () {
+            // Get current position again to be sure
+            let currRow = 0;
+            let currCol = 0;
+            if (config.strategies.getActiveCell) {
+                const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                if (ac) {
+                    currRow = ac.rowIndex;
+                    currCol = ac.columnIndex;
+                }
+            }
+            const rDiff = rowIndex - currRow;
+            const cDiff = index - currCol;
+            // Move one step vertically
+            if (rDiff > 0 && nav.goDown) {
                 (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving down');
                 yield nav.goDown(context);
             }
-            else if (rowDiff < 0 && nav.goUp) {
+            else if (rDiff < 0 && nav.goUp) {
                 (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving up');
                 yield nav.goUp(context);
             }
-        }
-        // Navigate horizontally
-        for (let i = 0; i < Math.abs(colDiff); i++) {
-            if (colDiff > 0 && nav.goRight) {
+            // Move one step horizontally
+            if (cDiff > 0 && nav.goRight) {
                 (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving right');
                 yield nav.goRight(context);
             }
-            else if (colDiff < 0 && nav.goLeft) {
+            else if (cDiff < 0 && nav.goLeft) {
                 (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: moving left');
                 yield nav.goLeft(context);
             }
+        });
+        const targetReached = () => __awaiter(void 0, void 0, void 0, function* () {
+            if (config.strategies.getActiveCell) {
+                const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                if (ac && ac.rowIndex === rowIndex && ac.columnIndex === index)
+                    return true;
+            }
+            // Locator presence: virtualized grids (e.g. Glide) often attach the target `td` after scroll
+            // while focus id lags; do not require getActiveCell to match for this to count as reached.
+            const cell = config.strategies.getCellLocator
+                ? config.strategies.getCellLocator({ row: rowLocator, columnName: column, columnIndex: index, page })
+                : resolve(config.cellSelector, rowLocator).nth(index);
+            return ((yield cell.count()) > 0);
+        });
+        if (yield targetReached()) {
+            // Already there. If we have a barrier, check-in to stay in lock-step.
+            if (barrier)
+                yield barrier.sync(index);
+            const cell = config.strategies.getCellLocator
+                ? config.strategies.getCellLocator({ row: rowLocator, columnName: column, columnIndex: index, page })
+                : resolve(config.cellSelector, rowLocator).nth(index);
+            return cell;
         }
-        // Wait for active cell to match target: poll getActiveCell or fallback to fixed delay
+        // If getActiveCell is present but returns null (no focus), and cell is in DOM,
+        // try to focus it once before entering navigation loop.
         if (config.strategies.getActiveCell) {
+            const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+            if (!ac) {
+                const cell = resolve(config.cellSelector, rowLocator).nth(index);
+                if ((yield cell.count()) > 0) {
+                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: cell "${column}" found but not focused; focusing.`);
+                    yield cell.focus();
+                    // Re-check target
+                    if (yield targetReached()) {
+                        if (barrier)
+                            yield barrier.sync(index);
+                        return cell;
+                    }
+                }
+            }
+        }
+        const navigateUntilReached = () => __awaiter(void 0, void 0, void 0, function* () {
+            let currRow = 0;
+            let currCol = 0;
+            if (config.strategies.getActiveCell) {
+                const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                if (ac) {
+                    currRow = ac.rowIndex;
+                    currCol = ac.columnIndex;
+                }
+            }
+            const rDiff = rowIndex - currRow;
+            // Navigate vertically (tight loop)
+            for (let i = 0; i < Math.abs(rDiff); i++) {
+                if (rDiff > 0 && nav.goDown)
+                    yield nav.goDown(context);
+                else if (rDiff < 0 && nav.goUp)
+                    yield nav.goUp(context);
+            }
+            if (config.strategies.getActiveCell) {
+                const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                if (ac) {
+                    currRow = ac.rowIndex;
+                    currCol = ac.columnIndex;
+                }
+            }
+            if (index === 0 && nav.snapFirstColumnIntoView) {
+                (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: snapFirstColumnIntoView for column index 0');
+                yield nav.snapFirstColumnIntoView(context);
+                if (config.strategies.getActiveCell) {
+                    const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                    if (ac) {
+                        currRow = ac.rowIndex;
+                        currCol = ac.columnIndex;
+                    }
+                }
+                // Home moves a11y focus within the current row to column 0. If focus row !== target row
+                // (e.g. still on previous row), Home jumps to grid origin and breaks `tr.nth(k)` reads.
+                if (typeof rowIndex === 'number' && currRow === rowIndex) {
+                    yield rootLocator.evaluate((el) => {
+                        var _a;
+                        const canvas = el.closest('canvas') || ((_a = el.parentElement) === null || _a === void 0 ? void 0 : _a.querySelector('canvas'));
+                        if (canvas instanceof HTMLCanvasElement) {
+                            canvas.tabIndex = 0;
+                            canvas.focus();
+                        }
+                    });
+                    yield page.keyboard.press('Home');
+                    yield page.waitForTimeout(120);
+                    if (config.strategies.getActiveCell) {
+                        const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                        if (ac) {
+                            currRow = ac.rowIndex;
+                            currCol = ac.columnIndex;
+                        }
+                    }
+                }
+            }
+            let cDiff = index - currCol;
+            if (Math.abs(cDiff) > 12 && nav.seekColumnIndex) {
+                (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: seekColumnIndex approx for column ${index}`);
+                yield nav.seekColumnIndex(context, index);
+                if (config.strategies.getActiveCell) {
+                    const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                    if (ac) {
+                        currRow = ac.rowIndex;
+                        currCol = ac.columnIndex;
+                    }
+                }
+                cDiff = index - currCol;
+            }
+            for (let i = 0; i < Math.abs(cDiff); i++) {
+                if (cDiff > 0 && nav.goRight)
+                    yield nav.goRight(context);
+                else if (cDiff < 0 && nav.goLeft)
+                    yield nav.goLeft(context);
+            }
+            const horizontalSteps = Math.abs(cDiff);
+            if (horizontalSteps > 0) {
+                const settleMs = Math.min(2500, 60 + horizontalSteps * 12);
+                yield page.waitForTimeout(settleMs);
+            }
+            // Wait for active cell to match target: poll getActiveCell or fallback to fixed delay
+            // This is the "Midas Touch" buffer needed for Glide's async accessibility updates.
             const pollIntervalMs = 10;
-            const maxWaitMs = 50;
+            const maxWaitMs = Math.min(6000, 250 + horizontalSteps * 25);
             const start = Date.now();
             while (Date.now() - start < maxWaitMs) {
-                const updatedActiveCell = yield config.strategies.getActiveCell({
-                    config,
-                    root: rootLocator,
-                    page,
-                    resolve
-                });
-                if (updatedActiveCell && updatedActiveCell.rowIndex === rowIndex && updatedActiveCell.columnIndex === index) {
-                    return updatedActiveCell.locator;
+                if (config.strategies.getActiveCell) {
+                    const ac = yield config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
+                    if (ac && ac.rowIndex === rowIndex && ac.columnIndex === index) {
+                        return ac.locator;
+                    }
+                }
+                if (yield targetReached()) {
+                    break;
                 }
                 yield page.waitForTimeout(pollIntervalMs);
             }
-            const final = yield config.strategies.getActiveCell({
-                config,
-                root: rootLocator,
-                page,
-                resolve
-            });
-            if (final)
-                return final.locator;
-            return null;
+        });
+        // Not there, perform (coordinated) navigation
+        let navResult;
+        if (barrier) {
+            navResult = yield barrier.sync(index, navigateUntilReached);
         }
+        else {
+            navResult = yield navigateUntilReached();
+        }
+        if (navResult instanceof Object && navResult._isLocator) {
+            const loc = navResult;
+            if ((yield loc.count()) > 0)
+                return loc;
+        }
+        // Return final locator if reached
+        const finalCell = config.strategies.getCellLocator
+            ? config.strategies.getCellLocator({ row: rowLocator, columnName: column, columnIndex: index, page })
+            : resolve(config.cellSelector, rowLocator).nth(index);
+        if ((yield finalCell.count()) > 0)
+            return finalCell;
         return null;
     }
     return null;
@@ -119,12 +246,13 @@ const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function*
  * @internal Internal factory for creating SmartRow objects.
  * Not part of the public package surface; tests and consumers should use public APIs.
  */
-const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex) => {
+const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex, barrier) => {
     const smart = rowLocator;
     // Attach State
     smart.rowIndex = rowIndex;
     smart.tablePageIndex = tablePageIndex;
     smart.table = table;
+    smart._barrier = barrier;
     // Attach Methods
     smart.getCell = (colName) => {
         const idx = map.get(colName);
@@ -177,22 +305,21 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 })
                 : resolve(config.cellSelector, rowLocator).nth(idx);
             let targetCell = cell;
-            const count = yield cell.count();
-            if (count === 0) {
-                // Cell not in DOM (virtualized) - navigate to it
-                const navigatedCell = yield _navigateToCell({
-                    config,
-                    rootLocator,
-                    page,
-                    resolve,
-                    column: col,
-                    index: idx,
-                    rowLocator,
-                    rowIndex
-                });
-                if (navigatedCell) {
-                    targetCell = navigatedCell;
-                }
+            // Always call _navigateToCell to ensure Lock-Step synchronization
+            // even if the cell is already present (it handles check-in inside)
+            const navigatedCell = yield _navigateToCell({
+                config,
+                rootLocator,
+                page,
+                resolve,
+                column: col,
+                index: idx,
+                rowLocator,
+                rowIndex,
+                barrier: smart._barrier
+            });
+            if (navigatedCell) {
+                targetCell = navigatedCell;
             }
             // --- Navigation Logic End ---
             // Call beforeCellRead hook if configured.
@@ -239,7 +366,8 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 column: colName,
                 index: colIdx,
                 rowLocator,
-                rowIndex
+                rowIndex,
+                barrier: smart._barrier
             });
             const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[colName];
             if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) {

package/dist/strategies/columns.d.ts

@@ -10,6 +10,17 @@ export interface NavigationPrimitives {
     goLeft?: (context: StrategyContext) => Promise<void>;
     goRight?: (context: StrategyContext) => Promise<void>;
     goHome?: (context: StrategyContext) => Promise<void>;
+    /**
+     * After vertical moves, run before horizontal steps when the target column index is 0.
+     * Use for horizontally virtualized a11y tables (e.g. Glide) so `td[aria-colindex="1"]` exists again.
+     * Do not reset vertical scroll here — RDG-style `goHome` is often unsuitable.
+     */
+    snapFirstColumnIntoView?: (context: StrategyContext) => Promise<void>;
+    /**
+     * Coarse horizontal reposition before goLeft/goRight steps (virtualized a11y grids).
+     * Implementations should leave a small delta for the caller to correct with primitives.
+     */
+    seekColumnIndex?: (context: StrategyContext, columnIndex: number) => Promise<void>;
 }
 /**
  * @deprecated Use NavigationPrimitives instead. This will be removed in a future version.

package/dist/strategies/fill.js

@@ -21,7 +21,7 @@ exports.FillStrategies = {
         const columnOverride = (_b = config === null || config === void 0 ? void 0 : config.columnOverrides) === null || _b === void 0 ? void 0 : _b[columnName];
         if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) {
             let currentValue;
-            // Auto-sync: If read exists, fetch current state first
+            // Auto-sync: If read exists, get current state first
             if (columnOverride.read) {
                 currentValue = yield columnOverride.read(cell);
             }

package/dist/typeContext.d.ts

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

package/dist/typeContext.js

@@ -370,6 +370,11 @@ export interface TableConfig<T = any> {
   cellSelector?: string | ((row: Locator) => Locator);
   /** Number of pages to scan for verification */
   maxPages?: number;
+  /**
+   * Default concurrency strategy for iteration methods.
+   * Can be overridden by the options passed to forEach, map, or filter.
+   */
+  concurrency?: RowIterationMode;
   /** Hook to rename columns dynamically */
   headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;
   /** Automatically scroll to table on init */
@@ -394,6 +399,7 @@ export interface FinalTableConfig<T = any> extends TableConfig<T> {
   cellSelector: string | ((row: Locator) => Locator);
   maxPages: number;
   autoScroll: boolean;
+  concurrency?: RowIterationMode;
   debug?: TableConfig['debug'];
   headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;
   onReset: (context: TableContext) => Promise<void>;
@@ -418,15 +424,27 @@ export type RowIterationContext<T = any> = {
   stop: () => void;
 };
 
+/** Concurrency modes for row iteration. */
+export type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';
+
 /** Shared options for forEach, map, and filter. */
 export type RowIterationOptions = {
   /** Maximum number of pages to iterate. Defaults to config.maxPages. */
   maxPages?: number;
   /**
-   * Whether to process rows within a page concurrently.
-   * @default false for forEach/filter, true for map
+   * @deprecated Use 'concurrency' mode instead.
+   * - parallel: true -> concurrency: 'parallel'
+   * - parallel: false -> concurrency: 'sequential'
    */
   parallel?: boolean;
+  /**
+   * Concurrency strategy for iteration.
+   * - 'parallel': Full parallel execution of both navigation and actions.
+   * - 'synchronized': Parallel navigation (lock-step) with serial actions.
+   * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.
+   * @default 'parallel' (for map), 'sequential' (for forEach/filter)
+   */
+  concurrency?: RowIterationMode;
   /**
    * Deduplication strategy. Use when rows may repeat across iterations
    * (e.g. infinite scroll tables). Returns a unique key per row.
@@ -526,6 +544,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * Execution is sequential by default (safe for interactions like clicking/filling).
    * Call \`stop()\` in the callback to end iteration early.
    *
+   * @param callback - Function receiving { row, rowIndex, stop }
+   * @param options - maxPages, concurrency, dedupe, useBulkPagination (\`parallel\` is deprecated; use \`concurrency\`)
+   *
    * @example
    * await table.forEach(async ({ row, stop }) => {
    *   if (await row.getCell('Status').innerText() === 'Done') stop();
@@ -542,22 +563,25 @@ 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.
+   * > **⚠️ UI Interactions:** \`map\` defaults to \`concurrency: 'parallel'\`. If your callback opens popovers,
+   * > fills inputs, or otherwise mutates UI state, pass \`concurrency: 'sequential'\` (or \`'synchronized'\`
+   * > when navigation must stay lock-step) to avoid overlapping interactions.
+   *
+   * @param callback - Function receiving { row, rowIndex, stop }
+   * @param options - maxPages, concurrency, dedupe, useBulkPagination (\`parallel\` is deprecated; use \`concurrency\`)
    *
    * @example
    * // Data extraction — parallel is safe
    * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
    *
    * @example
-   * // UI interactions — must use parallel: false
+   * // UI interactions — use sequential (or synchronized) concurrency
    * 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 });
+   * }, { concurrency: 'sequential' });
    */
   map<R>(
     callback: (ctx: RowIterationContext<T>) => R | Promise<R>,
@@ -569,6 +593,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * Rows are returned as-is — call \`bringIntoView()\` on each if needed.
    * Execution is sequential by default.
    *
+   * @param predicate - Function receiving { row, rowIndex, stop }
+   * @param options - maxPages, concurrency, dedupe, useBulkPagination (\`parallel\` is deprecated; use \`concurrency\`)
+   *
    * @example
    * const active = await table.filter(async ({ row }) =>
    *   await row.getCell('Status').innerText() === 'Active'