@rickcedwhat/playwright-smart-table 6.7.3 → 6.7.5

package/dist/typeContext.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TYPE_CONTEXT = void 0;
 /**
  * 🤖 AUTO-GENERATED FILE. DO NOT EDIT.
- * This file is generated by scripts/embed-types.js
+ * This file is generated by scripts/embed-types.mjs
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
 exports.TYPE_CONTEXT = `
@@ -240,11 +240,21 @@ export interface PaginationPrimitives {
   /** Jump to first page / scroll to top */
   goToFirst?: (context: TableContext) => Promise<boolean>;
 
-  /** Jump to specific page index (0-indexed) */
+  /**
+   * Jump to specific page index (0-indexed).
+   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6–14).
+   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.
+   */
   goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
+
+  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */
+  nextBulkPages?: number;
+
+  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
+  previousBulkPages?: number;
 }
 
-export type PaginationStrategy = ((context: TableContext) => Promise<boolean | number>) | PaginationPrimitives;
+export type PaginationStrategy = PaginationPrimitives;
 
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 
@@ -288,7 +298,8 @@ export type { HeaderStrategy } from './strategies/headers';
 export type { ColumnResolutionStrategy } from './strategies/resolution';
 
 /**
- * Strategy to filter rows based on criteria.
+ * Strategy to filter rows based on criteria. Applied when using getRow/findRow/findRows with filters.
+ * The default engine handles string, RegExp, number, and function (cell) => Locator filters.
  */
 export interface FilterStrategy {
   apply(options: {
@@ -300,7 +311,8 @@ export interface FilterStrategy {
 }
 
 /**
- * Strategy to check if the table or rows are loading.
+ * Strategy to check if the table or rows are loading. Used after pagination/sort to wait for content.
+ * E.g. isHeaderLoading for init stability; isTableLoading after sort/pagination.
  */
 export interface LoadingStrategy {
   isTableLoading?: (context: TableContext) => Promise<boolean>;
@@ -335,13 +347,10 @@ export interface TableStrategies {
    * Useful for scrolling off-screen columns into view in horizontally virtualized tables.
    */
   beforeCellRead?: BeforeCellReadFn;
-  /** Custom helper to check if a table is fully loaded/ready */
-  isTableLoaded?: (args: TableContext) => Promise<boolean>;
-  /** Custom helper to check if a row is fully loaded/ready */
-  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;
-  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */
-  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;
-  /** Strategy for detecting loading states */
+  /**
+   * Strategy for detecting loading states. Use this for table-, row-, and header-level readiness.
+   * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.
+   */
   loading?: LoadingStrategy;
 }
 
@@ -417,6 +426,11 @@ export type RowIterationOptions = {
    * (e.g. infinite scroll tables). Returns a unique key per row.
    */
   dedupe?: DedupeStrategy;
+  /**
+   * When true, use goNextBulk (if present) to advance pages during iteration.
+   * @default false — uses goNext for one-page-at-a-time advancement
+   */
+  useBulkPagination?: boolean;
 };
 
 export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {
@@ -444,6 +458,8 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   /**
    * Finds a row by filters on the current page only. Returns immediately (sync).
    * Throws error if table is not initialized.
+   * @note The returned SmartRow may have \`rowIndex\` as 0 when the match is not the first row.
+   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).
    */
   getRow: (
     filters: Record<string, FilterValue>,
@@ -451,10 +467,9 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   ) => SmartRow;
 
   /**
-   * Gets a row by 1-based index on the current page.
+   * Gets a row by 0-based index on the current page.
    * Throws error if table is not initialized.
-   * @param index 1-based row index
-   * @param options Optional settings including bringIntoView
+   * @param index 0-based row index
    */
   getRowByIndex: (
     index: number
@@ -474,11 +489,11 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   /**
    * ASYNC: Searches for all matching rows across pages using pagination.
    * Auto-initializes the table if not already initialized.
-   * @param filters - The filter criteria to match
+   * @param filters - The filter criteria to match (omit or pass {} for all rows)
    * @param options - Search options including exact match and max pages
    */
   findRows: (
-    filters: Record<string, FilterValue>,
+    filters?: Record<string, FilterValue>,
     options?: { exact?: boolean, maxPages?: number }
   ) => Promise<SmartRowArray<T>>;
 
@@ -581,6 +596,11 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
    * Automatically throws an Error containing the prompt.
    */
+  generateConfig: () => Promise<void>;
+
+  /**
+   * @deprecated Use \`generateConfig()\` instead. Will be removed in v7.0.0.
+   */
   generateConfigPrompt: () => Promise<void>;
 }
 `;

package/dist/types.d.ts

@@ -211,10 +211,18 @@ export interface PaginationPrimitives {
     goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;
     /** Jump to first page / scroll to top */
     goToFirst?: (context: TableContext) => Promise<boolean>;
-    /** Jump to specific page index (0-indexed) */
+    /**
+     * Jump to specific page index (0-indexed).
+     * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6–14).
+     * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.
+     */
     goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
+    /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */
+    nextBulkPages?: number;
+    /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
+    previousBulkPages?: number;
 }
-export type PaginationStrategy = ((context: TableContext) => Promise<boolean | number>) | PaginationPrimitives;
+export type PaginationStrategy = PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export type FillStrategy = (options: {
     row: SmartRow;
@@ -251,7 +259,8 @@ import { NavigationPrimitives } from './strategies/columns';
  */
 export type { ColumnResolutionStrategy } from './strategies/resolution';
 /**
- * Strategy to filter rows based on criteria.
+ * Strategy to filter rows based on criteria. Applied when using getRow/findRow/findRows with filters.
+ * The default engine handles string, RegExp, number, and function (cell) => Locator filters.
  */
 export interface FilterStrategy {
     apply(options: {
@@ -265,7 +274,8 @@ export interface FilterStrategy {
     }): Locator;
 }
 /**
- * Strategy to check if the table or rows are loading.
+ * Strategy to check if the table or rows are loading. Used after pagination/sort to wait for content.
+ * E.g. isHeaderLoading for init stability; isTableLoading after sort/pagination.
  */
 export interface LoadingStrategy {
     isTableLoading?: (context: TableContext) => Promise<boolean>;
@@ -298,20 +308,10 @@ export interface TableStrategies {
      * Useful for scrolling off-screen columns into view in horizontally virtualized tables.
      */
     beforeCellRead?: BeforeCellReadFn;
-    /** Custom helper to check if a table is fully loaded/ready */
-    isTableLoaded?: (args: TableContext) => Promise<boolean>;
-    /** Custom helper to check if a row is fully loaded/ready */
-    isRowLoaded?: (args: {
-        row: Locator;
-        index: number;
-    }) => Promise<boolean>;
-    /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */
-    isCellLoaded?: (args: {
-        cell: Locator;
-        column: string;
-        row: Locator;
-    }) => Promise<boolean>;
-    /** Strategy for detecting loading states */
+    /**
+     * Strategy for detecting loading states. Use this for table-, row-, and header-level readiness.
+     * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.
+     */
     loading?: LoadingStrategy;
 }
 export interface TableConfig<T = any> {
@@ -387,6 +387,11 @@ export type RowIterationOptions = {
      * (e.g. infinite scroll tables). Returns a unique key per row.
      */
     dedupe?: DedupeStrategy;
+    /**
+     * When true, use goNextBulk (if present) to advance pages during iteration.
+     * @default false — uses goNext for one-page-at-a-time advancement
+     */
+    useBulkPagination?: boolean;
 };
 export interface TableResult<T = any> extends AsyncIterable<{
     row: SmartRow<T>;
@@ -414,15 +419,16 @@ export interface TableResult<T = any> extends AsyncIterable<{
     /**
      * Finds a row by filters on the current page only. Returns immediately (sync).
      * Throws error if table is not initialized.
+     * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.
+     * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).
      */
     getRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
     }) => SmartRow;
     /**
-     * Gets a row by 1-based index on the current page.
+     * Gets a row by 0-based index on the current page.
      * Throws error if table is not initialized.
-     * @param index 1-based row index
-     * @param options Optional settings including bringIntoView
+     * @param index 0-based row index
      */
     getRowByIndex: (index: number) => SmartRow;
     /**
@@ -438,10 +444,10 @@ export interface TableResult<T = any> extends AsyncIterable<{
     /**
      * ASYNC: Searches for all matching rows across pages using pagination.
      * Auto-initializes the table if not already initialized.
-     * @param filters - The filter criteria to match
+     * @param filters - The filter criteria to match (omit or pass {} for all rows)
      * @param options - Search options including exact match and max pages
      */
-    findRows: (filters: Record<string, FilterValue>, options?: {
+    findRows: (filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
     }) => Promise<SmartRowArray<T>>;
@@ -526,5 +532,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
      * Automatically throws an Error containing the prompt.
      */
+    generateConfig: () => Promise<void>;
+    /**
+     * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.
+     */
     generateConfigPrompt: () => Promise<void>;
 }

package/dist/useTable.js

@@ -24,6 +24,7 @@ var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _ar
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useTable = void 0;
 const minimalConfigContext_1 = require("./minimalConfigContext");
+const validation_1 = require("./strategies/validation");
 const loading_1 = require("./strategies/loading");
 const fill_1 = require("./strategies/fill");
 const headers_1 = require("./strategies/headers");
@@ -31,6 +32,7 @@ const smartRow_1 = require("./smartRow");
 const filterEngine_1 = require("./filterEngine");
 const tableMapper_1 = require("./engine/tableMapper");
 const rowFinder_1 = require("./engine/rowFinder");
+const tableIteration_1 = require("./engine/tableIteration");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
 const elementTracker_1 = require("./utils/elementTracker");
@@ -45,7 +47,7 @@ const useTable = (rootLocator, configOptions = {}) => {
     const defaultStrategies = {
         fill: fill_1.FillStrategies.default,
         header: headers_1.HeaderStrategies.visible,
-        pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }),
+        pagination: {},
         loading: {
             isHeaderLoading: loading_1.LoadingStrategies.Headers.stable(200)
         }
@@ -94,6 +96,8 @@ const useTable = (rootLocator, configOptions = {}) => {
     };
     const tableState = { currentPageIndex: 0 };
     const rowFinder = new rowFinder_1.RowFinder(rootLocator, config, resolve, filterEngine, tableMapper, _makeSmart, tableState);
+    /** Builds a full TableContext/StrategyContext with getHeaderCell, getHeaders, scrollToColumn. Set after result is created. */
+    let createStrategyContext = () => ({ root: rootLocator, config, page: rootLocator.page(), resolve });
     const _getCleanHtml = (loc) => __awaiter(void 0, void 0, void 0, function* () {
         return loc.evaluate((el) => {
             const clone = el.cloneNode(true);
@@ -125,20 +129,26 @@ const useTable = (rootLocator, configOptions = {}) => {
     const _autoInit = () => __awaiter(void 0, void 0, void 0, function* () {
         yield tableMapper.getMap();
     });
-    const _advancePage = () => __awaiter(void 0, void 0, void 0, function* () {
-        var _a;
-        const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell, getHeaders: result.getHeaders, scrollToColumn: result.scrollToColumn };
-        let advanced;
-        if (typeof config.strategies.pagination === 'function') {
-            advanced = !!(yield config.strategies.pagination(context));
+    // Default: goNext (one page). Pass useBulk true to prefer goNextBulk. "How far" uses numeric return when strategy provides it.
+    const _advancePage = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (useBulk = false) {
+        const context = createStrategyContext();
+        const pagination = config.strategies.pagination;
+        let rawResult;
+        if (useBulk && (pagination === null || pagination === void 0 ? void 0 : pagination.goNextBulk)) {
+            rawResult = yield pagination.goNextBulk(context);
         }
-        else {
-            advanced = !!(((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goNext) && (yield config.strategies.pagination.goNext(context)));
+        else if (pagination === null || pagination === void 0 ? void 0 : pagination.goNext) {
+            rawResult = yield pagination.goNext(context);
         }
-        if (advanced) {
-            tableState.currentPageIndex++;
+        else if (pagination === null || pagination === void 0 ? void 0 : pagination.goNextBulk) {
+            rawResult = yield pagination.goNextBulk(context);
         }
-        return advanced;
+        const didAdvance = rawResult !== undefined && (0, validation_1.validatePaginationResult)(rawResult, 'Pagination Strategy');
+        const pagesJumped = typeof rawResult === 'number' ? rawResult : (didAdvance ? 1 : 0);
+        if (pagesJumped > 0) {
+            tableState.currentPageIndex += pagesJumped;
+        }
+        return didAdvance;
     });
     const result = {
         get currentPageIndex() { return tableState.currentPageIndex; },
@@ -176,11 +186,10 @@ const useTable = (rootLocator, configOptions = {}) => {
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
             var _a;
             log("Resetting table...");
-            const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell };
-            yield config.onReset(context);
-            if (typeof config.strategies.pagination !== 'function' && ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goToFirst)) {
+            yield config.onReset(createStrategyContext());
+            if ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.goToFirst) {
                 log("Auto-navigating to first page...");
-                yield config.strategies.pagination.goToFirst(context);
+                yield config.strategies.pagination.goToFirst(createStrategyContext());
             }
             else if (hasPaginationInConfig) {
                 log("No goToFirst strategy configured. Table may not be on page 1.");
@@ -213,11 +222,10 @@ const useTable = (rootLocator, configOptions = {}) => {
             return _makeSmart(rowLocator, map, index);
         },
         findRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
-            // @ts-ignore
             return rowFinder.findRow(filters, options);
         }),
         findRows: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
-            return rowFinder.findRows(filters, options);
+            return rowFinder.findRows(filters !== null && filters !== void 0 ? filters : {}, options);
         }),
         isInitialized: () => {
             return tableMapper.isInitialized();
@@ -229,7 +237,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
                 log(`Applying sort for column "${columnName}" (${direction})`);
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell };
+                const context = Object.assign(Object.assign({}, createStrategyContext()), { getHeaderCell: result.getHeaderCell });
                 const maxRetries = 3;
                 for (let i = 0; i < maxRetries; i++) {
                     const currentState = yield config.strategies.sorting.getSortState({ columnName, context });
@@ -257,7 +265,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 yield _autoInit();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve, getHeaderCell: result.getHeaderCell };
+                const context = Object.assign(Object.assign({}, createStrategyContext()), { getHeaderCell: result.getHeaderCell });
                 return config.strategies.sorting.getSortState({ columnName, context });
             })
         },
@@ -268,6 +276,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 const map = tableMapper.getMapSync();
                 const effectiveMaxPages = config.maxPages;
                 const tracker = new elementTracker_1.ElementTracker('iterator');
+                const useBulk = false; // iterator has no options; default goNext
                 try {
                     let rowIndex = 0;
                     let pagesScanned = 1;
@@ -281,7 +290,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         }
                         if (pagesScanned >= effectiveMaxPages)
                             break;
-                        if (!(yield __await(_advancePage())))
+                        if (!(yield __await(_advancePage(useBulk))))
                             break;
                         pagesScanned++;
                     }
@@ -291,194 +300,63 @@ const useTable = (rootLocator, configOptions = {}) => {
                 }
             });
         },
-        // ─── Private row-iteration engine ────────────────────────────────────────
+        // ─── Row iteration (delegated to engine/tableIteration) ──────────────────
         forEach: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
-            var _a, _b, _c;
             yield _autoInit();
-            const map = tableMapper.getMapSync();
-            const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-            const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
-            const dedupeKeys = dedupeStrategy ? new Set() : null;
-            const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
-            const tracker = new elementTracker_1.ElementTracker('forEach');
-            try {
-                let rowIndex = 0;
-                let stopped = false;
-                let pagesScanned = 1;
-                const stop = () => { stopped = true; };
-                while (!stopped) {
-                    const rowLocators = resolve(config.rowSelector, rootLocator);
-                    const newIndices = yield tracker.getUnseenIndices(rowLocators);
-                    const pageRows = yield rowLocators.all();
-                    const smartRows = newIndices.map((idx, i) => _makeSmart(pageRows[idx], map, rowIndex + i));
-                    if (parallel) {
-                        yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
-                            if (stopped)
-                                return;
-                            if (dedupeKeys) {
-                                const key = yield dedupeStrategy(row);
-                                if (dedupeKeys.has(key))
-                                    return;
-                                dedupeKeys.add(key);
-                            }
-                            yield callback({ row, rowIndex: row.rowIndex, stop });
-                        })));
-                    }
-                    else {
-                        for (const row of smartRows) {
-                            if (stopped)
-                                break;
-                            if (dedupeKeys) {
-                                const key = yield dedupeStrategy(row);
-                                if (dedupeKeys.has(key))
-                                    continue;
-                                dedupeKeys.add(key);
-                            }
-                            yield callback({ row, rowIndex: row.rowIndex, stop });
-                        }
-                    }
-                    rowIndex += smartRows.length;
-                    if (stopped || pagesScanned >= effectiveMaxPages)
-                        break;
-                    if (!(yield _advancePage()))
-                        break;
-                    pagesScanned++;
-                }
-            }
-            finally {
-                yield tracker.cleanup(rootLocator.page());
-            }
+            yield (0, tableIteration_1.runForEach)({
+                getRowLocators: () => resolve(config.rowSelector, rootLocator),
+                getMap: () => tableMapper.getMapSync(),
+                advancePage: _advancePage,
+                makeSmartRow: (loc, map, idx, pageIdx) => _makeSmart(loc, map, idx, pageIdx),
+                createSmartRowArray: smartRowArray_1.createSmartRowArray,
+                config,
+                getPage: () => rootLocator.page(),
+            }, callback, options);
         }),
         map: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
-            var _a, _b, _c;
             yield _autoInit();
-            const map = tableMapper.getMapSync();
-            const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-            const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
-            const dedupeKeys = dedupeStrategy ? new Set() : null;
-            const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : true;
-            const tracker = new elementTracker_1.ElementTracker('map');
-            const results = [];
-            try {
-                let rowIndex = 0;
-                let stopped = false;
-                let pagesScanned = 1;
-                const stop = () => { stopped = true; };
-                while (!stopped) {
-                    const rowLocators = resolve(config.rowSelector, rootLocator);
-                    const newIndices = yield tracker.getUnseenIndices(rowLocators);
-                    const pageRows = yield rowLocators.all();
-                    const smartRows = newIndices.map((idx, i) => _makeSmart(pageRows[idx], map, rowIndex + i));
-                    if (parallel) {
-                        const SKIP = Symbol('skip');
-                        const pageResults = yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
-                            if (dedupeKeys) {
-                                const key = yield dedupeStrategy(row);
-                                if (dedupeKeys.has(key))
-                                    return SKIP;
-                                dedupeKeys.add(key);
-                            }
-                            return callback({ row, rowIndex: row.rowIndex, stop });
-                        })));
-                        for (const r of pageResults) {
-                            if (r !== SKIP)
-                                results.push(r);
-                        }
-                    }
-                    else {
-                        for (const row of smartRows) {
-                            if (stopped)
-                                break;
-                            if (dedupeKeys) {
-                                const key = yield dedupeStrategy(row);
-                                if (dedupeKeys.has(key))
-                                    continue;
-                                dedupeKeys.add(key);
-                            }
-                            results.push(yield callback({ row, rowIndex: row.rowIndex, stop }));
-                        }
-                    }
-                    rowIndex += smartRows.length;
-                    if (stopped || pagesScanned >= effectiveMaxPages)
-                        break;
-                    if (!(yield _advancePage()))
-                        break;
-                    pagesScanned++;
-                }
-            }
-            finally {
-                yield tracker.cleanup(rootLocator.page());
-            }
-            return results;
+            return (0, tableIteration_1.runMap)({
+                getRowLocators: () => resolve(config.rowSelector, rootLocator),
+                getMap: () => tableMapper.getMapSync(),
+                advancePage: _advancePage,
+                makeSmartRow: (loc, map, idx, pageIdx) => _makeSmart(loc, map, idx, pageIdx),
+                createSmartRowArray: smartRowArray_1.createSmartRowArray,
+                config,
+                getPage: () => rootLocator.page(),
+            }, callback, options);
         }),
         filter: (predicate_1, ...args_1) => __awaiter(void 0, [predicate_1, ...args_1], void 0, function* (predicate, options = {}) {
-            var _a, _b, _c;
             yield _autoInit();
-            const map = tableMapper.getMapSync();
-            const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-            const dedupeStrategy = (_b = options.dedupe) !== null && _b !== void 0 ? _b : config.strategies.dedupe;
-            const dedupeKeys = dedupeStrategy ? new Set() : null;
-            const parallel = (_c = options.parallel) !== null && _c !== void 0 ? _c : false;
-            const tracker = new elementTracker_1.ElementTracker('filter');
-            const matched = [];
-            try {
-                let rowIndex = 0;
-                let stopped = false;
-                let pagesScanned = 1;
-                const stop = () => { stopped = true; };
-                while (!stopped) {
-                    const rowLocators = resolve(config.rowSelector, rootLocator);
-                    const newIndices = yield tracker.getUnseenIndices(rowLocators);
-                    const pageRows = yield rowLocators.all();
-                    const smartRows = newIndices.map((idx, i) => _makeSmart(pageRows[idx], map, rowIndex + i, pagesScanned - 1));
-                    if (parallel) {
-                        const flags = yield Promise.all(smartRows.map((row) => __awaiter(void 0, void 0, void 0, function* () {
-                            if (dedupeKeys) {
-                                const key = yield dedupeStrategy(row);
-                                if (dedupeKeys.has(key))
-                                    return false;
-                                dedupeKeys.add(key);
-                            }
-                            return predicate({ row, rowIndex: row.rowIndex, stop });
-                        })));
-                        smartRows.forEach((row, i) => { if (flags[i])
-                            matched.push(row); });
-                    }
-                    else {
-                        for (const row of smartRows) {
-                            if (stopped)
-                                break;
-                            if (dedupeKeys) {
-                                const key = yield dedupeStrategy(row);
-                                if (dedupeKeys.has(key))
-                                    continue;
-                                dedupeKeys.add(key);
-                            }
-                            if (yield predicate({ row, rowIndex: row.rowIndex, stop })) {
-                                matched.push(row);
-                            }
-                        }
-                    }
-                    rowIndex += smartRows.length;
-                    if (stopped || pagesScanned >= effectiveMaxPages)
-                        break;
-                    if (!(yield _advancePage()))
-                        break;
-                    pagesScanned++;
-                }
-            }
-            finally {
-                yield tracker.cleanup(rootLocator.page());
-            }
-            return (0, smartRowArray_1.createSmartRowArray)(matched);
+            return (0, tableIteration_1.runFilter)({
+                getRowLocators: () => resolve(config.rowSelector, rootLocator),
+                getMap: () => tableMapper.getMapSync(),
+                advancePage: _advancePage,
+                makeSmartRow: (loc, map, idx, pageIdx) => _makeSmart(loc, map, idx, pageIdx),
+                createSmartRowArray: smartRowArray_1.createSmartRowArray,
+                config,
+                getPage: () => rootLocator.page(),
+            }, predicate, options);
         }),
-        generateConfigPrompt: () => __awaiter(void 0, void 0, void 0, function* () {
+        generateConfig: () => __awaiter(void 0, void 0, void 0, function* () {
             const html = yield _getCleanHtml(rootLocator);
             const separator = "=".repeat(50);
             const content = `\n${separator} \n🤖 COPY INTO GEMINI / ChatGPT 🤖\n${separator} \nI am using 'playwright-smart-table'.\nTarget Table Locator: ${rootLocator.toString()} \nGenerate config for: \n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n${separator}\n`;
             yield _handlePrompt('Smart Table Config', content);
         }),
+        generateConfigPrompt: () => __awaiter(void 0, void 0, void 0, function* () {
+            console.warn('⚠️ [playwright-smart-table] generateConfigPrompt() is deprecated and will be removed in v7.0.0. Please use generateConfig() instead.');
+            return result.generateConfig();
+        }),
     };
+    createStrategyContext = () => ({
+        root: rootLocator,
+        config,
+        page: rootLocator.page(),
+        resolve,
+        getHeaderCell: result.getHeaderCell,
+        getHeaders: result.getHeaders,
+        scrollToColumn: result.scrollToColumn,
+    });
     finalTable = result;
     return result;
 };

package/dist/utils/paginationPath.d.ts

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