@rickcedwhat/playwright-smart-table 6.7.1 → 6.7.4

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 = `
@@ -231,20 +231,30 @@ export interface PaginationPrimitives {
   /** Classic "Previous Page" or "Scroll Up" */
   goPrevious?: (context: TableContext) => Promise<boolean>;
 
-  /** Bulk skip forward multiple pages at once */
-  goNextBulk?: (context: TableContext) => Promise<boolean>;
+  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */
+  goNextBulk?: (context: TableContext) => Promise<boolean | number>;
 
-  /** Bulk skip backward multiple pages at once */
-  goPreviousBulk?: (context: TableContext) => Promise<boolean>;
+  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */
+  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>) | PaginationPrimitives;
+export type PaginationStrategy = PaginationPrimitives;
 
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 
@@ -417,6 +427,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 }> {
@@ -451,10 +466,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
@@ -581,6 +595,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

@@ -205,16 +205,24 @@ export interface PaginationPrimitives {
     goNext?: (context: TableContext) => Promise<boolean>;
     /** Classic "Previous Page" or "Scroll Up" */
     goPrevious?: (context: TableContext) => Promise<boolean>;
-    /** Bulk skip forward multiple pages at once */
-    goNextBulk?: (context: TableContext) => Promise<boolean>;
-    /** Bulk skip backward multiple pages at once */
-    goPreviousBulk?: (context: TableContext) => Promise<boolean>;
+    /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */
+    goNextBulk?: (context: TableContext) => Promise<boolean | number>;
+    /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */
+    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>) | PaginationPrimitives;
+export type PaginationStrategy = PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export type FillStrategy = (options: {
     row: SmartRow;
@@ -387,6 +395,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>;
@@ -419,10 +432,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
         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;
     /**
@@ -526,5 +538,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");
@@ -33,6 +34,7 @@ const tableMapper_1 = require("./engine/tableMapper");
 const rowFinder_1 = require("./engine/rowFinder");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
+const elementTracker_1 = require("./utils/elementTracker");
 /**
  * Main hook to interact with a table.
  */
@@ -44,7 +46,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)
         }
@@ -124,20 +126,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;
+    // 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 = { 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));
+        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; },
@@ -177,7 +185,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             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)) {
+            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);
             }
@@ -266,185 +274,225 @@ const useTable = (rootLocator, configOptions = {}) => {
                 yield __await(_autoInit());
                 const map = tableMapper.getMapSync();
                 const effectiveMaxPages = config.maxPages;
-                let rowIndex = 0;
-                let pagesScanned = 1;
-                while (true) {
-                    const pageRows = yield __await(resolve(config.rowSelector, rootLocator).all());
-                    for (const rowLocator of pageRows) {
-                        yield yield __await({ row: _makeSmart(rowLocator, map, rowIndex), rowIndex });
-                        rowIndex++;
+                const tracker = new elementTracker_1.ElementTracker('iterator');
+                const useBulk = false; // iterator has no options; default goNext
+                try {
+                    let rowIndex = 0;
+                    let pagesScanned = 1;
+                    while (true) {
+                        const rowLocators = resolve(config.rowSelector, rootLocator);
+                        const newIndices = yield __await(tracker.getUnseenIndices(rowLocators));
+                        const pageRows = yield __await(rowLocators.all());
+                        for (const idx of newIndices) {
+                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex), rowIndex });
+                            rowIndex++;
+                        }
+                        if (pagesScanned >= effectiveMaxPages)
+                            break;
+                        if (!(yield __await(_advancePage(useBulk))))
+                            break;
+                        pagesScanned++;
                     }
-                    if (pagesScanned >= effectiveMaxPages)
-                        break;
-                    if (!(yield __await(_advancePage())))
-                        break;
-                    pagesScanned++;
+                }
+                finally {
+                    yield __await(tracker.cleanup(rootLocator.page()));
                 }
             });
         },
         // ─── Private row-iteration engine ────────────────────────────────────────
         forEach: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             yield _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;
-            let rowIndex = 0;
-            let stopped = false;
-            let pagesScanned = 1;
-            const stop = () => { stopped = true; };
-            while (!stopped) {
-                const pageRows = yield resolve(config.rowSelector, rootLocator).all();
-                const smartRows = pageRows.map((r, i) => _makeSmart(r, 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))
+            const useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : 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;
-                            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);
+                            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 });
                         }
-                        yield callback({ row, rowIndex: row.rowIndex, stop });
                     }
+                    rowIndex += smartRows.length;
+                    if (stopped || pagesScanned >= effectiveMaxPages)
+                        break;
+                    if (!(yield _advancePage(useBulk)))
+                        break;
+                    pagesScanned++;
                 }
-                rowIndex += smartRows.length;
-                if (stopped || pagesScanned >= effectiveMaxPages)
-                    break;
-                if (!(yield _advancePage()))
-                    break;
-                pagesScanned++;
+            }
+            finally {
+                yield tracker.cleanup(rootLocator.page());
             }
         }),
         map: (callback_1, ...args_1) => __awaiter(void 0, [callback_1, ...args_1], void 0, function* (callback, options = {}) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             yield _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 useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
+            const tracker = new elementTracker_1.ElementTracker('map');
             const results = [];
-            let rowIndex = 0;
-            let stopped = false;
-            let pagesScanned = 1;
-            const stop = () => { stopped = true; };
-            while (!stopped) {
-                const pageRows = yield resolve(config.rowSelector, rootLocator).all();
-                const smartRows = pageRows.map((r, i) => _makeSmart(r, 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);
+            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);
                         }
-                        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);
+                    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 }));
                         }
-                        results.push(yield callback({ row, rowIndex: row.rowIndex, stop }));
                     }
+                    rowIndex += smartRows.length;
+                    if (stopped || pagesScanned >= effectiveMaxPages)
+                        break;
+                    if (!(yield _advancePage(useBulk)))
+                        break;
+                    pagesScanned++;
                 }
-                rowIndex += smartRows.length;
-                if (stopped || pagesScanned >= effectiveMaxPages)
-                    break;
-                if (!(yield _advancePage()))
-                    break;
-                pagesScanned++;
+            }
+            finally {
+                yield tracker.cleanup(rootLocator.page());
             }
             return results;
         }),
         filter: (predicate_1, ...args_1) => __awaiter(void 0, [predicate_1, ...args_1], void 0, function* (predicate, options = {}) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             yield _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 useBulk = (_d = options.useBulkPagination) !== null && _d !== void 0 ? _d : false;
+            const tracker = new elementTracker_1.ElementTracker('filter');
             const matched = [];
-            let rowIndex = 0;
-            let stopped = false;
-            let pagesScanned = 1;
-            const stop = () => { stopped = true; };
-            while (!stopped) {
-                const pageRows = yield resolve(config.rowSelector, rootLocator).all();
-                const smartRows = pageRows.map((r, i) => _makeSmart(r, 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);
+            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(useBulk)))
+                        break;
+                    pagesScanned++;
                 }
-                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);
         }),
-        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();
+        }),
     };
     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>;