@rickcedwhat/playwright-smart-table 6.4.0 → 6.6.0

package/README.md

@@ -106,6 +106,14 @@ const allActive = await table.findRows({ Status: 'Active' });
 - ❌ You don't need to find a row based on a value in a cell
 - ❌ You don't need to find a cell based on a value in another cell in the same row
 
+### ⚠️ Important Note on Pagination & Interactions
+
+When using `findRows` across multiple pages, the returned `SmartRow` locators represent elements that may no longer be attached to the current DOM if the table paginated past them.
+
+- **Data Extraction:** Safe. You can use `table.iterateThroughTable()` to extract data (`await row.toJSON()`) while the row is visible.
+- **Interactions:** Unsafe directly. You cannot do `await row.click()` if the row is on Page 1 but the table is currently showing Page 3. 
+- **Solution:** If you need to interact with a row found on a previous page, you may be able to use `await row.bringIntoView()` before interacting with it to force the table to paginate back to that row (Note: this specific cross-page interaction flow is currently under testing).
+
 ## Documentation
 
 **📚 Full documentation available at: https://rickcedwhat.github.io/playwright-smart-table/**

package/dist/engine/rowFinder.d.ts

@@ -9,8 +9,11 @@ export declare class RowFinder<T = any> {
     private filterEngine;
     private tableMapper;
     private makeSmartRow;
+    private tableState;
     private resolve;
-    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number) => SmartRow<T>);
+    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number, tablePageIndex?: number) => SmartRow<T>, tableState?: {
+        currentPageIndex: number;
+    });
     private log;
     findRow(filters: Record<string, FilterValue>, options?: {
         exact?: boolean;

package/dist/engine/rowFinder.js

@@ -25,12 +25,13 @@ const debugUtils_1 = require("../utils/debugUtils");
 const smartRowArray_1 = require("../utils/smartRowArray");
 const validation_1 = require("../strategies/validation");
 class RowFinder {
-    constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow) {
+    constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow, tableState = { currentPageIndex: 0 }) {
         this.rootLocator = rootLocator;
         this.config = config;
         this.filterEngine = filterEngine;
         this.tableMapper = tableMapper;
         this.makeSmartRow = makeSmartRow;
+        this.tableState = tableState;
         this.resolve = resolve;
     }
     log(msg) {
@@ -82,7 +83,7 @@ class RowFinder {
             const map = yield this.tableMapper.getMap();
             const allRows = [];
             const effectiveMaxPages = (_b = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
-            let pageCount = 0;
+            let pagesScanned = 1;
             const collectMatches = () => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b;
                 // ... logic ...
@@ -94,7 +95,7 @@ class RowFinder {
                 const currentRows = yield rowLocators.all();
                 const isRowLoading = (_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isRowLoading;
                 for (let i = 0; i < currentRows.length; i++) {
-                    const smartRow = this.makeSmartRow(currentRows[i], map, allRows.length + i);
+                    const smartRow = this.makeSmartRow(currentRows[i], map, allRows.length + i, this.tableState.currentPageIndex);
                     if (isRowLoading && (yield isRowLoading(smartRow)))
                         continue;
                     allRows.push(smartRow);
@@ -105,7 +106,7 @@ class RowFinder {
             // Pagination Loop - Corrected logic
             // We always scan at least 1 page.
             // If maxPages > 1, and we have a pagination strategy, we try to go next.
-            while (pageCount < effectiveMaxPages - 1 && this.config.strategies.pagination) {
+            while (pagesScanned < effectiveMaxPages && this.config.strategies.pagination) {
                 const context = {
                     root: this.rootLocator,
                     config: this.config,
@@ -113,11 +114,22 @@ class RowFinder {
                     page: this.rootLocator.page()
                 };
                 // Check if we should stop? (e.g. if we found enough rows? No, findRows finds ALL)
-                const paginationResult = yield this.config.strategies.pagination(context);
+                let paginationResult;
+                if (typeof this.config.strategies.pagination === 'function') {
+                    paginationResult = yield this.config.strategies.pagination(context);
+                }
+                else {
+                    // It's a PaginationPrimitives object, use goNext by default for findRows
+                    if (!this.config.strategies.pagination.goNext) {
+                        break; // Cannot paginate forward
+                    }
+                    paginationResult = yield this.config.strategies.pagination.goNext(context);
+                }
                 const didPaginate = yield (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                 if (!didPaginate)
                     break;
-                pageCount++;
+                this.tableState.currentPageIndex++;
+                pagesScanned++;
                 // Wait for reload logic if needed? Usually pagination handles it.
                 yield collectMatches();
             }
@@ -129,7 +141,7 @@ class RowFinder {
             var _a, _b;
             const map = yield this.tableMapper.getMap();
             const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages;
-            let currentPage = 1;
+            let pagesScanned = 1;
             this.log(`Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
             while (true) {
                 // Check Loading
@@ -149,40 +161,51 @@ class RowFinder {
                 const allRows = this.resolve(this.config.rowSelector, this.rootLocator);
                 const matchedRows = this.filterEngine.applyFilters(allRows, filters, map, options.exact || false, this.rootLocator.page());
                 const count = yield matchedRows.count();
-                this.log(`Page ${currentPage}: Found ${count} matches.`);
+                this.log(`Page ${this.tableState.currentPageIndex}: Found ${count} matches.`);
                 if (count > 1) {
                     const sampleData = [];
                     try {
                         const firstFewRows = yield matchedRows.all();
                         const sampleCount = Math.min(firstFewRows.length, 3);
                         for (let i = 0; i < sampleCount; i++) {
-                            const rowData = yield this.makeSmartRow(firstFewRows[i], map, 0).toJSON();
+                            const rowData = yield this.makeSmartRow(firstFewRows[i], map, 0, this.tableState.currentPageIndex).toJSON();
                             sampleData.push(JSON.stringify(rowData));
                         }
                     }
                     catch (e) { }
                     const sampleMsg = sampleData.length > 0 ? `\nSample matching rows:\n${sampleData.map((d, i) => `  ${i + 1}. ${d}`).join('\n')}` : '';
-                    throw new Error(`Ambiguous Row: Found ${count} rows matching ${JSON.stringify(filters)} on page ${currentPage}. ` +
+                    throw new Error(`Ambiguous Row: Found ${count} rows matching ${JSON.stringify(filters)} on page ${this.tableState.currentPageIndex}. ` +
                         `Expected exactly one match. Try adding more filters to make your query unique.${sampleMsg}`);
                 }
                 if (count === 1)
                     return matchedRows.first();
-                if (currentPage < effectiveMaxPages) {
-                    this.log(`Page ${currentPage}: Not found. Attempting pagination...`);
+                if (pagesScanned < effectiveMaxPages) {
+                    this.log(`Page ${this.tableState.currentPageIndex}: Not found. Attempting pagination...`);
                     const context = {
                         root: this.rootLocator,
                         config: this.config,
                         resolve: this.resolve,
                         page: this.rootLocator.page()
                     };
-                    const paginationResult = yield this.config.strategies.pagination(context);
+                    let paginationResult;
+                    if (typeof this.config.strategies.pagination === 'function') {
+                        paginationResult = yield this.config.strategies.pagination(context);
+                    }
+                    else {
+                        if (!this.config.strategies.pagination.goNext) {
+                            this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (no goNext primitive).`);
+                            return null;
+                        }
+                        paginationResult = yield this.config.strategies.pagination.goNext(context);
+                    }
                     const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                     if (didLoadMore) {
-                        currentPage++;
+                        this.tableState.currentPageIndex++;
+                        pagesScanned++;
                         continue;
                     }
                     else {
-                        this.log(`Page ${currentPage}: Pagination failed (end of data).`);
+                        this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (end of data).`);
                     }
                 }
                 return null;

package/dist/filterEngine.js

@@ -25,10 +25,15 @@ class FilterEngine {
             // But for now, we implement the default logic or use custom if we add it to config later
             // Default Filter Logic
             const cellTemplate = this.resolve(this.config.cellSelector, page);
-            // This logic assumes 1:1 row-to-cell mapping based on index.
-            // filter({ has: ... }) checks if the row *contains* the matching cell.
-            // But we need to be specific about WHICH cell.
-            // Locator filtering by `has: locator.nth(index)` works if `locator` search is relative to the row.
+            // ⚠️ CRITICAL WARNING: DO NOT "FIX" OR REFACTOR THIS LOGIC. ⚠️
+            // At first glance, `cellTemplate.nth(colIndex)` looks like a global page selector 
+            // that will return the Nth cell on the entire page, rather than the Nth cell in the row.
+            // THIS IS INTENTIONAL AND CORRECT. 
+            // Playwright deeply understands nested locator scoping. When this global-looking locator 
+            // is passed into `filtered.filter({ has: ... })` below, Playwright magically and 
+            // automatically re-bases the `nth()` selector to be strictly relative to the ROW being evaluated.
+            // Attempting to manually force generic relative locators here will break complex function 
+            // selectors and introduce regressions. Leave it as is.
             const targetCell = cellTemplate.nth(colIndex);
             if (typeof filterVal === 'function') {
                 // Locator-based filter: (cell) => cell.locator(...)

package/dist/smartRow.d.ts

@@ -4,4 +4,4 @@ import { SmartRow as SmartRowType, FinalTableConfig, TableResult } from './types
  * Factory to create a SmartRow by extending a Playwright Locator.
  * We avoid Class/Proxy to ensure full compatibility with Playwright's expect(locator) matchers.
  */
-export declare const createSmartRow: <T = any>(rowLocator: Locator, map: Map<string, number>, rowIndex: number | undefined, config: FinalTableConfig<T>, rootLocator: Locator, resolve: (item: any, parent: Locator | Page) => Locator, table: TableResult<T> | null) => SmartRowType<T>;
+export declare const createSmartRow: <T = any>(rowLocator: Locator, map: Map<string, number>, rowIndex: number | undefined, config: FinalTableConfig<T>, rootLocator: Locator, resolve: (item: any, parent: Locator | Page) => Locator, table: TableResult<T> | null, tablePageIndex?: number) => SmartRowType<T>;

package/dist/smartRow.js

@@ -98,10 +98,12 @@ const _navigateToCell = (params) => __awaiter(void 0, void 0, void 0, function*
  * Factory to create a SmartRow by extending a Playwright Locator.
  * We avoid Class/Proxy to ensure full compatibility with Playwright's expect(locator) matchers.
  */
-const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table) => {
+const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex) => {
     const smart = rowLocator;
     // Attach State
     smart.rowIndex = rowIndex;
+    smart.tablePageIndex = tablePageIndex;
+    smart.table = table;
     // Attach Methods
     smart.getCell = (colName) => {
         const idx = map.get(colName);
@@ -120,15 +122,16 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         return resolve(config.cellSelector, rowLocator).nth(idx);
     };
     smart.toJSON = (options) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a;
+        var _a, _b;
         const result = {};
         const page = rootLocator.page();
         for (const [col, idx] of map.entries()) {
             if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(col)) {
                 continue;
             }
-            // Check if we have a data mapper for this column
-            const mapper = (_a = config.dataMapper) === null || _a === void 0 ? void 0 : _a[col];
+            // Check if we have a column override or data mapper for this column
+            const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col];
+            const mapper = (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) || ((_b = config.dataMapper) === null || _b === void 0 ? void 0 : _b[col]);
             if (mapper) {
                 // Use custom mapper
                 // Ensure we have the cell first (same navigation logic)
@@ -206,6 +209,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 index: rowIndex !== null && rowIndex !== void 0 ? rowIndex : -1,
                 page: rowLocator.page(),
                 rootLocator,
+                config,
                 table: table,
                 fillOptions
             });
@@ -218,6 +222,47 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         if (rowIndex === undefined) {
             throw new Error('Cannot bring row into view - row index is unknown. Use getRowByIndex() instead of getRow().');
         }
+        const parentTable = smart.table;
+        // Cross-page Navigation using PaginationPrimitives
+        if (tablePageIndex !== undefined && config.strategies.pagination) {
+            const primitives = config.strategies.pagination;
+            // Only orchestrate if it's an object of primitives, not a single function
+            if (typeof config.strategies.pagination !== 'function') {
+                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+                if (primitives.goToPage) {
+                    (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Jumping to page ${tablePageIndex} using goToPage primitive`);
+                    yield primitives.goToPage(tablePageIndex, context);
+                }
+                else if (primitives.goPrevious) {
+                    (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Looping goPrevious until we reach page ${tablePageIndex}`);
+                    const diff = parentTable.currentPageIndex - tablePageIndex;
+                    for (let i = 0; i < diff; i++) {
+                        const success = yield primitives.goPrevious(context);
+                        if (!success) {
+                            throw new Error(`bringIntoView: Failed to paginate backwards. Strategy aborted before reaching page ${tablePageIndex}.`);
+                        }
+                    }
+                }
+                else if (primitives.goToFirst && primitives.goNext) {
+                    (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: going to first page and looping goNext until we reach page ${tablePageIndex}`);
+                    yield primitives.goToFirst(context);
+                    for (let i = 0; i < tablePageIndex; i++) {
+                        yield primitives.goNext(context);
+                    }
+                }
+                else {
+                    (0, debugUtils_1.logDebug)(config, 'error', `Cannot bring row on page ${tablePageIndex} into view. No backwards pagination strategies (goToPage, goPrevious, or goToFirst) provided.`);
+                    throw new Error(`Cannot bring row on page ${tablePageIndex} into view: Row is on a different page and no backward pagination primitive found.`);
+                }
+            }
+            else {
+                throw new Error(`Cannot bring row on page ${tablePageIndex} into view: Pagination is a single function. Provide an object with 'goPrevious', 'goToPage', or 'goToFirst' primitives.`);
+            }
+            // Successfully orchestrated backwards navigation, now update the state pointer
+            parentTable.currentPageIndex = tablePageIndex;
+        }
+        // Delay after pagination/finding before scrolling
+        yield (0, debugUtils_1.debugDelay)(config, 'findRow');
         // Scroll row into view using Playwright's built-in method
         yield rowLocator.scrollIntoViewIfNeeded();
     });

package/dist/strategies/fill.d.ts

@@ -3,5 +3,5 @@ export declare const FillStrategies: {
     /**
      * Default strategy: Detects input type and fills accordingly (Text, Select, Checkbox, ContentEditable).
      */
-    default: ({ row, columnName, value, fillOptions }: Parameters<FillStrategy>[0]) => Promise<void>;
+    default: ({ row, columnName, value, fillOptions, config, table }: Parameters<FillStrategy>[0]) => Promise<void>;
 };

package/dist/strategies/fill.js

@@ -14,12 +14,28 @@ exports.FillStrategies = {
     /**
      * Default strategy: Detects input type and fills accordingly (Text, Select, Checkbox, ContentEditable).
      */
-    default: (_a) => __awaiter(void 0, [_a], void 0, function* ({ row, columnName, value, fillOptions }) {
-        var _b;
+    default: (_a) => __awaiter(void 0, [_a], void 0, function* ({ row, columnName, value, fillOptions, config, table }) {
+        var _b, _c;
         const cell = row.getCell(columnName);
+        // 1. Check for Unified Column Override
+        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
+            if (columnOverride.read) {
+                currentValue = yield columnOverride.read(cell);
+            }
+            yield columnOverride.write({
+                cell,
+                targetValue: value,
+                currentValue,
+                row
+            });
+            return;
+        }
         // Use custom input mapper for this column if provided, otherwise auto-detect
         let inputLocator;
-        if ((_b = fillOptions === null || fillOptions === void 0 ? void 0 : fillOptions.inputMappers) === null || _b === void 0 ? void 0 : _b[columnName]) {
+        if ((_c = fillOptions === null || fillOptions === void 0 ? void 0 : fillOptions.inputMappers) === null || _c === void 0 ? void 0 : _c[columnName]) {
             inputLocator = fillOptions.inputMappers[columnName](cell);
         }
         else {

package/dist/strategies/index.d.ts

@@ -12,6 +12,14 @@ export declare const Strategies: {
             stabilization?: import("./stabilization").StabilizationStrategy;
             timeout?: number;
         }) => import("..").PaginationStrategy;
+        click: (selectors: {
+            next?: import("..").Selector;
+            previous?: import("..").Selector;
+            first?: import("..").Selector;
+        }, options?: {
+            stabilization?: import("./stabilization").StabilizationStrategy;
+            timeout?: number;
+        }) => import("..").PaginationStrategy;
         infiniteScroll: (options?: {
             action?: "scroll" | "js-scroll";
             scrollTarget?: import("..").Selector;
@@ -30,7 +38,7 @@ export declare const Strategies: {
         visible: ({ config, resolve, root }: import("..").StrategyContext) => Promise<string[]>;
     };
     Fill: {
-        default: ({ row, columnName, value, fillOptions }: Parameters<import("..").FillStrategy>[0]) => Promise<void>;
+        default: ({ row, columnName, value, fillOptions, config, table }: Parameters<import("..").FillStrategy>[0]) => Promise<void>;
     };
     Resolution: {
         default: import("./resolution").ColumnResolutionStrategy;

package/dist/strategies/pagination.d.ts

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

package/dist/strategies/pagination.js

@@ -14,27 +14,43 @@ const stabilization_1 = require("./stabilization");
 exports.PaginationStrategies = {
     /**
      * Strategy: Clicks a "Next" button and waits for stabilization.
-     * @param nextButtonSelector Selector for the next page button.
+     * Backward compatibility for when only a single 'next' selector was needed.
+     * @deprecated Use `click` with `{ next: selector }` instead.
+     */
+    clickNext: (nextButtonSelector, options = {}) => {
+        return exports.PaginationStrategies.click({ next: nextButtonSelector }, options);
+    },
+    /**
+     * Strategy: Classic Pagination Buttons.
+     * Clicks 'Next', 'Previous', or 'First' buttons and waits for stabilization.
+     *
+     * @param selectors Selectors for pagination buttons.
      * @param options.stabilization Strategy to determine when the page has updated.
      *        Defaults to `contentChanged({ scope: 'first' })`.
      * @param options.timeout Timeout for the click action.
      */
-    clickNext: (nextButtonSelector, options = {}) => {
-        return (context) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a;
-            const { root, resolve, page } = context;
-            const nextBtn = resolve(nextButtonSelector, root).first();
-            if (!(yield nextBtn.isVisible()) || !(yield nextBtn.isEnabled())) {
-                return false;
-            }
-            // Default stabilization: Wait for first row content to change
-            const stabilization = (_a = options.stabilization) !== null && _a !== void 0 ? _a : stabilization_1.StabilizationStrategies.contentChanged({ scope: 'first', timeout: options.timeout });
-            // Stabilization: Wrap action
-            const success = yield stabilization(context, () => __awaiter(void 0, void 0, void 0, function* () {
-                yield nextBtn.click({ timeout: 2000 }).catch(() => { });
-            }));
-            return success;
-        });
+    click: (selectors, options = {}) => {
+        var _a;
+        const defaultStabilize = (_a = options.stabilization) !== null && _a !== void 0 ? _a : stabilization_1.StabilizationStrategies.contentChanged({ scope: 'first', timeout: options.timeout });
+        const createClicker = (selector) => {
+            if (!selector)
+                return undefined;
+            return (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const { root, resolve } = context;
+                const btn = resolve(selector, root).first();
+                if (!btn || !(yield btn.isVisible()) || !(yield btn.isEnabled())) {
+                    return false;
+                }
+                return yield defaultStabilize(context, () => __awaiter(void 0, void 0, void 0, function* () {
+                    yield btn.click({ timeout: 2000 }).catch(() => { });
+                }));
+            });
+        };
+        return {
+            goNext: createClicker(selectors.next),
+            goPrevious: createClicker(selectors.previous),
+            goToFirst: createClicker(selectors.first)
+        };
     },
     /**
      * Strategy: Infinite Scroll (generic).
@@ -48,32 +64,38 @@ exports.PaginationStrategies = {
      *        Use `contentChanged` for virtualization.
      */
     infiniteScroll: (options = {}) => {
-        return (context) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a, _b;
-            const { root, resolve, page } = context;
-            const scrollTarget = options.scrollTarget
-                ? resolve(options.scrollTarget, root)
-                : root;
-            // Default stabilization: Wait for row count to increase (Append mode)
-            const stabilization = (_a = options.stabilization) !== null && _a !== void 0 ? _a : stabilization_1.StabilizationStrategies.rowCountIncreased({ timeout: options.timeout });
-            const amount = (_b = options.scrollAmount) !== null && _b !== void 0 ? _b : 500;
-            const doScroll = () => __awaiter(void 0, void 0, void 0, function* () {
-                const box = yield scrollTarget.boundingBox();
-                // Action: Scroll
-                if (options.action === 'js-scroll' || !box) {
-                    yield scrollTarget.evaluate((el, y) => {
-                        el.scrollTop += y;
-                    }, amount);
-                }
-                else {
-                    // Mouse Wheel
-                    yield page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
-                    yield page.mouse.wheel(0, amount);
-                }
+        var _a, _b;
+        // Default stabilization: Wait for row count to increase (Append mode)
+        const stabilization = (_a = options.stabilization) !== null && _a !== void 0 ? _a : stabilization_1.StabilizationStrategies.rowCountIncreased({ timeout: options.timeout });
+        const amount = (_b = options.scrollAmount) !== null && _b !== void 0 ? _b : 500;
+        const createScroller = (directionMultiplier) => {
+            return (context) => __awaiter(void 0, void 0, void 0, function* () {
+                const { root, resolve, page } = context;
+                const scrollTarget = options.scrollTarget
+                    ? resolve(options.scrollTarget, root)
+                    : root;
+                const doScroll = () => __awaiter(void 0, void 0, void 0, function* () {
+                    const box = yield scrollTarget.boundingBox();
+                    const scrollValue = amount * directionMultiplier;
+                    // Action: Scroll
+                    if (options.action === 'js-scroll' || !box) {
+                        yield scrollTarget.evaluate((el, y) => {
+                            el.scrollTop += y;
+                        }, scrollValue);
+                    }
+                    else {
+                        // Mouse Wheel
+                        yield page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+                        yield page.mouse.wheel(0, scrollValue);
+                    }
+                });
+                // Stabilization: Wait
+                return yield stabilization(context, doScroll);
             });
-            // Stabilization: Wait
-            const success = yield stabilization(context, doScroll);
-            return success;
-        });
+        };
+        return {
+            goNext: createScroller(1),
+            goPrevious: createScroller(-1)
+        };
     }
 };

package/dist/typeContext.d.ts

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