@rickcedwhat/playwright-smart-table 6.8.2 → 6.10.0

package/dist/strategies/stabilization.js

@@ -1,13 +1,4 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StabilizationStrategies = void 0;
 exports.StabilizationStrategies = {
@@ -15,77 +6,77 @@ exports.StabilizationStrategies = {
      * Waits for the visible text of the table rows to change.
      */
     contentChanged: (options = {}) => {
-        return (_a, action_1) => __awaiter(void 0, [_a, action_1], void 0, function* ({ root, config, resolve, page }, action) {
-            var _b, _c;
+        return async ({ root, config, resolve, page }, action) => {
+            var _a, _b;
             const rows = resolve(config.rowSelector, root);
-            const timeout = (_b = options.timeout) !== null && _b !== void 0 ? _b : 5000;
-            const scope = (_c = options.scope) !== null && _c !== void 0 ? _c : 'all';
+            const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : 5000;
+            const scope = (_b = options.scope) !== null && _b !== void 0 ? _b : 'all';
             // Helper to get fingerprint
-            const getFingerprint = () => __awaiter(void 0, void 0, void 0, function* () {
+            const getFingerprint = async () => {
                 if (scope === 'first') {
-                    return yield rows.first().innerText().catch(() => '');
+                    return await rows.first().innerText().catch(() => '');
                 }
-                const allText = yield rows.allInnerTexts();
+                const allText = await rows.allInnerTexts();
                 return allText.join('|');
-            });
+            };
             // 1. Capture Before
-            const beforeFingerprint = yield getFingerprint();
+            const beforeFingerprint = await getFingerprint();
             // 2. Perform Action
-            yield action();
+            await action();
             // 3. Wait for Change
             const startTime = Date.now();
             while (Date.now() - startTime < timeout) {
-                const afterFingerprint = yield getFingerprint();
+                const afterFingerprint = await getFingerprint();
                 if (afterFingerprint !== beforeFingerprint) {
                     return true;
                 }
-                yield page.waitForTimeout(100);
+                await page.waitForTimeout(100);
             }
             return false;
-        });
+        };
     },
     /**
      * Waits for the total number of rows to strictly increase.
      */
     rowCountIncreased: (options = {}) => {
-        return (_a, action_1) => __awaiter(void 0, [_a, action_1], void 0, function* ({ root, config, resolve, page }, action) {
-            var _b;
+        return async ({ root, config, resolve, page }, action) => {
+            var _a;
             const rows = resolve(config.rowSelector, root);
-            const timeout = (_b = options.timeout) !== null && _b !== void 0 ? _b : 5000;
-            const beforeCount = yield rows.count();
-            yield action();
+            const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : 5000;
+            const beforeCount = await rows.count();
+            await action();
             const startTime = Date.now();
             while (Date.now() - startTime < timeout) {
-                const afterCount = yield rows.count();
+                const afterCount = await rows.count();
                 if (afterCount > beforeCount) {
                     return true;
                 }
-                yield page.waitForTimeout(100);
+                await page.waitForTimeout(100);
             }
             return false;
-        });
+        };
     },
     /**
      * Waits for a specific network condition or spinner to disappear.
      * Useful for tables that have explicit loading states but might not change content immediately.
      */
     networkIdle: (options = {}) => {
-        return (_a) => __awaiter(void 0, [_a], void 0, function* ({ root, page, resolve }) {
-            var _b;
-            const timeout = (_b = options.timeout) !== null && _b !== void 0 ? _b : 5000;
+        return async ({ root, page, resolve }) => {
+            var _a;
+            const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : 5000;
             if (options.spinnerSelector) {
                 const spinner = resolve(options.spinnerSelector, root);
                 try {
-                    yield spinner.waitFor({ state: 'detached', timeout });
+                    await spinner.waitFor({ state: 'detached', timeout });
                     return true;
                 }
-                catch (_c) {
+                catch (_b) {
                     return false;
                 }
             }
             // Fallback to simple wait if no selector
-            yield page.waitForTimeout(500);
+            await page.waitForTimeout(500);
             return true;
-        });
+        };
     }
 };

package/dist/strategies/viewport.d.ts

@@ -0,0 +1,52 @@
+import { ViewportStrategy } from '../types';
+export type DataAttributeViewportOptions = {
+    /**
+     * CSS selector for the scroll container (the element with overflow: auto/scroll).
+     * Resolved with `closest()` from the root element, so ancestors are found automatically.
+     * Defaults to 'div[class*="overflow-auto"]'.
+     */
+    scrollContainer?: string;
+    /**
+     * Milliseconds to wait for cells to appear in the DOM after a column scroll.
+     * Defaults to 3000.
+     */
+    attachTimeout?: number;
+    /**
+     * DOM attribute on row elements that holds the row index.
+     * Defaults to 'data-index'. Use 'aria-rowindex' for ARIA grids.
+     */
+    rowAttribute?: string;
+    /**
+     * DOM attribute on cell elements that holds the column index.
+     * Defaults to 'data-index'. Use 'aria-colindex' for ARIA grids.
+     */
+    columnAttribute?: string;
+    /**
+     * Estimated row height used when the target virtualized row is not mounted.
+     * If omitted, the strategy infers it from visible rows and falls back to 40px.
+     */
+    rowHeight?: number;
+    /**
+     * Estimated column width used when the target virtualized header is not mounted.
+     * If omitted, the strategy infers it from visible headers/cells and falls back to 120px.
+     */
+    columnWidth?: number;
+    /**
+     * Pixel padding applied when jumping to an estimated row or column position.
+     * Defaults to 20.
+     */
+    scrollPadding?: number;
+    /**
+     * Value subtracted from the attribute to get the 0-based row index.
+     * Defaults to 0. Use 1 for 'aria-rowindex' which is 1-based.
+     */
+    rowOffset?: number;
+    /**
+     * Value subtracted from the attribute to get the 0-based column index.
+     * Defaults to 0. Use 1 for 'aria-colindex' which is 1-based.
+     */
+    columnOffset?: number;
+};
+export declare const ViewportStrategies: {
+    dataAttribute: (options?: DataAttributeViewportOptions) => ViewportStrategy;
+};

package/dist/strategies/viewport.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewportStrategies = void 0;
+/**
+ * Viewport strategies for tables where row and cell elements carry a DOM attribute
+ * equal to their index (e.g. Braintrust logs table, TanStack-style grids).
+ *
+ * Derives selectors from the table config so no duplication is needed:
+ *   - getVisibleColumnRange — reads column attribute from cells in the first visible row
+ *   - getVisibleRowRange   — reads row attribute from all visible row elements
+ *   - scrollToColumn       — aligns header's left edge to container left, waits for cell mount
+ *   - scrollToRow          — scrolls row into view, waits for row mount
+ *
+ * @example
+ * // TanStack / Braintrust (data-index, 0-based — default)
+ * viewport: Strategies.Viewport.dataAttribute()
+ *
+ * @example
+ * // ARIA grid (aria-rowindex / aria-colindex, 1-based)
+ * viewport: Strategies.Viewport.dataAttribute({ rowAttribute: 'aria-rowindex', columnAttribute: 'aria-colindex', rowOffset: 1, columnOffset: 1 })
+ */
+const dataAttribute = (options) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const containerSel = (_a = options === null || options === void 0 ? void 0 : options.scrollContainer) !== null && _a !== void 0 ? _a : 'div[class*="overflow-auto"]';
+    const attachTimeout = (_b = options === null || options === void 0 ? void 0 : options.attachTimeout) !== null && _b !== void 0 ? _b : 3000;
+    const rowAttr = (_c = options === null || options === void 0 ? void 0 : options.rowAttribute) !== null && _c !== void 0 ? _c : 'data-index';
+    const colAttr = (_d = options === null || options === void 0 ? void 0 : options.columnAttribute) !== null && _d !== void 0 ? _d : 'data-index';
+    const rowOffset = (_e = options === null || options === void 0 ? void 0 : options.rowOffset) !== null && _e !== void 0 ? _e : 0;
+    const colOffset = (_f = options === null || options === void 0 ? void 0 : options.columnOffset) !== null && _f !== void 0 ? _f : 0;
+    const rowHeight = options === null || options === void 0 ? void 0 : options.rowHeight;
+    const columnWidth = options === null || options === void 0 ? void 0 : options.columnWidth;
+    const scrollPadding = (_g = options === null || options === void 0 ? void 0 : options.scrollPadding) !== null && _g !== void 0 ? _g : 20;
+    return {
+        getVisibleColumnRange: async ({ root, config }) => {
+            const rowSel = config.rowSelector;
+            const cellSel = typeof config.cellSelector === 'string' ? config.cellSelector : `[${colAttr}]`;
+            return root.evaluate((el, { rowSel, cellSel, colAttr, colOffset }) => {
+                const firstRow = el.querySelector(rowSel);
+                if (!firstRow)
+                    return { first: 0, last: 0 };
+                const indices = Array.from(firstRow.querySelectorAll(cellSel))
+                    .map(c => Number(c.getAttribute(colAttr)) - colOffset)
+                    .filter(n => !isNaN(n));
+                if (!indices.length)
+                    return { first: 0, last: 0 };
+                return { first: Math.min(...indices), last: Math.max(...indices) };
+            }, { rowSel, cellSel, colAttr, colOffset });
+        },
+        getVisibleRowRange: async ({ root, config }) => {
+            const rowSel = config.rowSelector;
+            return root.evaluate((el, { rowSel, rowAttr, rowOffset }) => {
+                const indices = Array.from(el.querySelectorAll(rowSel))
+                    .map(r => Number(r.getAttribute(rowAttr)) - rowOffset)
+                    .filter(n => !isNaN(n));
+                if (!indices.length)
+                    return { first: 0, last: 0 };
+                return { first: Math.min(...indices), last: Math.max(...indices) };
+            }, { rowSel, rowAttr, rowOffset });
+        },
+        scrollToColumn: async ({ root, config }, colIndex) => {
+            const headerSel = typeof config.headerSelector === 'string' ? config.headerSelector : null;
+            const cellSel = typeof config.cellSelector === 'string' ? config.cellSelector : `[${colAttr}]`;
+            await root.evaluate((el, { containerSel, headerSel, cellSel, idx, columnWidth, scrollPadding }) => {
+                const container = el.closest(containerSel);
+                if (!container || !headerSel)
+                    return;
+                const headers = Array.from(el.querySelectorAll(headerSel));
+                const target = headers[idx];
+                if (!target) {
+                    const widthSources = headers.length ? headers : Array.from(el.querySelectorAll(cellSel));
+                    const widths = widthSources
+                        .map(node => node.getBoundingClientRect().width)
+                        .filter(width => width > 0);
+                    const estimatedWidth = columnWidth !== null && columnWidth !== void 0 ? columnWidth : (widths.length
+                        ? widths.reduce((sum, width) => sum + width, 0) / widths.length
+                        : 120);
+                    container.scrollLeft = Math.max(0, idx * estimatedWidth - scrollPadding);
+                    return;
+                }
+                const cRect = container.getBoundingClientRect();
+                const tRect = target.getBoundingClientRect();
+                if (tRect.left < cRect.left) {
+                    // Scrolling left: reveal the target's left edge with padding.
+                    container.scrollLeft -= (cRect.left - tRect.left) + scrollPadding;
+                }
+                else if (tRect.right > cRect.right) {
+                    // Scrolling right: reveal the target's right edge with padding.
+                    container.scrollLeft += (tRect.right - cRect.right) + scrollPadding;
+                }
+            }, { containerSel, headerSel, cellSel, idx: colIndex, columnWidth, scrollPadding });
+            // Wait for a cell at this column index to mount in any row
+            await root
+                .locator(`${config.rowSelector} [${colAttr}="${colIndex + colOffset}"]`)
+                .first()
+                .waitFor({ state: 'attached', timeout: attachTimeout });
+        },
+        scrollToRow: async ({ root, config }, rowIndex) => {
+            const rowSel = config.rowSelector;
+            await root.evaluate((el, { containerSel, rowSel, rowAttr, idx, rowOffset, rowHeight, scrollPadding }) => {
+                const container = el.closest(containerSel);
+                if (!container)
+                    return;
+                const row = container.querySelector(`${rowSel}[${rowAttr}="${idx + rowOffset}"]`);
+                if (row) {
+                    row.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+                    return;
+                }
+                const visibleRows = Array.from(container.querySelectorAll(rowSel));
+                const heights = visibleRows
+                    .map(visibleRow => visibleRow.getBoundingClientRect().height)
+                    .filter(height => height > 0);
+                const estimatedHeight = rowHeight !== null && rowHeight !== void 0 ? rowHeight : (heights.length
+                    ? heights.reduce((sum, height) => sum + height, 0) / heights.length
+                    : 40);
+                container.scrollTop = Math.max(0, idx * estimatedHeight - scrollPadding);
+            }, { containerSel, rowSel, rowAttr, idx: rowIndex, rowOffset, rowHeight, scrollPadding });
+            await root
+                .locator(`${rowSel}[${rowAttr}="${rowIndex + rowOffset}"]`)
+                .waitFor({ state: 'attached', timeout: attachTimeout });
+        },
+    };
+};
+exports.ViewportStrategies = { dataAttribute };

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  /**\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";
+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  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */\n  root: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n  config: FinalTableConfig<any>;\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 * Viewport oracle strategies for virtualized tables.\n *\n * These tell the library *what is currently in the DOM* rather than *how to move*.\n * When present, the cell-reading engine uses them to jump directly to a target\n * row/column instead of stepping blindly with navigation primitives.\n *\n * This is the primary fix for the 2D scroll hazard: scrolling right to bring a\n * column into view can knock rows out of the vertical viewport (and vice versa).\n * With `getVisibleRowRange` the engine detects this and calls `scrollToRow` to\n * restore the row before reading \u2014 eliminating the hazard without polling loops.\n *\n * All members are optional. Supply whichever the underlying grid exposes:\n * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.\n * - Scroll primitives alone enable direct jumps without range awareness.\n * - Both together give the most reliable, fastest path.\n *\n * @example\n * // MUI DataGrid via apiRef\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const api = (el as any).__muiDataGrid__;\n *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };\n *       }),\n *     scrollToRow: async ({ root }, rowIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),\n *     scrollToColumn: async ({ root }, colIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),\n *   }\n * }\n *\n * @example\n * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const rows = [...el.querySelectorAll('[role=\"row\"][aria-rowindex]')];\n *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);\n *         return { first: Math.min(...idxs), last: Math.max(...idxs) };\n *       }),\n *   }\n * }\n */\nexport interface ViewportStrategy {\n  /**\n   * Returns the 0-based index range of rows currently rendered in the DOM.\n   * Used to detect when a target row has been scrolled out of view and needs recovery.\n   */\n  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Returns the 0-based index range of columns currently rendered in the DOM.\n   * Used to detect when a target column is not yet mounted before reading.\n   */\n  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Scrolls or jumps directly to make a row visible by 0-based index.\n   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.\n   */\n  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;\n\n  /**\n   * Scrolls or jumps directly to make a column visible by 0-based index.\n   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.\n   */\n  scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;\n\n  /**\n   * When true, disables the automatic memoization of getVisibleColumnRange and\n   * getVisibleRowRange results. By default the library caches each range value and\n   * invalidates it after the corresponding scroll call, eliminating redundant DOM\n   * evaluate() round-trips between scrolls.\n   */\n  disableCache?: boolean;\n}\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   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,\n   * Braintrust-style grids where both rows and columns are virtualized simultaneously).\n   *\n   * When present, the cell-reading engine uses these to jump directly to the target\n   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can\n   * knock rows out of the vertical viewport, and vice versa).\n   *\n   * Completely optional and additive \u2014 existing `navigation` primitives remain the fallback.\n   */\n  viewport?: ViewportStrategy;\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   * 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\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\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\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

@@ -37,10 +37,13 @@ export type FilterValue = string | RegExp | number | ((cell: Locator) => Locator
  */
 export type GetCellLocatorFn = (args: {
   row: Locator;
+  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */
+  root: Locator;
   columnName: string;
   columnIndex: number;
   rowIndex?: number;
   page: Page;
+  config: FinalTableConfig<any>;
 }) => Locator;
 
 /**
@@ -80,6 +83,88 @@ export type GetActiveCellFn = (args: TableContext) => Promise<{
   locator: Locator;
 } | null>;
 
+/**
+ * Viewport oracle strategies for virtualized tables.
+ *
+ * These tell the library *what is currently in the DOM* rather than *how to move*.
+ * When present, the cell-reading engine uses them to jump directly to a target
+ * row/column instead of stepping blindly with navigation primitives.
+ *
+ * This is the primary fix for the 2D scroll hazard: scrolling right to bring a
+ * column into view can knock rows out of the vertical viewport (and vice versa).
+ * With \`getVisibleRowRange\` the engine detects this and calls \`scrollToRow\` to
+ * restore the row before reading — eliminating the hazard without polling loops.
+ *
+ * All members are optional. Supply whichever the underlying grid exposes:
+ * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.
+ * - Scroll primitives alone enable direct jumps without range awareness.
+ * - Both together give the most reliable, fastest path.
+ *
+ * @example
+ * // MUI DataGrid via apiRef
+ * strategies: {
+ *   viewport: {
+ *     getVisibleRowRange: async ({ root }) =>
+ *       root.evaluate(el => {
+ *         const api = (el as any).__muiDataGrid__;
+ *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };
+ *       }),
+ *     scrollToRow: async ({ root }, rowIndex) =>
+ *       root.evaluate((el, idx) =>
+ *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),
+ *     scrollToColumn: async ({ root }, colIndex) =>
+ *       root.evaluate((el, idx) =>
+ *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),
+ *   }
+ * }
+ *
+ * @example
+ * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)
+ * strategies: {
+ *   viewport: {
+ *     getVisibleRowRange: async ({ root }) =>
+ *       root.evaluate(el => {
+ *         const rows = [...el.querySelectorAll('[role="row"][aria-rowindex]')];
+ *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);
+ *         return { first: Math.min(...idxs), last: Math.max(...idxs) };
+ *       }),
+ *   }
+ * }
+ */
+export interface ViewportStrategy {
+  /**
+   * Returns the 0-based index range of rows currently rendered in the DOM.
+   * Used to detect when a target row has been scrolled out of view and needs recovery.
+   */
+  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;
+
+  /**
+   * Returns the 0-based index range of columns currently rendered in the DOM.
+   * Used to detect when a target column is not yet mounted before reading.
+   */
+  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;
+
+  /**
+   * Scrolls or jumps directly to make a row visible by 0-based index.
+   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.
+   */
+  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;
+
+  /**
+   * Scrolls or jumps directly to make a column visible by 0-based index.
+   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.
+   */
+  scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;
+
+  /**
+   * When true, disables the automatic memoization of getVisibleColumnRange and
+   * getVisibleRowRange results. By default the library caches each range value and
+   * invalidates it after the corresponding scroll call, eliminating redundant DOM
+   * evaluate() round-trips between scrolls.
+   */
+  disableCache?: boolean;
+}
+
 
 /**
  * SmartRow - A Playwright Locator with table-aware methods.
@@ -358,6 +443,18 @@ export interface TableStrategies {
    * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.
    */
   loading?: LoadingStrategy;
+
+  /**
+   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
+   * Braintrust-style grids where both rows and columns are virtualized simultaneously).
+   *
+   * When present, the cell-reading engine uses these to jump directly to the target
+   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can
+   * knock rows out of the vertical viewport, and vice versa).
+   *
+   * Completely optional and additive — existing \`navigation\` primitives remain the fallback.
+   */
+  viewport?: ViewportStrategy;
 }
 
 
@@ -431,12 +528,6 @@ export type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';
 export type RowIterationOptions = {
   /** Maximum number of pages to iterate. Defaults to config.maxPages. */
   maxPages?: number;
-  /**
-   * @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.
@@ -545,7 +636,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * 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\`)
+   * @param options - maxPages, concurrency, dedupe, useBulkPagination
    *
    * @example
    * await table.forEach(async ({ row, stop }) => {
@@ -568,7 +659,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * > 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\`)
+   * @param options - maxPages, concurrency, dedupe, useBulkPagination
    *
    * @example
    * // Data extraction — parallel is safe
@@ -594,7 +685,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * Execution is sequential by default.
    *
    * @param predicate - Function receiving { row, rowIndex, stop }
-   * @param options - maxPages, concurrency, dedupe, useBulkPagination (\`parallel\` is deprecated; use \`concurrency\`)
+   * @param options - maxPages, concurrency, dedupe, useBulkPagination
    *
    * @example
    * const active = await table.filter(async ({ row }) =>