@rickcedwhat/playwright-smart-table 6.10.0 → 6.11.0

package/README.md

@@ -5,233 +5,71 @@
 [![npm version](https://img.shields.io/github/package-json/v/rickcedwhat/playwright-smart-table?label=npm&color=blue&t=2)](https://www.npmjs.com/package/@rickcedwhat/playwright-smart-table)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
----
-
 ## 📚 [Full Documentation →](https://rickcedwhat.github.io/playwright-smart-table/)
 
-**Visit the complete documentation at: https://rickcedwhat.github.io/playwright-smart-table/**
-
 ---
 
-## Why Playwright Smart Table?
-
-Testing HTML tables in Playwright is painful. Traditional approaches are fragile and hard to maintain.
-
-### The Problem
+## The Problem
 
-**Traditional approach:**
+Testing HTML tables in Playwright is fragile by default:
 
 ```typescript
-// ❌ Fragile - breaks if columns reorder
+// ❌ Breaks if columns reorder
 const email = await page.locator('tbody tr').nth(2).locator('td').nth(3).textContent();
 
-// ❌ Brittle XPath
-const row = page.locator('//tr[td[contains(text(), "John")]]');
-
-// ❌ Manual column mapping
+// ❌ Manual column mapping every time
 const headers = await page.locator('thead th').allTextContents();
 const emailIndex = headers.indexOf('Email');
 const email = await row.locator('td').nth(emailIndex).textContent();
 ```
 
-### The Solution
-
-**Playwright Smart Table:**
+## The Solution
 
 ```typescript
-// ✅ Column-aware - survives column reordering
+// ✅ Column-aware — survives column reordering
 const row = table.getRow({ Name: 'John Doe' });
 const email = await row.getCell('Email').textContent();
 
-// ✅ Auto-pagination across all pages
-const allEngineers = await table.findRows({ Department: 'Engineering' });
+// ✅ Search across pages
+const allEngineers = await table.findRows({ Department: 'Engineering' }, { maxPages: 5 });
 
-// ✅ Type-safe
-type Employee = { Name: string; Email: string; Department: string };
-const table = useTable<Employee>(page.locator('#table'));
+// ✅ Iterate with forEach, map, filter, or for await...of
+await table.forEach(async ({ row }) => {
+  await row.getCell('Checkbox').click();
+});
 ```
 
-## Quick Start
-
-### Installation
+## Installation
 
 ```bash
 npm install @rickcedwhat/playwright-smart-table
 ```
 
-### Basic Usage
+## Quick Start
 
 ```typescript
 import { useTable } from '@rickcedwhat/playwright-smart-table';
 
 const table = await useTable(page.locator('#my-table')).init();
 
-// Get row by column values (current page)
 const row = table.getRow({ Name: 'John Doe' });
-
-// Access cells by column name
 const email = await row.getCell('Email').innerText();
-
-// Search across paginated tables
-const allActive = await table.findRows({ Status: 'Active' });
-```
-
-### Iterating Across Pages
-
-```typescript
-// forEach — sequential by default (concurrency: 'sequential') — safe for interactions
-await table.forEach(async ({ row, rowIndex, stop }) => {
-  if (await row.getCell('Status').innerText() === 'Done') stop();
-  await row.getCell('Checkbox').click();
-});
-
-// map — parallel by default (concurrency: 'parallel') — safe for reads
-const emails = await table.map(({ row }) => row.getCell('Email').innerText());
-
-// filter — sequential by default; returns SmartRowArray
-const active = await table.filter(async ({ row }) =>
-  await row.getCell('Status').innerText() === 'Active'
-);
-
-// for await...of — low-level page-by-page iteration
-for await (const { row, rowIndex } of table) {
-  console.log(rowIndex, await row.getCell('Name').innerText());
-}
-```
-
-Set a default for all iteration calls with `useTable(..., { concurrency: 'sequential' })`, or per call: `table.map(fn, { concurrency: 'synchronized' })`. Modes: **`parallel`** (full parallelism), **`sequential`** (strictly one row at a time), **`synchronized`** (parallel navigation with serialized callbacks — useful for virtualized grids).
-
-When your pagination strategy supports bulk jumps (`goNextBulk`), pass `{ useBulkPagination: true }` to `map`/`forEach`/`filter` to advance by multiple pages at once.
-
-> **`map` + UI interactions:** `map` defaults to `concurrency: 'parallel'`. If your callback opens popovers,
-> fills inputs, or otherwise mutates UI state, pass `{ concurrency: 'sequential' }` (or `'synchronized'` if you need lock-step navigation with serialized work).
-
-### `filter` vs `findRows`
-
-| Use case | Best tool |
-|---|---|
-| Match by column value / regex / locator | `findRows` |
-| Computed value (math, range, derived) | `filter` |
-| Cross-column OR logic | `filter` |
-| Multi-step interaction in predicate (click, read, close) | `filter` |
-| Early exit after N matches | `filter` + `stop()` |
-
-**`findRows` is faster** for column-value matches — Playwright evaluates the locator natively with no DOM reads. **`filter` is more flexible** for logic that a CSS selector can't express.
-
-```typescript
-// findRows — structural match, no DOM reads, fast
-const notStarted = await table.findRows({
-  Status: (cell) => cell.locator('[class*="gray"]')
-});
-
-// filter — arbitrary async logic
-const expensive = await table.filter(async ({ row }) => {
-  const price = parseFloat(await row.getCell('Price').innerText());
-  const qty = parseFloat(await row.getCell('Qty').innerText());
-  return price * qty > 1000;
-});
-```
-
-### Advanced: `columnOverrides`
-
-For complex DOM structures, custom data extraction, or specialized input widgets, use `columnOverrides` to intercept how Smart Table interacts with specific columns:
-
-```typescript
-const table = useTable(page.locator('#table'), {
-  columnOverrides: {
-    // Override how data is read from the 'Status' column (e.g., for .toJSON())
-    Status: {
-      read: async (cell) => {
-        const isChecked = await cell.locator('input[type="checkbox"]').isChecked();
-        return isChecked ? 'Active' : 'Inactive';
-      }
-    },
-    // Override how data is written to the 'Tags' column (for .smartFill())
-    Tags: {
-      write: async ({ cell, targetValue }) => {
-        await cell.click();
-        await page.keyboard.type(targetValue);
-        await page.keyboard.press('Enter');
-      }
-    }
-  }
-});
 ```
 
 ## Key Features
 
-- 🎯 **Smart Locators** - Find rows by content, not position
-- 🧠 **Fuzzy Matching** - Smart suggestions for typos in column names
-- ⚡ **Smart Initialization** - Handles loading states and dynamic headers automatically
-- 📄 **Auto-Pagination** - Search across all pages automatically
-- 🔍 **Column-Aware Access** - Access cells by column name
-- 🔁 **Iteration Methods** - `forEach`, `map`, `filter`, and `for await...of` across all pages
-- 🛠️ **Debug Mode** - Visual debugging with slow motion and logging
-- 🔌 **[Extensible Strategies](docs/concepts/strategies.md)** - Support any table implementation
-- 💪 **Type-Safe** - Full TypeScript support
-- 🚀 **Production-Ready** - Battle-tested in real-world applications
-
-## When to Use This Library
-
-**Use this library when you need to:**
-
-- ✅ Find rows by column values
-- ✅ Access cells by column name
-- ✅ Search across paginated tables
-- ✅ Handle column reordering
-- ✅ Extract structured data
-- ✅ Fill/edit table cells
-- ✅ Work with dynamic tables (MUI DataGrid, AG Grid, etc.)
-
-**You might not need this library if:**
-
-- ❌ You don't interact with tables at all
-- ❌ 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 `findRows` or `filter` paginates across pages, returned `SmartRow` locators point to rows that may be off the current DOM page.
-
-- **Data extraction:** Safe — `toJSON()` and cell reads work while the row is visible during iteration.
-- **Interactions after pagination:** Use `await row.bringIntoView()` first — it navigates back to the page the row was originally found on, then you can safely click/fill.
+- 🎯 **Column-aware locators** — find rows and cells by name, not index
+- 📄 **Pagination-aware search** — `findRows` and `forEach` scan across pages automatically
+- 🔁 **Iteration methods** — `forEach`, `map`, `filter`, and `for await...of`
+- 🛠️ **Debug mode** — slow motion playback and structured logs
+- 🔌 **Extensible strategies** — plug in any table implementation or pagination shape
+- 💪 **Full TypeScript support**
 
-```typescript
-const active = await table.filter(async ({ row }) =>
-  await row.getCell('Status').innerText() === 'Active'
-);
-
-for (const row of active) {
-  await row.bringIntoView(); // navigate back to the row's page
-  await row.getCell('Checkbox').click(); // safe to interact
-}
-```
-
-## Documentation
-
-**📚 Full documentation available at: https://rickcedwhat.github.io/playwright-smart-table/**
-
-- [Getting Started Guide](https://rickcedwhat.github.io/playwright-smart-table/guide/getting-started)
-- [Core Concepts](https://rickcedwhat.github.io/playwright-smart-table/guide/core-concepts)
-- [API Reference](https://rickcedwhat.github.io/playwright-smart-table/api/)
-- [Examples](https://rickcedwhat.github.io/playwright-smart-table/examples/)
-- [Troubleshooting](https://rickcedwhat.github.io/playwright-smart-table/troubleshooting)
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## Deprecations
-
-- `generateConfigPrompt()` — deprecated. Use `generateConfig()` instead. `generateConfigPrompt()` will be removed in v7.0.0.
-
-## License
-
-MIT © Cedrick Catalan
-
-## Links
+---
 
 - [Documentation](https://rickcedwhat.github.io/playwright-smart-table/)
 - [npm Package](https://www.npmjs.com/package/@rickcedwhat/playwright-smart-table)
 - [GitHub Repository](https://github.com/rickcedwhat/playwright-smart-table)
 - [Issues](https://github.com/rickcedwhat/playwright-smart-table/issues)
+
+MIT © Cedrick Catalan

package/dist/engine/tableIteration.js

@@ -79,7 +79,7 @@ async function runMap(env, callback, options = {}, label = 'map') {
                             if (stopped && row.rowIndex > stoppedIndex)
                                 return SKIP;
                             log(env.config, `${label}: processing row ${row.rowIndex}`);
-                            return await callback({ row, rowIndex: row.rowIndex, stop: () => stop(row.rowIndex) });
+                            return await callback({ row, index: row.rowIndex, rowIndex: row.rowIndex, stop: () => stop(row.rowIndex) });
                         };
                         if (actionMutex) {
                             return await actionMutex.run(runCallback);

package/dist/minimalConfigContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-config-types.mjs
  * It contains minimal type definitions for config generation prompts.
  */
-export declare const MINIMAL_CONFIG_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string or function returning a Locator.\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 * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\n/**\n * Configuration options for useTable - focus on selectors and basic setup\n */\nexport interface TableConfig<T = any> {\n  /** CSS selector or function for table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for table rows */\n  rowSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  \n  /** Transform header text (e.g., normalize, deduplicate) */\n  headerTransformer?: (args: { \n    text: string; \n    index: number; \n    locator: Locator;\n    seenHeaders: Set<string>;\n  }) => string | Promise<string>;\n  \n  /** Automatically scroll to table on init (default: true) */\n  autoScroll?: boolean;\n  \n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  \n  /** Advanced: Custom strategies for pagination, sorting, navigation, etc. */\n  strategies?: TableStrategies;\n}\n\n/**\n * Example usage:\n */\n// const table = useTable(page.locator('table'), {\n//   headerSelector: 'thead th',\n//   rowSelector: 'tbody tr',\n//   cellSelector: 'td',\n//   headerTransformer: ({ text }) => text.trim()\n// });\n\n";
+export declare const MINIMAL_CONFIG_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string or function returning a Locator.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * headerSelector: (root) => root.locator('[role=\"columnheader\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\n/**\n * Configuration options for useTable - focus on selectors and basic setup\n */\nexport interface TableConfig<T = any> {\n  /** CSS selector or function for table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for table rows */\n  rowSelector?: string | ((root: Locator) => Locator);\n  \n  /** CSS selector or function for cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  \n  /** Transform header text (e.g., normalize, deduplicate) */\n  headerTransformer?: (args: { \n    text: string; \n    index: number; \n    locator: Locator;\n    seenHeaders: Set<string>;\n  }) => string | Promise<string>;\n  \n  /** Automatically scroll to table on init (default: true) */\n  autoScroll?: boolean;\n  \n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  \n  /** Advanced: Custom strategies for pagination, sorting, navigation, etc. */\n  strategies?: TableStrategies;\n}\n\n/**\n * Example usage:\n */\n// const table = useTable(page.locator('table'), {\n//   headerSelector: 'thead th',\n//   rowSelector: 'tbody tr',\n//   cellSelector: 'td',\n//   headerTransformer: ({ text }) => text.trim()\n// });\n\n";

package/dist/minimalConfigContext.js

@@ -14,7 +14,7 @@ exports.MINIMAL_CONFIG_CONTEXT = `
  * rowSelector: 'tbody tr'
  * 
  * // Function selector
- * rowSelector: (root) => root.locator('[role="row"]')
+ * headerSelector: (root) => root.locator('[role="columnheader"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator);
 

package/dist/packageVersion.d.ts

@@ -3,4 +3,4 @@
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.10.0";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.11.0";

package/dist/packageVersion.js

@@ -6,4 +6,4 @@ exports.PLAYWRIGHT_SMART_TABLE_VERSION = void 0;
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.10.0";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.11.0";

package/dist/smartRow.js

@@ -115,8 +115,21 @@ const _navigateToCell = async (params) => {
         }
         // Cell still not accessible — fall through to navigation primitives if configured.
         if (!config.strategies.navigation) {
-            (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: viewport phase could not reach cell, no navigation fallback configured');
-            return null;
+            const colRange = viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
+            const rowRange = viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
+            let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex}.\n`;
+            if (colRange) {
+                errMsg += `  Visible column range: [${colRange.first}–${colRange.last}]. Column is out of view and no navigation fallback is configured.\n`;
+            }
+            else {
+                errMsg += `  Column is out of view and no navigation fallback is configured.\n`;
+            }
+            if (rowRange && rowIndex !== undefined) {
+                const inView = rowIndex >= rowRange.first && rowIndex <= rowRange.last;
+                errMsg += `  Visible row range: [${rowRange.first}–${rowRange.last}]. ${inView ? 'Row is in view.' : 'Row is out of view.'}\n`;
+            }
+            errMsg += `  → Add a \`strategies.navigation\` or \`strategies.viewport.scrollToColumn\` to handle off-screen columns.`;
+            throw new Error(errMsg);
         }
     }
     // Use navigation primitives if available
@@ -297,9 +310,11 @@ const _navigateToCell = async (params) => {
         const finalCell = getCellLocator();
         if (await finalCell.count() > 0)
             return finalCell;
-        return null;
+        throw new Error(`SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex} after exhausting navigation strategies. Ensure navigation primitives are correctly implemented.`);
     }
-    return null;
+    // No horizontal strategies configured; assume table is 1D or fully rendered,
+    // and let standard Playwright auto-waiting handle any lazy-loading delays.
+    return getCellLocator();
 };
 /**
  * Factory to create a SmartRow by extending a Playwright Locator.
@@ -322,8 +337,9 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         if (idx === undefined) {
             throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, Array.from(map.keys())));
         }
+        let baseLocator;
         if (config.strategies.getCellLocator) {
-            return config.strategies.getCellLocator({
+            baseLocator = config.strategies.getCellLocator({
                 row: rowLocator,
                 root: rootLocator,
                 columnName: colName,
@@ -333,7 +349,27 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 config
             });
         }
-        return resolve(config.cellSelector, rowLocator).nth(idx);
+        else {
+            baseLocator = resolve(config.cellSelector, rowLocator).nth(idx);
+        }
+        const smartCell = baseLocator;
+        smartCell.bringIntoView = async () => {
+            const navigatedCell = await _navigateToCell({
+                config,
+                rootLocator,
+                page: rootLocator.page(),
+                resolve,
+                column: colName,
+                index: idx,
+                rowLocator,
+                rowIndex,
+                barrier: smart._barrier
+            });
+            if (navigatedCell && navigatedCell._locator) {
+                smartCell._locator = navigatedCell._locator;
+            }
+        };
+        return smartCell;
     };
     smart.wasFound = () => {
         return !smart[sentinel_1.SENTINEL_ROW];
@@ -486,7 +522,13 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 await (0, paginationPath_1.executeNavigationWithGoToPageRetry)(tablePageIndex, primitives, context, getCurrent, setCurrent);
             }
             else {
-                const path = (0, paginationPath_1.planNavigationPath)(getCurrent(), tablePageIndex, primitives);
+                let totalPages;
+                if (primitives.getTotalPages) {
+                    const tp = await primitives.getTotalPages(context);
+                    if (tp !== null)
+                        totalPages = tp;
+                }
+                const path = (0, paginationPath_1.planNavigationPath)(getCurrent(), tablePageIndex, primitives, totalPages);
                 if (path.length > 0) {
                     (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Executing navigation path to page ${tablePageIndex} (${path.length} step(s))`);
                     await (0, paginationPath_1.executeNavigationPath)(path, primitives, context, getCurrent, setCurrent);

package/dist/strategies/index.d.ts

@@ -17,9 +17,12 @@ export declare const Strategies: {
             nextBulk?: import("..").Selector;
             previousBulk?: import("..").Selector;
             first?: import("..").Selector;
+            last?: import("..").Selector;
+            pageNumbers?: import("..").Selector;
         }, options?: {
             nextBulkPages?: number;
             previousBulkPages?: number;
+            numberOfPages?: number | ((root: import("playwright-core").Locator) => number | Promise<number>);
             stabilization?: import("./stabilization").StabilizationStrategy;
             timeout?: number;
         }) => import("../types").PaginationStrategy;
@@ -67,7 +70,10 @@ export declare const Strategies: {
             never: () => Promise<boolean>;
         };
         Headers: {
-            stable: (duration?: number) => (context: import("..").TableContext) => Promise<boolean>;
+            stable: (duration?: number, options?: {
+                pollMs?: number;
+                timeoutMs?: number;
+            }) => (context: import("..").TableContext) => Promise<boolean>;
             never: () => Promise<boolean>;
         };
     };

package/dist/strategies/loading.d.ts

@@ -50,10 +50,20 @@ export declare const LoadingStrategies: {
      */
     Headers: {
         /**
-         * Checks if the headers are stable (count and text) for a specified duration.
-         * @param duration Duration in ms for headers to remain unchanged to be considered stable (default: 200).
+         * Waits until the header signature (count + text) remains unchanged for `duration` ms.
+         *
+         * The default single-shot check (read → wait → read) is fine for most grids.
+         * For slow or virtualized grids that churn headers for several seconds, supply
+         * `pollMs` and optionally `timeoutMs` to poll in a loop until stable.
+         *
+         * @param duration  Stable window in ms — headers must not change for this long (default: 200).
+         * @param options.pollMs     How often to re-check while waiting (default: same as `duration`, i.e. single-shot).
+         * @param options.timeoutMs  Hard deadline in ms; throws if stability is never reached (default: no hard timeout).
          */
-        stable: (duration?: number) => (context: TableContext) => Promise<boolean>;
+        stable: (duration?: number, options?: {
+            pollMs?: number;
+            timeoutMs?: number;
+        }) => (context: TableContext) => Promise<boolean>;
         /**
          * Assume headers are never loading (immediate snapshot).
          */

package/dist/strategies/loading.js

@@ -75,26 +75,55 @@ exports.LoadingStrategies = {
      */
     Headers: {
         /**
-         * Checks if the headers are stable (count and text) for a specified duration.
-         * @param duration Duration in ms for headers to remain unchanged to be considered stable (default: 200).
+         * Waits until the header signature (count + text) remains unchanged for `duration` ms.
+         *
+         * The default single-shot check (read → wait → read) is fine for most grids.
+         * For slow or virtualized grids that churn headers for several seconds, supply
+         * `pollMs` and optionally `timeoutMs` to poll in a loop until stable.
+         *
+         * @param duration  Stable window in ms — headers must not change for this long (default: 200).
+         * @param options.pollMs     How often to re-check while waiting (default: same as `duration`, i.e. single-shot).
+         * @param options.timeoutMs  Hard deadline in ms; throws if stability is never reached (default: no hard timeout).
          */
-        stable: (duration = 200) => async (context) => {
+        stable: (duration = 200, options = {}) => async (context) => {
             const { config, resolve, root } = context;
-            const getHeaderTexts = async () => {
+            const { pollMs, timeoutMs } = options;
+            const getSignature = async () => {
                 const headers = await resolve(config.headerSelector, root).all();
-                return Promise.all(headers.map(h => h.innerText()));
+                const texts = await Promise.all(headers.map(h => h.innerText()));
+                return texts.join('\x00');
             };
-            const initial = await getHeaderTexts();
-            // Wait for duration
-            await context.page.waitForTimeout(duration);
-            const current = await getHeaderTexts();
-            if (initial.length !== current.length)
-                return true; // Count changed, still loading
-            for (let i = 0; i < initial.length; i++) {
-                if (initial[i] !== current[i])
-                    return true; // Content changed, still loading
+            // Single-shot path (original behaviour): no polling requested
+            if (pollMs === undefined) {
+                const initial = await getSignature();
+                await context.page.waitForTimeout(duration);
+                const current = await getSignature();
+                return initial !== current; // true = still loading
+            }
+            // Polling path
+            const deadline = timeoutMs !== undefined ? Date.now() + timeoutMs : Infinity;
+            let lastSig = await getSignature();
+            let stableStart = Date.now(); // baseline sample counts toward the stable window
+            while (true) {
+                // Check deadline before sleeping so the loop cannot overshoot timeoutMs by one pollMs interval.
+                if (Date.now() > deadline) {
+                    throw new Error(`Headers.stable: headers did not stabilise within ${timeoutMs}ms`);
+                }
+                await context.page.waitForTimeout(pollMs);
+                const sig = await getSignature();
+                if (sig !== lastSig) {
+                    lastSig = sig;
+                    stableStart = null; // reset on change
+                    continue;
+                }
+                if (stableStart === null) {
+                    stableStart = Date.now();
+                    continue;
+                }
+                if (Date.now() - stableStart >= duration) {
+                    return false; // Stable — not loading
+                }
             }
-            return false; // Stable
         },
         /**
          * Assume headers are never loading (immediate snapshot).

package/dist/strategies/pagination.d.ts

@@ -7,9 +7,19 @@ export declare const PaginationStrategies: {
         nextBulk?: Selector;
         previousBulk?: Selector;
         first?: Selector;
+        last?: Selector;
+        /**
+         * Selector matching all visible page-number buttons/links.
+         * Used to implement direct page jumps (goToPage). Works with both full-range pagination
+         * (all pages always visible) and windowed pagination (e.g. only pages 6–14 visible) —
+         * returns false when the target page is outside the current window, triggering the
+         * library's step-and-retry loop until the button scrolls into view.
+         */
+        pageNumbers?: Selector;
     }, options?: {
         nextBulkPages?: number;
         previousBulkPages?: number;
+        numberOfPages?: number | ((root: import("@playwright/test").Locator) => number | Promise<number>);
         stabilization?: StabilizationStrategy;
         timeout?: number;
     }) => PaginationStrategy;

package/dist/strategies/pagination.js

@@ -16,7 +16,8 @@ exports.PaginationStrategies = {
                     return false;
                 }
                 return await defaultStabilize(context, async () => {
-                    await btn.click({ timeout: 2000 }).catch(() => { });
+                    var _a;
+                    await btn.click({ timeout: (_a = options.timeout) !== null && _a !== void 0 ? _a : 2000 });
                 }).then(stabilized => stabilized ? returnVal : false);
             };
         };
@@ -28,6 +29,33 @@ exports.PaginationStrategies = {
             goNextBulk: createClicker(selectors.nextBulk, nextBulk),
             goPreviousBulk: createClicker(selectors.previousBulk, prevBulk),
             goToFirst: createClicker(selectors.first),
+            goToLast: createClicker(selectors.last),
+            goToPage: selectors.pageNumbers
+                ? async (pageIndex, context) => {
+                    const { root, resolve } = context;
+                    const pageLabel = String(pageIndex + 1);
+                    const btn = resolve(selectors.pageNumbers, root)
+                        .filter({ hasText: new RegExp(`^\\s*${pageLabel}\\s*$`) })
+                        .first();
+                    if (!await btn.isVisible().catch(() => false))
+                        return false;
+                    if (!await btn.isEnabled().catch(() => false))
+                        return false;
+                    return await defaultStabilize(context, async () => {
+                        var _a;
+                        await btn.click({ timeout: (_a = options.timeout) !== null && _a !== void 0 ? _a : 2000 });
+                    }).then(s => !!s);
+                }
+                : undefined,
+            getTotalPages: options.numberOfPages !== undefined ? async (context) => {
+                const result = typeof options.numberOfPages === 'function'
+                    ? await options.numberOfPages(context.root)
+                    : options.numberOfPages;
+                if (typeof result !== 'number' || !Number.isFinite(result) || !Number.isInteger(result) || result < 1) {
+                    throw new Error(`[SmartTable] numberOfPages must return a finite integer >= 1 (received: ${result})`);
+                }
+                return result;
+            } : undefined,
             nextBulkPages: nextBulk,
             previousBulkPages: prevBulk,
         };

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.mjs
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */\n  root: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n  config: FinalTableConfig<any>;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in toJSON (and columnOverrides.read).\n * Use this to scroll off-screen columns into view in horizontally virtualized tables,\n * wait for lazy-rendered content, or perform any pre-read setup.\n *\n * @example\n * // Scroll the column header into view to trigger horizontal virtualization render\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded();\n *   }\n * }\n */\nexport type BeforeCellReadFn = (args: {\n  /** The resolved cell locator */\n  cell: Locator;\n  columnName: string;\n  columnIndex: number;\n  row: Locator;\n  page: Page;\n  root: Locator;\n  /** Resolves a column name to its header cell locator */\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n}) => Promise<void>;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n/**\n * Viewport oracle strategies for virtualized tables.\n *\n * These tell the library *what is currently in the DOM* rather than *how to move*.\n * When present, the cell-reading engine uses them to jump directly to a target\n * row/column instead of stepping blindly with navigation primitives.\n *\n * This is the primary fix for the 2D scroll hazard: scrolling right to bring a\n * column into view can knock rows out of the vertical viewport (and vice versa).\n * With `getVisibleRowRange` the engine detects this and calls `scrollToRow` to\n * restore the row before reading \u2014 eliminating the hazard without polling loops.\n *\n * All members are optional. Supply whichever the underlying grid exposes:\n * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.\n * - Scroll primitives alone enable direct jumps without range awareness.\n * - Both together give the most reliable, fastest path.\n *\n * @example\n * // MUI DataGrid via apiRef\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const api = (el as any).__muiDataGrid__;\n *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };\n *       }),\n *     scrollToRow: async ({ root }, rowIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),\n *     scrollToColumn: async ({ root }, colIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),\n *   }\n * }\n *\n * @example\n * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const rows = [...el.querySelectorAll('[role=\"row\"][aria-rowindex]')];\n *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);\n *         return { first: Math.min(...idxs), last: Math.max(...idxs) };\n *       }),\n *   }\n * }\n */\nexport interface ViewportStrategy {\n  /**\n   * Returns the 0-based index range of rows currently rendered in the DOM.\n   * Used to detect when a target row has been scrolled out of view and needs recovery.\n   */\n  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Returns the 0-based index range of columns currently rendered in the DOM.\n   * Used to detect when a target column is not yet mounted before reading.\n   */\n  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Scrolls or jumps directly to make a row visible by 0-based index.\n   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.\n   */\n  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;\n\n  /**\n   * Scrolls or jumps directly to make a column visible by 0-based index.\n   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.\n   */\n  scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;\n\n  /**\n   * When true, disables the automatic memoization of getVisibleColumnRange and\n   * getVisibleRowRange results. By default the library caches each range value and\n   * invalidates it after the corresponding scroll call, eliminating redundant DOM\n   * evaluate() round-trips between scrolls.\n   */\n  disableCache?: boolean;\n}\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /**\n   * Jump to specific page index (0-indexed).\n   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6\u201314).\n   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.\n   */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n\n  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */\n  nextBulkPages?: number;\n\n  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */\n  previousBulkPages?: number;\n}\n\nexport type PaginationStrategy = PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell.\n   * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria. Applied when using getRow/findRow/findRows with filters.\n * The default engine handles string, RegExp, number, and function (cell) => Locator filters.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: FilterValue };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading. Used after pagination/sort to wait for content.\n * E.g. isHeaderLoading for init stability; isTableLoading after sort/pagination.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n  isHeaderLoading?: (context: TableContext) => Promise<boolean>;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */\n  navigation?: NavigationPrimitives;\n\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /**\n   * Strategy for filtering rows. If present, FilterEngine will delegate filter application\n   * to this pluggable strategy.\n   */\n  filter?: FilterStrategy;\n  /**\n   * Hook called before each cell value is read in toJSON and columnOverrides.read.\n   * Fires for both the default innerText extraction and custom read mappers.\n   * Useful for scrolling off-screen columns into view in horizontally virtualized tables.\n   */\n  beforeCellRead?: BeforeCellReadFn;\n  /**\n   * Strategy for detecting loading states. Use this for table-, row-, and header-level readiness.\n   * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.\n   */\n  loading?: LoadingStrategy;\n\n  /**\n   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,\n   * Braintrust-style grids where both rows and columns are virtualized simultaneously).\n   *\n   * When present, the cell-reading engine uses these to jump directly to the target\n   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can\n   * knock rows out of the vertical viewport, and vice versa).\n   *\n   * Completely optional and additive \u2014 existing `navigation` primitives remain the fallback.\n   */\n  viewport?: ViewportStrategy;\n}\n\n\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /**\n   * Default concurrency strategy for iteration methods.\n   * Can be overridden by the options passed to forEach, map, or filter.\n   */\n  concurrency?: RowIterationMode;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n\n  /**\n   * Unified interface for reading and writing data to specific columns.\n   * Overrides both default extraction (toJSON) and filling (smartFill) logic.\n   */\n  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;\n}\n\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: string | ((root: Locator) => Locator);\n  rowSelector: string;\n  cellSelector: string | ((row: Locator) => Locator);\n  maxPages: number;\n  autoScroll: boolean;\n  concurrency?: RowIterationMode;\n  debug?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\n\n\n/** Callback context passed to forEach, map, and filter. */\nexport type RowIterationContext<T = any> = {\n  row: SmartRow<T>;\n  rowIndex: number;\n  stop: () => void;\n};\n\n/** Concurrency modes for row iteration. */\nexport type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';\n\n/** Shared options for forEach, map, and filter. */\nexport type RowIterationOptions = {\n  /** Maximum number of pages to iterate. Defaults to config.maxPages. */\n  maxPages?: number;\n  /**\n   * Concurrency strategy for iteration.\n   * - 'parallel': Full parallel execution of both navigation and actions.\n   * - 'synchronized': Parallel navigation (lock-step) with serial actions.\n   * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.\n   * @default 'parallel' (for map), 'sequential' (for forEach/filter)\n   */\n  concurrency?: RowIterationMode;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n  /**\n   * When true, use goNextBulk (if present) to advance pages during iteration.\n   * @default false \u2014 uses goNext for one-page-at-a-time advancement\n   */\n  useBulkPagination?: boolean;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.\n   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 0-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 0-based row index\n   */\n  getRowByIndex: (\n    index: number\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match (omit or pass {} for all rows)\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters?: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `concurrency: 'parallel'`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `concurrency: 'sequential'` (or `'synchronized'`\n   * > when navigation must stay lock-step) to avoid overlapping interactions.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 use sequential (or synchronized) concurrency\n   * const assignees = await table.map(async ({ row }) => {\n   *   await row.getCell('Assignee').locator('button').click();\n   *   const name = await page.locator('.popover .name').innerText();\n   *   await page.keyboard.press('Escape');\n   *   return name;\n   * }, { concurrency: 'sequential' });\n   */\n  map<R>(\n    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.\n   * Rows are returned as-is \u2014 call `bringIntoView()` on each if needed.\n   * Execution is sequential by default.\n   *\n   * @param predicate - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * const active = await table.filter(async ({ row }) =>\n   *   await row.getCell('Status').innerText() === 'Active'\n   * );\n   */\n  filter(\n    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,\n    options?: RowIterationOptions\n  ): Promise<SmartRowArray<T>>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   * Automatically throws an Error containing the prompt.\n   */\n  generateConfig: () => Promise<void>;\n\n  /**\n   * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.\n   */\n  generateConfigPrompt: () => Promise<void>;\n}\n";
+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 * headerSelector: (root) => root.locator('[role=\"columnheader\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);\n\n/**\n * Value used to filter rows.\n * - string/number/RegExp: filter by text content of the cell.\n * - function: filter by custom locator logic within the cell.\n * @example\n * // Text filter\n * { Name: 'John' }\n * \n * // Custom locator filter (e.g. checkbox is checked)\n * { Status: (cell) => cell.locator('input:checked') }\n */\nexport type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */\n  root: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n  config: FinalTableConfig<any>;\n}) => Locator;\n\n/**\n * Hook called before each cell value is read in toJSON (and columnOverrides.read).\n * Use this to scroll off-screen columns into view in horizontally virtualized tables,\n * wait for lazy-rendered content, or perform any pre-read setup.\n *\n * @example\n * // Scroll the column header into view to trigger horizontal virtualization render\n * strategies: {\n *   beforeCellRead: async ({ columnName, getHeaderCell }) => {\n *     const header = await getHeaderCell(columnName);\n *     await header.scrollIntoViewIfNeeded();\n *   }\n * }\n */\nexport type BeforeCellReadFn = (args: {\n  /** The resolved cell locator */\n  cell: Locator;\n  columnName: string;\n  columnIndex: number;\n  row: Locator;\n  page: Page;\n  root: Locator;\n  /** Resolves a column name to its header cell locator */\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n}) => Promise<void>;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n/**\n * Viewport oracle strategies for virtualized tables.\n *\n * These tell the library *what is currently in the DOM* rather than *how to move*.\n * When present, the cell-reading engine uses them to jump directly to a target\n * row/column instead of stepping blindly with navigation primitives.\n *\n * This is the primary fix for the 2D scroll hazard: scrolling right to bring a\n * column into view can knock rows out of the vertical viewport (and vice versa).\n * With `getVisibleRowRange` the engine detects this and calls `scrollToRow` to\n * restore the row before reading \u2014 eliminating the hazard without polling loops.\n *\n * All members are optional. Supply whichever the underlying grid exposes:\n * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.\n * - Scroll primitives alone enable direct jumps without range awareness.\n * - Both together give the most reliable, fastest path.\n *\n * @example\n * // MUI DataGrid via apiRef\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const api = (el as any).__muiDataGrid__;\n *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };\n *       }),\n *     scrollToRow: async ({ root }, rowIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),\n *     scrollToColumn: async ({ root }, colIndex) =>\n *       root.evaluate((el, idx) =>\n *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),\n *   }\n * }\n *\n * @example\n * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)\n * strategies: {\n *   viewport: {\n *     getVisibleRowRange: async ({ root }) =>\n *       root.evaluate(el => {\n *         const rows = [...el.querySelectorAll('[role=\"row\"][aria-rowindex]')];\n *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);\n *         return { first: Math.min(...idxs), last: Math.max(...idxs) };\n *       }),\n *   }\n * }\n */\nexport interface ViewportStrategy {\n  /**\n   * Returns the 0-based index range of rows currently rendered in the DOM.\n   * Used to detect when a target row has been scrolled out of view and needs recovery.\n   */\n  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Returns the 0-based index range of columns currently rendered in the DOM.\n   * Used to detect when a target column is not yet mounted before reading.\n   */\n  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;\n\n  /**\n   * Scrolls or jumps directly to make a row visible by 0-based index.\n   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.\n   */\n  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;\n\n  /**\n   * Scrolls or jumps directly to make a column visible by 0-based index.\n   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.\n   */\n  scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;\n\n  /**\n   * When true, disables the automatic memoization of getVisibleColumnRange and\n   * getVisibleRowRange results. By default the library caches each range value and\n   * invalidates it after the corresponding scroll call, eliminating redundant DOM\n   * evaluate() round-trips between scrolls.\n   */\n  disableCache?: boolean;\n}\n\n\n/**\n * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.\n * \n * Extends all standard Locator methods (click, isVisible, etc.).\n */\nexport type SmartCell = Locator & {\n  /**\n   * Scrolls/paginates to bring this specific cell into view using the configured strategies.\n   * Useful when the grid is horizontally virtualized and the column must be scrolled\n   * into view before it can be interacted with or read.\n   */\n  bringIntoView(): Promise<void>;\n};\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /** Optional page index this row was found on (0-based) */\n  tablePageIndex?: number;\n\n  /** Reference to the parent TableResult */\n  table: TableResult<T>;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns SmartCell (Locator + bringIntoView)\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await emailCell.bringIntoView();\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): SmartCell;\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   * Works when row position metadata is known (e.g., from getRowByIndex, findRow,\n   * findRows, filter, or async iteration).\n   * @throws Error if row position metadata is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n\n  /**\n   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).\n   */\n  wasFound(): boolean;\n};\n\nexport type StrategyContext = TableContext & {\n  rowLocator?: Locator;\n  rowIndex?: number;\n};\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext<T = any> {\n  root: Locator;\n  config: FinalTableConfig<T>;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n  /** Resolves a column name to its header cell locator. Available after table is initialized. */\n  getHeaderCell?: (columnName: string) => Promise<Locator>;\n  /** Returns all column names in order. Available after table is initialized. */\n  getHeaders?: () => Promise<string[]>;\n  /** Scrolls the table horizontally to bring the given column's header into view. */\n  scrollToColumn?: (columnName: string) => Promise<void>;\n}\n\nexport interface PaginationPrimitives {\n  /** Classic \"Next Page\" or \"Scroll Down\" */\n  goNext?: (context: TableContext) => Promise<boolean>;\n\n  /** Classic \"Previous Page\" or \"Scroll Up\" */\n  goPrevious?: (context: TableContext) => Promise<boolean>;\n\n  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */\n  goNextBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */\n  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;\n\n  /** Jump to first page / scroll to top */\n  goToFirst?: (context: TableContext) => Promise<boolean>;\n\n  /** Jump to last page / scroll to bottom */\n  goToLast?: (context: TableContext) => Promise<boolean>;\n\n  /**\n   * Fetch the total number of pages currently available.\n   * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).\n   */\n  getTotalPages?: (context: TableContext) => Promise<number | null>;\n\n  /**\n   * Jump to specific page index (0-indexed).\n   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6\u201314).\n   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.\n   */\n  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;\n\n  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */\n  nextBulkPages?: number;\n\n  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */\n  previousBulkPages?: number;\n\n  /**\n   * Called once during init() to sync the library's page counter with the actual DOM state.\n   * Use when a table may open on a page other than the first (e.g. a deep-linked URL that\n   * lands on page 5). Returns a 0-indexed page number.\n   * @example\n   * detectCurrentPage: async (root) => {\n   *   const text = await root.locator('[aria-current=\"page\"]').textContent();\n   *   return parseInt(text ?? '1') - 1;\n   * }\n   */\n  detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;\n}\n\nexport type PaginationStrategy = PaginationPrimitives;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\n\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  config: FinalTableConfig<any>;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport interface ColumnOverride<TValue = any> {\n  /** \n   * How to extract the value from the cell.\n   * `context` provides access to the parent row, permitting multi-cell logic or bypassing the default cell locator.\n   */\n  read?: (cell: Locator) => Promise<TValue> | TValue;\n\n  /** \n   * How to fill the cell with a new value. (Replaces smartFill default logic)\n   * Provides the current value (via `read`) if a `write` wants to check state first.\n   */\n  write?: (params: {\n    cell: Locator;\n    targetValue: TValue;\n    currentValue?: TValue;\n    row: SmartRow<any>;\n  }) => Promise<void>;\n}\n\nexport type { HeaderStrategy } from './strategies/headers';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria. Applied when using getRow/findRow/findRows with filters.\n * The default engine handles string, RegExp, number, and function (cell) => Locator filters.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: FilterValue };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading. Used after pagination/sort to wait for content.\n * E.g. isHeaderLoading for init stability; isTableLoading after sort/pagination.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n  isHeaderLoading?: (context: TableContext) => Promise<boolean>;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */\n  navigation?: NavigationPrimitives;\n\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /**\n   * Strategy for filtering rows. If present, FilterEngine will delegate filter application\n   * to this pluggable strategy.\n   */\n  filter?: FilterStrategy;\n  /**\n   * Hook called before each cell value is read in toJSON and columnOverrides.read.\n   * Fires for both the default innerText extraction and custom read mappers.\n   * Useful for scrolling off-screen columns into view in horizontally virtualized tables.\n   */\n  beforeCellRead?: BeforeCellReadFn;\n  /**\n   * Strategy for detecting loading states. Use this for table-, row-, and header-level readiness.\n   * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.\n   */\n  loading?: LoadingStrategy;\n\n  /**\n   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,\n   * Braintrust-style grids where both rows and columns are virtualized simultaneously).\n   *\n   * When present, the cell-reading engine uses these to jump directly to the target\n   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can\n   * knock rows out of the vertical viewport, and vice versa).\n   *\n   * Completely optional and additive \u2014 existing `navigation` primitives remain the fallback.\n   */\n  viewport?: ViewportStrategy;\n}\n\n\nexport interface TableConfig<T = any> {\n  /** Selector for the table headers */\n  headerSelector?: string | ((root: Locator) => Locator);\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string | ((row: Locator) => Locator);\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /**\n   * Default concurrency strategy for iteration methods.\n   * Can be overridden by the options passed to forEach, map, or filter.\n   */\n  concurrency?: RowIterationMode;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n\n  /**\n   * Unified interface for reading and writing data to specific columns.\n   * Overrides both default extraction (toJSON) and filling (smartFill) logic.\n   */\n  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;\n}\n\nexport interface FinalTableConfig<T = any> extends TableConfig<T> {\n  headerSelector: string | ((root: Locator) => Locator);\n  rowSelector: string;\n  cellSelector: string | ((row: Locator) => Locator);\n  maxPages: number;\n  autoScroll: boolean;\n  concurrency?: RowIterationMode;\n  debug?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\n\n\n/** Callback context passed to forEach, map, and filter. */\nexport type RowIterationContext<T = any> = {\n  row: SmartRow<T>;\n  /** 0-based iteration counter \u2014 the order this row was visited, not its DOM position or grid identity. @deprecated Use `index` instead. `rowIndex` will be removed in v7.0.0. */\n  rowIndex: number;\n  /** 0-based iteration counter \u2014 the order this row was visited, not its DOM position or grid identity. */\n  index: number;\n  stop: () => void;\n};\n\n/** Concurrency modes for row iteration. */\nexport type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';\n\n/** Shared options for forEach, map, and filter. */\nexport type RowIterationOptions = {\n  /** Maximum number of pages to iterate. Defaults to config.maxPages. */\n  maxPages?: number;\n  /**\n   * Concurrency strategy for iteration.\n   * - 'parallel': Full parallel execution of both navigation and actions.\n   * - 'synchronized': Parallel navigation (lock-step) with serial actions.\n   * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.\n   * @default 'parallel' (for map), 'sequential' (for forEach/filter)\n   */\n  concurrency?: RowIterationMode;\n  /**\n   * Deduplication strategy. Use when rows may repeat across iterations\n   * (e.g. infinite scroll tables). Returns a unique key per row.\n   */\n  dedupe?: DedupeStrategy;\n  /**\n   * When true, use goNextBulk (if present) to advance pages during iteration.\n   * @default false \u2014 uses goNext for one-page-at-a-time advancement\n   */\n  useBulkPagination?: boolean;\n};\n\nexport interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number }> {\n  /**\n   * Represents the current page index of the table's DOM.\n   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.\n   */\n  currentPageIndex: number;\n\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   * @note The returned SmartRow may have `rowIndex` as 0 when the match is not the first row.\n   * Use getRowByIndex(index) when you need a known index (e.g. for bringIntoView()).\n   */\n  getRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 0-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 0-based row index\n   */\n  getRowByIndex: (\n    index: number\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match (omit or pass {} for all rows)\n   * @param options - Search options including exact match and max pages\n   */\n  findRows: (\n    filters?: Record<string, FilterValue>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRowArray<T>>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * Counts the number of rows currently on the page.\n   * Does not paginate.\n   */\n  countRows: () => Promise<number>;\n\n  /**\n   * Iterates over rows and extracts the value of a single column.\n   * More efficient than map + toJSON for single-column extraction.\n   * @param columnName - The name of the column to extract\n   * @param options - Iteration options\n   */\n  mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;\n\n  /**\n   * Iterates over rows and extracts the value of a single column as strings.\n   * @param columnName - The name of the column to extract\n   * @param options - Iteration options\n   */\n  getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;\n\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Iterates every row across all pages, calling the callback for side effects.\n   * Execution is sequential by default (safe for interactions like clicking/filling).\n   * Call `stop()` in the callback to end iteration early.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * await table.forEach(async ({ row, stop }) => {\n   *   if (await row.getCell('Status').innerText() === 'Done') stop();\n   *   await row.getCell('Checkbox').click();\n   * });\n   */\n  forEach(\n    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,\n    options?: RowIterationOptions\n  ): Promise<void>;\n\n  /**\n   * Transforms every row across all pages into a value. Returns a flat array.\n   * Execution is parallel within each page by default (safe for reads).\n   * Call `stop()` to halt after the current page finishes.\n   *\n   * > **\u26A0\uFE0F UI Interactions:** `map` defaults to `concurrency: 'parallel'`. If your callback opens popovers,\n   * > fills inputs, or otherwise mutates UI state, pass `concurrency: 'sequential'` (or `'synchronized'`\n   * > when navigation must stay lock-step) to avoid overlapping interactions.\n   *\n   * @param callback - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * // Data extraction \u2014 parallel is safe\n   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());\n   *\n   * @example\n   * // UI interactions \u2014 use sequential (or synchronized) concurrency\n   * const assignees = await table.map(async ({ row }) => {\n   *   await row.getCell('Assignee').locator('button').click();\n   *   const name = await page.locator('.popover .name').innerText();\n   *   await page.keyboard.press('Escape');\n   *   return name;\n   * }, { concurrency: 'sequential' });\n   */\n  map<R>(\n    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,\n    options?: RowIterationOptions\n  ): Promise<R[]>;\n\n  /**\n   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.\n   * Rows are returned as-is \u2014 call `bringIntoView()` on each if needed.\n   * Execution is sequential by default.\n   *\n   * @param predicate - Function receiving { row, rowIndex, stop }\n   * @param options - maxPages, concurrency, dedupe, useBulkPagination\n   *\n   * @example\n   * const active = await table.filter(async ({ row }) =>\n   *   await row.getCell('Status').innerText() === 'Active'\n   * );\n   */\n  filter(\n    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,\n    options?: RowIterationOptions\n  ): Promise<SmartRowArray<T>>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   * Automatically throws an Error containing the prompt.\n   */\n  generateConfig: () => Promise<void>;\n\n  /**\n   * @deprecated Use `generateConfig()` instead. Will be removed in v7.0.0.\n   */\n  generateConfigPrompt: () => Promise<void>;\n}\n";

package/dist/typeContext.js

@@ -14,7 +14,7 @@ exports.TYPE_CONTEXT = `
  * rowSelector: 'tbody tr'
  * 
  * // Function selector
- * rowSelector: (root) => root.locator('[role="row"]')
+ * headerSelector: (root) => root.locator('[role="columnheader"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
 
@@ -166,6 +166,21 @@ export interface ViewportStrategy {
 }
 
 
+/**
+ * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.
+ * 
+ * Extends all standard Locator methods (click, isVisible, etc.).
+ */
+export type SmartCell = Locator & {
+  /**
+   * Scrolls/paginates to bring this specific cell into view using the configured strategies.
+   * Useful when the grid is horizontally virtualized and the column must be scrolled
+   * into view before it can be interacted with or read.
+   */
+  bringIntoView(): Promise<void>;
+};
+
+
 /**
  * SmartRow - A Playwright Locator with table-aware methods.
  * 
@@ -191,12 +206,13 @@ export type SmartRow<T = any> = Locator & {
   /**
    * Get a cell locator by column name.
    * @param column - Column name (case-sensitive)
-   * @returns Locator for the cell
+   * @returns SmartCell (Locator + bringIntoView)
    * @example
    * const emailCell = row.getCell('Email');
+   * await emailCell.bringIntoView();
    * await expect(emailCell).toHaveText('john@example.com');
    */
-  getCell(column: string): Locator;
+  getCell(column: string): SmartCell;
 
   /**
    * Extract all cell data as a key-value object.
@@ -214,8 +230,9 @@ export type SmartRow<T = any> = Locator & {
 
   /**
    * Scrolls/paginates to bring this row into view.
-   * Only works if rowIndex is known (e.g., from getRowByIndex).
-   * @throws Error if rowIndex is unknown
+   * Works when row position metadata is known (e.g., from getRowByIndex, findRow,
+   * findRows, filter, or async iteration).
+   * @throws Error if row position metadata is unknown
    */
   bringIntoView(): Promise<void>;
 
@@ -325,6 +342,15 @@ export interface PaginationPrimitives {
   /** Jump to first page / scroll to top */
   goToFirst?: (context: TableContext) => Promise<boolean>;
 
+  /** Jump to last page / scroll to bottom */
+  goToLast?: (context: TableContext) => Promise<boolean>;
+
+  /**
+   * Fetch the total number of pages currently available.
+   * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).
+   */
+  getTotalPages?: (context: TableContext) => Promise<number | null>;
+
   /**
    * 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).
@@ -337,6 +363,18 @@ export interface PaginationPrimitives {
 
   /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
   previousBulkPages?: number;
+
+  /**
+   * Called once during init() to sync the library's page counter with the actual DOM state.
+   * Use when a table may open on a page other than the first (e.g. a deep-linked URL that
+   * lands on page 5). Returns a 0-indexed page number.
+   * @example
+   * detectCurrentPage: async (root) => {
+   *   const text = await root.locator('[aria-current="page"]').textContent();
+   *   return parseInt(text ?? '1') - 1;
+   * }
+   */
+  detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;
 }
 
 export type PaginationStrategy = PaginationPrimitives;
@@ -517,7 +555,10 @@ export interface FillOptions {
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
   row: SmartRow<T>;
+  /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. @deprecated Use \`index\` instead. \`rowIndex\` will be removed in v7.0.0. */
   rowIndex: number;
+  /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
+  index: number;
   stop: () => void;
 };
 
@@ -548,7 +589,7 @@ export type RowIterationOptions = {
   useBulkPagination?: boolean;
 };
 
-export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {
+export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number }> {
   /**
    * Represents the current page index of the table's DOM.
    * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.
@@ -617,6 +658,26 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    */
   scrollToColumn: (columnName: string) => Promise<void>;
 
+  /**
+   * Counts the number of rows currently on the page.
+   * Does not paginate.
+   */
+  countRows: () => Promise<number>;
+
+  /**
+   * Iterates over rows and extracts the value of a single column.
+   * More efficient than map + toJSON for single-column extraction.
+   * @param columnName - The name of the column to extract
+   * @param options - Iteration options
+   */
+  mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;
+
+  /**
+   * Iterates over rows and extracts the value of a single column as strings.
+   * @param columnName - The name of the column to extract
+   * @param options - Iteration options
+   */
+  getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;
 
 
   /**

package/dist/types.d.ts

@@ -7,7 +7,7 @@ import type { SmartRowArray } from './utils/smartRowArray';
  * rowSelector: 'tbody tr'
  *
  * // Function selector
- * rowSelector: (root) => root.locator('[role="row"]')
+ * headerSelector: (root) => root.locator('[role="columnheader"]')
  */
 export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
 /**
@@ -154,6 +154,19 @@ export interface ViewportStrategy {
      */
     disableCache?: boolean;
 }
+/**
+ * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.
+ *
+ * Extends all standard Locator methods (click, isVisible, etc.).
+ */
+export type SmartCell = Locator & {
+    /**
+     * Scrolls/paginates to bring this specific cell into view using the configured strategies.
+     * Useful when the grid is horizontally virtualized and the column must be scrolled
+     * into view before it can be interacted with or read.
+     */
+    bringIntoView(): Promise<void>;
+};
 /**
  * SmartRow - A Playwright Locator with table-aware methods.
  *
@@ -176,12 +189,13 @@ export type SmartRow<T = any> = Locator & {
     /**
      * Get a cell locator by column name.
      * @param column - Column name (case-sensitive)
-     * @returns Locator for the cell
+     * @returns SmartCell (Locator + bringIntoView)
      * @example
      * const emailCell = row.getCell('Email');
+     * await emailCell.bringIntoView();
      * await expect(emailCell).toHaveText('john@example.com');
      */
-    getCell(column: string): Locator;
+    getCell(column: string): SmartCell;
     /**
      * Extract all cell data as a key-value object.
      * @param options - Optional configuration
@@ -199,8 +213,9 @@ export type SmartRow<T = any> = Locator & {
     }): Promise<T>;
     /**
      * Scrolls/paginates to bring this row into view.
-     * Only works if rowIndex is known (e.g., from getRowByIndex).
-     * @throws Error if rowIndex is unknown
+     * Works when row position metadata is known (e.g., from getRowByIndex, findRow,
+     * findRows, filter, or async iteration).
+     * @throws Error if row position metadata is unknown
      */
     bringIntoView(): Promise<void>;
     /**
@@ -297,6 +312,13 @@ export interface PaginationPrimitives {
     goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;
     /** Jump to first page / scroll to top */
     goToFirst?: (context: TableContext) => Promise<boolean>;
+    /** Jump to last page / scroll to bottom */
+    goToLast?: (context: TableContext) => Promise<boolean>;
+    /**
+     * Fetch the total number of pages currently available.
+     * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).
+     */
+    getTotalPages?: (context: TableContext) => Promise<number | null>;
     /**
      * 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).
@@ -307,6 +329,17 @@ export interface PaginationPrimitives {
     nextBulkPages?: number;
     /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
     previousBulkPages?: number;
+    /**
+     * Called once during init() to sync the library's page counter with the actual DOM state.
+     * Use when a table may open on a page other than the first (e.g. a deep-linked URL that
+     * lands on page 5). Returns a 0-indexed page number.
+     * @example
+     * detectCurrentPage: async (root) => {
+     *   const text = await root.locator('[aria-current="page"]').textContent();
+     *   return parseInt(text ?? '1') - 1;
+     * }
+     */
+    detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;
 }
 export type PaginationStrategy = PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
@@ -479,7 +512,10 @@ export interface FillOptions {
 /** Callback context passed to forEach, map, and filter. */
 export type RowIterationContext<T = any> = {
     row: SmartRow<T>;
+    /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. @deprecated Use `index` instead. `rowIndex` will be removed in v7.0.0. */
     rowIndex: number;
+    /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
+    index: number;
     stop: () => void;
 };
 /** Concurrency modes for row iteration. */
@@ -510,6 +546,7 @@ export type RowIterationOptions = {
 export interface TableResult<T = any> extends AsyncIterable<{
     row: SmartRow<T>;
     rowIndex: number;
+    index: number;
 }> {
     /**
      * Represents the current page index of the table's DOM.
@@ -569,6 +606,24 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Navigates to a specific column using the configured CellNavigationStrategy.
      */
     scrollToColumn: (columnName: string) => Promise<void>;
+    /**
+     * Counts the number of rows currently on the page.
+     * Does not paginate.
+     */
+    countRows: () => Promise<number>;
+    /**
+     * Iterates over rows and extracts the value of a single column.
+     * More efficient than map + toJSON for single-column extraction.
+     * @param columnName - The name of the column to extract
+     * @param options - Iteration options
+     */
+    mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;
+    /**
+     * Iterates over rows and extracts the value of a single column as strings.
+     * @param columnName - The name of the column to extract
+     * @param options - Iteration options
+     */
+    getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;
     /**
      * Resets the table state (clears cache, flags) and invokes the onReset strategy.
      */

package/dist/useTable.js

@@ -192,12 +192,30 @@ const useTable = (rootLocator, configOptions = {}) => {
         get currentPageIndex() { return tableState.currentPageIndex; },
         set currentPageIndex(v) { tableState.currentPageIndex = v; },
         init: async (options) => {
+            var _a;
             if (tableMapper.isInitialized())
                 return result;
             (0, debugUtils_1.warnIfDebugInCI)(config);
             (0, debugUtils_1.logDebug)(config, 'info', 'Initializing table');
             const map = await tableMapper.getMap(options === null || options === void 0 ? void 0 : options.timeout);
             (0, debugUtils_1.logDebug)(config, 'info', `Table initialized with ${map.size} columns`, Array.from(map.keys()));
+            if ((_a = config.strategies.pagination) === null || _a === void 0 ? void 0 : _a.detectCurrentPage) {
+                try {
+                    const detected = await config.strategies.pagination.detectCurrentPage(rootLocator);
+                    if (Number.isInteger(detected) && detected >= 0) {
+                        tableState.currentPageIndex = detected;
+                        (0, debugUtils_1.logDebug)(config, 'info', `init: detected starting page index ${detected}`);
+                    }
+                    else {
+                        tableState.currentPageIndex = 0;
+                        (0, debugUtils_1.logDebug)(config, 'error', `init: detectCurrentPage returned invalid index (${detected}); defaulting to 0`);
+                    }
+                }
+                catch (e) {
+                    tableState.currentPageIndex = 0;
+                    (0, debugUtils_1.logDebug)(config, 'error', `init: detectCurrentPage failed`, e);
+                }
+            }
             await (0, debugUtils_1.debugDelay)(config, 'default');
             return result;
         },
@@ -221,6 +239,32 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw _createColumnError(columnName, map, 'header cell');
             return resolve(config.headerSelector, rootLocator).nth(idx);
         },
+        countRows: async () => {
+            await _autoInit();
+            const allRows = resolve(config.rowSelector, rootLocator);
+            return allRows.count();
+        },
+        mapColumn: async (columnName, options = {}) => {
+            await _autoInit();
+            const map = await tableMapper.getMap();
+            if (!map.has(columnName))
+                throw _createColumnError(columnName, map, 'mapColumn iteration');
+            return result.map(async ({ row }) => {
+                var _a;
+                const cell = row.getCell(columnName);
+                await cell.bringIntoView();
+                const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[columnName];
+                if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) {
+                    return await columnOverride.read(cell);
+                }
+                const text = await cell.innerText();
+                return (text || '').trim();
+            }, options);
+        },
+        getColumnValues: async (columnName, options = {}) => {
+            const values = await result.mapColumn(columnName, options);
+            return values.map(v => String(v));
+        },
         reset: async () => {
             var _a;
             log("Resetting table...");
@@ -324,7 +368,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         const pageRows = yield __await(rowLocators.all());
                         const barrier = new navigationBarrier_1.NavigationBarrier(newIndices.length);
                         for (const idx of newIndices) {
-                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex, pagesScanned - 1, barrier), rowIndex });
+                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex, pagesScanned - 1, barrier), index: rowIndex, rowIndex });
                             rowIndex++;
                         }
                         if (pagesScanned >= effectiveMaxPages)

package/dist/utils/paginationPath.d.ts

@@ -3,6 +3,9 @@ import type { PaginationPrimitives, TableContext } from '../types';
 export type NavigationStep = {
     type: 'goToPage';
     pageIndex: number;
+} | {
+    type: 'goToLast';
+    targetIndex: number;
 } | {
     type: 'goNextBulk';
     count: number;
@@ -22,7 +25,7 @@ export type NavigationStep = {
  * 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[];
+export declare function planNavigationPath(currentPageIndex: number, targetPageIndex: number, primitives: PaginationPrimitives, totalPages?: number): 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,

package/dist/utils/paginationPath.js

@@ -3,13 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.planNavigationPath = planNavigationPath;
 exports.executeNavigationWithGoToPageRetry = executeNavigationWithGoToPageRetry;
 exports.executeNavigationPath = executeNavigationPath;
+function computeCost(path) {
+    return path.reduce((sum, step) => {
+        if ('count' in step)
+            return sum + step.count;
+        return sum + 1; // goToPage and goToLast count as 1
+    }, 0);
+}
 /**
  * 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).
  */
-function planNavigationPath(currentPageIndex, targetPageIndex, primitives) {
+function planNavigationPath(currentPageIndex, targetPageIndex, primitives, totalPages) {
     var _a, _b;
     if (currentPageIndex === targetPageIndex)
         return [];
@@ -23,37 +30,58 @@ function planNavigationPath(currentPageIndex, targetPageIndex, primitives) {
         const stepsForward = targetPageIndex - currentPageIndex;
         const hasBulk = !!(primitives.goNextBulk && nextBulkSize > 0);
         const hasPrev = !!primitives.goPrevious;
+        let forwardPath = [];
         if (!hasBulk || nextBulkSize <= 0) {
             if (primitives.goNext) {
-                return [{ type: 'goNext', count: stepsForward }];
+                forwardPath = [{ type: 'goNext', count: stepsForward }];
             }
-            return [];
         }
-        const bulkCountA = Math.floor(stepsForward / nextBulkSize);
-        const remA = stepsForward % nextBulkSize;
-        const totalA = bulkCountA + remA;
-        let totalB = Infinity;
-        let bulkCountB = 0;
-        let overB = 0;
-        if (hasPrev && primitives.goPreviousBulk && prevBulkSize > 0) {
-            bulkCountB = Math.ceil(stepsForward / nextBulkSize);
-            overB = bulkCountB * nextBulkSize - stepsForward;
-            totalB = bulkCountB + overB;
+        else {
+            const bulkCountA = Math.floor(stepsForward / nextBulkSize);
+            const remA = stepsForward % nextBulkSize;
+            const totalA = (remA === 0 || primitives.goNext)
+                ? bulkCountA + remA
+                : Infinity;
+            let totalB = Infinity;
+            let bulkCountB = 0;
+            let overB = 0;
+            if (hasPrev) {
+                bulkCountB = Math.ceil(stepsForward / nextBulkSize);
+                overB = bulkCountB * nextBulkSize - stepsForward;
+                totalB = bulkCountB + overB;
+            }
+            forwardPath = (totalB < totalA)
+                ? (() => {
+                    const path = [];
+                    if (bulkCountB > 0)
+                        path.push({ type: 'goNextBulk', count: bulkCountB });
+                    if (overB > 0)
+                        path.push({ type: 'goPrevious', count: overB });
+                    return path;
+                })()
+                : Number.isFinite(totalA) ? (() => {
+                    const path = [];
+                    if (bulkCountA > 0)
+                        path.push({ type: 'goNextBulk', count: bulkCountA });
+                    if (remA > 0)
+                        path.push({ type: 'goNext', count: remA });
+                    return path;
+                })() : [];
         }
-        if (totalB < totalA) {
-            const path = [];
-            if (bulkCountB > 0)
-                path.push({ type: 'goNextBulk', count: bulkCountB });
-            if (overB > 0)
-                path.push({ type: 'goPrevious', count: overB });
-            return path;
+        if (totalPages !== undefined && primitives.goToLast) {
+            const lastPageIndex = totalPages - 1;
+            if (targetPageIndex <= lastPageIndex) {
+                // Evaluate wrap-around path
+                const backwardPath = planNavigationPath(lastPageIndex, targetPageIndex, primitives);
+                if (backwardPath.length > 0 || targetPageIndex === lastPageIndex) {
+                    const wrapPath = [{ type: 'goToLast', targetIndex: lastPageIndex }, ...backwardPath];
+                    if (forwardPath.length === 0 || computeCost(wrapPath) < computeCost(forwardPath)) {
+                        return wrapPath;
+                    }
+                }
+            }
         }
-        const path = [];
-        if (bulkCountA > 0)
-            path.push({ type: 'goNextBulk', count: bulkCountA });
-        if (remA > 0)
-            path.push({ type: 'goNext', count: remA });
-        return path;
+        return forwardPath;
     }
     // Backward: current → target
     const stepsBack = currentPageIndex - targetPageIndex;
@@ -178,6 +206,14 @@ async function executeNavigationPath(path, primitives, context, getCurrentPage,
                     setCurrentPage(step.pageIndex);
                 }
                 break;
+            case 'goToLast':
+                if (primitives.goToLast) {
+                    const ok = await primitives.goToLast(context);
+                    if (!ok)
+                        throw new Error(`goToLast failed`);
+                    setCurrentPage(step.targetIndex);
+                }
+                break;
             case 'goNextBulk':
                 for (let i = 0; i < step.count && primitives.goNextBulk; i++) {
                     const result = await primitives.goNextBulk(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.10.0",
+  "version": "6.11.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -23,8 +23,9 @@
     "generate-docs": "node scripts/generate-readme.mjs",
     "generate-all-api-docs": "node scripts/generate-all-api-docs.mjs",
     "update-all-api-signatures": "node scripts/update-all-api-signatures.mjs",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
+    "docs:dev": "vitepress dev docs --host",
+    "docs:build": "node scripts/docs-build-prod.mjs",
+    "docs:build:all": "vitepress build docs",
     "docs:verify-links": "node scripts/verify-vitepress-links.mjs",
     "embed-version": "node scripts/embed-version.mjs",
     "build": "npm run embed-version && npm run generate-types && npm run generate-config-types && npm run generate-docs && npm run generate-all-api-docs && npm run update-all-api-signatures && tsc",
@@ -42,7 +43,7 @@
     "test:playground": "npx playwright test --config tests-external/playground/playwright.config.ts 2>&1 | tee \"tests-external/playground/logs/run-$(date +%Y%m%d-%H%M%S).log\"",
     "dev:playground": "cd playground && npm run dev",
     "dev:mui": "cd tests/apps/mui-datagrid && npm run dev",
-    "prepare": "husky install"
+    "prepare": "husky"
   },
   "exports": {
     ".": {
@@ -89,6 +90,8 @@
     "@vitest/coverage-v8": "^4.1.0",
     "@vitest/ui": "^4.1.0",
     "happy-dom": "^20.8.3",
+    "@commitlint/cli": "^19.7.1",
+    "@commitlint/config-conventional": "^19.7.1",
     "husky": "^9.1.7",
     "typescript": "^6.0.2",
     "vitepress": "^1.6.4",