@rickcedwhat/playwright-smart-table 6.12.0 → 6.13.0

package/README.md

@@ -45,6 +45,7 @@ await table.forEach(async ({ row }) => {
 npm install @rickcedwhat/playwright-smart-table
 ```
 
+
 ## Quick Start
 
 ```typescript

package/dist/engine/rowFinder.d.ts

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

package/dist/engine/rowFinder.js

@@ -16,9 +16,6 @@ class RowFinder {
         this.tableState = tableState;
         this.resolve = resolve;
     }
-    log(msg) {
-        (0, debugUtils_1.logDebug)(this.config, 'verbose', msg);
-    }
     async findRow(filters, options = {}) {
         (0, debugUtils_1.logDebug)(this.config, 'info', 'Searching for row', filters);
         await this.tableMapper.getMap();
@@ -45,7 +42,7 @@ class RowFinder {
         const allRows = [];
         const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
         let pagesScanned = 1;
-        this.log(`findRows: starting (maxPages=${effectiveMaxPages}, filters=${JSON.stringify(filtersRecord)})`);
+        (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: starting (maxPages=${effectiveMaxPages}, filters=${JSON.stringify(filtersRecord)})`);
         const tracker = new elementTracker_1.ElementTracker('findRows');
         try {
             const collectMatches = async () => {
@@ -63,13 +60,13 @@ class RowFinder {
                 for (const idx of newIndices) {
                     const smartRow = this.makeSmartRow(currentRows[idx], map, allRows.length, this.tableState.currentPageIndex);
                     if (isRowLoading && await isRowLoading(smartRow)) {
-                        this.log(`findRows: page ${this.tableState.currentPageIndex} — row skipped (isRowLoading=true)`);
+                        (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: page ${this.tableState.currentPageIndex} — row skipped (isRowLoading=true)`);
                         continue;
                     }
                     allRows.push(smartRow);
                     added++;
                 }
-                this.log(`findRows: page ${this.tableState.currentPageIndex} — ${added} new match(es) (total: ${allRows.length})`);
+                (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: page ${this.tableState.currentPageIndex} — ${added} new match(es) (total: ${allRows.length})`);
             };
             // Scan first page
             await collectMatches();
@@ -90,25 +87,26 @@ class RowFinder {
                     paginationResult = await this.config.strategies.pagination.goNext(context);
                 }
                 else {
-                    this.log(`findRows: no pagination primitive — stopping`);
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: no pagination primitive — stopping`);
                     break;
                 }
                 const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                 if (!didPaginate) {
-                    this.log(`findRows: pagination returned false — end of data`);
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: pagination returned false — end of data`);
                     break;
                 }
                 const pagesJumped = typeof paginationResult === 'number' ? paginationResult : 1;
                 this.tableState.currentPageIndex += pagesJumped;
                 pagesScanned += pagesJumped;
-                this.log(`findRows: advanced ${pagesJumped} page(s), now at page ${this.tableState.currentPageIndex}`);
+                (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: advanced ${pagesJumped} page(s), now at page ${this.tableState.currentPageIndex}`);
+                await (0, debugUtils_1.debugDelay)(this.config, 'pagination');
                 await collectMatches();
             }
         }
         finally {
             await tracker.cleanup(this.rootLocator.page());
         }
-        this.log(`findRows: done — ${allRows.length} row(s) collected across ${pagesScanned} page(s)`);
+        (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: done — ${allRows.length} row(s) collected across ${pagesScanned} page(s)`);
         return (0, smartRowArray_1.createSmartRowArray)(allRows);
     }
     async findRowLocator(filters, options = {}) {
@@ -116,7 +114,7 @@ class RowFinder {
         const map = await this.tableMapper.getMap();
         const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages;
         let pagesScanned = 1;
-        this.log(`Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
+        (0, debugUtils_1.logDebug)(this.config, 'verbose', `Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
         while (true) {
             // Check Loading
             if ((_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isTableLoading) {
@@ -127,7 +125,7 @@ class RowFinder {
                     resolve: this.resolve
                 });
                 if (isLoading) {
-                    this.log('Table is loading... waiting');
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', 'Table is loading... waiting');
                     await this.rootLocator.page().waitForTimeout(200);
                     continue;
                 }
@@ -135,7 +133,7 @@ class RowFinder {
             const allRows = this.resolve(this.config.rowSelector, this.rootLocator);
             const matchedRows = this.filterEngine.applyFilters(allRows, filters, map, options.exact || false, this.rootLocator.page(), this.rootLocator);
             const count = await matchedRows.count();
-            this.log(`Page ${this.tableState.currentPageIndex}: Found ${count} matches.`);
+            (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Found ${count} matches.`);
             if (count > 1) {
                 const sampleData = [];
                 try {
@@ -154,7 +152,7 @@ class RowFinder {
             if (count === 1)
                 return matchedRows.first();
             if (pagesScanned < effectiveMaxPages) {
-                this.log(`Page ${this.tableState.currentPageIndex}: Not found. Attempting pagination...`);
+                (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Not found. Attempting pagination...`);
                 const context = {
                     root: this.rootLocator,
                     config: this.config,
@@ -171,7 +169,7 @@ class RowFinder {
                     paginationResult = await pagination.goNext(context);
                 }
                 else {
-                    this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (no goNext or goNextBulk primitive).`);
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Pagination failed (no goNext or goNextBulk primitive).`);
                     return null;
                 }
                 const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
@@ -179,10 +177,12 @@ class RowFinder {
                     const pagesJumped = typeof paginationResult === 'number' ? paginationResult : 1;
                     this.tableState.currentPageIndex += pagesJumped;
                     pagesScanned += pagesJumped;
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRowLocator: advanced ${pagesJumped} page(s), now at page ${this.tableState.currentPageIndex}`);
+                    await (0, debugUtils_1.debugDelay)(this.config, 'pagination');
                     continue;
                 }
                 else {
-                    this.log(`Page ${this.tableState.currentPageIndex}: Pagination failed (end of data).`);
+                    (0, debugUtils_1.logDebug)(this.config, 'verbose', `Page ${this.tableState.currentPageIndex}: Pagination failed (end of data).`);
                 }
             }
             return null;

package/dist/engine/tableIteration.d.ts

@@ -11,6 +11,7 @@ export interface TableIterationEnv<T = any> {
     createSmartRowArray: (rows: SmartRow<T>[]) => SmartRowArray<T>;
     config: FinalTableConfig<T>;
     getPage: () => Page;
+    getCurrentPageIndex: () => number;
 }
 /** Delegates to {@link runMap}; void results are discarded. */
 export declare function runForEach<T>(env: TableIterationEnv<T>, callback: (ctx: RowIterationContext<T>) => void | Promise<void>, options?: RowIterationOptions): Promise<void>;

package/dist/engine/tableIteration.js

@@ -27,7 +27,7 @@ async function runMap(env, callback, options = {}, label = 'map') {
     const dedupeKeys = dedupeStrategy ? new Set() : null;
     const defaultMode = label === 'map' ? 'parallel' : 'sequential';
     const concurrency = (_d = (_c = options.concurrency) !== null && _c !== void 0 ? _c : env.config.concurrency) !== null && _d !== void 0 ? _d : defaultMode;
-    const useBarrier = concurrency !== 'sequential';
+    const useBarrier = concurrency === 'synchronized';
     // Mutex must not pair with the navigation barrier: synchronized mode needs every row
     // to enter barrier.sync concurrently; serializing callbacks here deadlocks (first row waits
     // for batchSize peers that never reach the barrier).
@@ -67,7 +67,7 @@ async function runMap(env, callback, options = {}, label = 'map') {
                 log(env.config, `${label}: scanning page ${pagesScanned} — ${batchSize} new row(s)`);
                 const barrier = useBarrier ? new navigationBarrier_1.NavigationBarrier(batchSize) : undefined;
                 const actionMutex = useMutex ? new mutex_1.Mutex() : null;
-                const smartRows = newIndices.map((idx, i) => env.makeSmartRow(pageRows[idx], map, rowIndex + i, pagesScanned - 1, barrier));
+                const smartRows = newIndices.map((idx, i) => env.makeSmartRow(pageRows[idx], map, rowIndex + i, env.getCurrentPageIndex(), barrier));
                 const processRow = async (row) => {
                     try {
                         if (stopped && row.rowIndex > stoppedIndex) {
@@ -86,7 +86,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, index: row.rowIndex, rowIndex: row.rowIndex, stop: () => stop(row.rowIndex) });
+                            return await callback({ row, index: row.rowIndex, rowIndex: row.rowIndex, pageIndex: env.getCurrentPageIndex(), stop: () => stop(row.rowIndex) });
                         };
                         if (actionMutex) {
                             return await actionMutex.run(runCallback);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { PLAYWRIGHT_SMART_TABLE_VERSION } from './packageVersion';
 export { useTable } from './useTable';
-export type { TableConfig, TableResult, SmartRow, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, } from './types';
+export type { TableConfig, TableResult, SmartRow, SmartCell, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, } from './types';
 export { Strategies } from './strategies';
 export * as presets from './presets';
 /** @deprecated Use `presets` instead. Plugins will be removed in v7.0.0. */

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.12.0";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.13.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.12.0";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.13.0";

package/dist/presets/glide/index.d.ts

@@ -1,4 +1,7 @@
 import { FillStrategy, TableConfig } from '../../types';
+export { createGlideViewport } from './viewport';
+export type { GlideViewportOptions } from './viewport';
+import { GlideViewportOptions } from './viewport';
 /** Strategies only for Glide Data Grid. Includes fillSimple; use when you want to supply your own selectors or override fill. */
 export declare const GlideStrategies: {
     fillSimple: FillStrategy;
@@ -9,15 +12,7 @@ export declare const GlideStrategies: {
         selector?: string;
         scrollAmount?: number;
     }) => Promise<string[]>;
-    navigation: {
-        goUp: (context: import("../..").StrategyContext) => Promise<void>;
-        goDown: (context: import("../..").StrategyContext) => Promise<void>;
-        goLeft: (context: import("../..").StrategyContext) => Promise<void>;
-        goRight: (context: import("../..").StrategyContext) => Promise<void>;
-        goHome: (context: import("../..").StrategyContext) => Promise<void>;
-        snapFirstColumnIntoView: (context: import("../..").StrategyContext) => Promise<void>;
-        seekColumnIndex: (context: import("../..").StrategyContext, columnIndex: number) => Promise<void>;
-    };
+    viewport: import("../../types").ViewportStrategy;
     loading: {
         isHeaderLoading: () => Promise<boolean>;
     };
@@ -28,6 +23,16 @@ export declare const GlideStrategies: {
         locator: any;
     } | null>;
 };
+/** Alias of {@link GlideViewportOptions}. All fields are forwarded to the viewport strategy. */
+export type GlideOptions = GlideViewportOptions;
+/**
+ * Factory that returns a configured Glide preset.
+ * Use when your grid differs from the defaults:
+ * ```ts
+ * useTable(loc, { ...createGlide({ attachTimeout: 5000 }), maxPages: 5 })
+ * ```
+ */
+export declare function createGlide(options?: GlideOptions): Partial<TableConfig>;
 export declare const Glide: Partial<TableConfig> & {
     Strategies: typeof GlideStrategies;
 };

package/dist/presets/glide/index.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Glide = exports.GlideStrategies = void 0;
-const columns_1 = require("./columns");
+exports.Glide = exports.GlideStrategies = exports.createGlideViewport = void 0;
+exports.createGlide = createGlide;
 const headers_1 = require("./headers");
 const pagination_1 = require("../../strategies/pagination");
 const stabilization_1 = require("../../strategies/stabilization");
+var viewport_1 = require("./viewport");
+Object.defineProperty(exports, "createGlideViewport", { enumerable: true, get: function () { return viewport_1.createGlideViewport; } });
+const viewport_2 = require("./viewport");
 const glideFillStrategy = async ({ row, columnName, value, page }) => {
     // Canvas-aware click: Glide is a canvas grid. The accessibility 'td' elements
     // may not trigger internal focus on a simple click. We click the canvas at the cell's location.
@@ -86,15 +89,7 @@ const GlideDefaultStrategies = {
     fill: glideFillStrategy,
     pagination: glidePaginationStrategy,
     header: headers_1.scrollRightHeader,
-    navigation: {
-        goUp: columns_1.glideGoUp,
-        goDown: columns_1.glideGoDown,
-        goLeft: columns_1.glideGoLeft,
-        goRight: columns_1.glideGoRight,
-        goHome: columns_1.glideSnapFirstColumnIntoView,
-        snapFirstColumnIntoView: columns_1.glideSnapFirstColumnIntoView,
-        seekColumnIndex: columns_1.glideSeekColumnIndex
-    },
+    viewport: (0, viewport_2.createGlideViewport)(),
     loading: {
         isHeaderLoading: async () => false
     },
@@ -103,10 +98,27 @@ const GlideDefaultStrategies = {
 };
 /** Strategies only for Glide Data Grid. Includes fillSimple; use when you want to supply your own selectors or override fill. */
 exports.GlideStrategies = Object.assign(Object.assign({}, GlideDefaultStrategies), { fillSimple: glideFillSimple });
+/**
+ * Factory that returns a configured Glide preset.
+ * Use when your grid differs from the defaults:
+ * ```ts
+ * useTable(loc, { ...createGlide({ attachTimeout: 5000 }), maxPages: 5 })
+ * ```
+ */
+function createGlide(options = {}) {
+    return {
+        headerSelector: 'table[role="grid"] thead tr th',
+        rowSelector: 'table[role="grid"] tbody tr',
+        cellSelector: 'td',
+        concurrency: 'sequential',
+        strategies: Object.assign(Object.assign({}, GlideDefaultStrategies), { viewport: (0, viewport_2.createGlideViewport)(options) })
+    };
+}
 /**
  * Full preset for Glide Data Grid (selectors + default strategies only).
  * Spread: useTable(loc, { ...Plugins.Glide, maxPages: 5 }).
  * Strategies only (including fillSimple): useTable(loc, { rowSelector: '...', strategies: Plugins.Glide.Strategies }).
+ * For a non-64-column grid, use `createGlide({ columnCount })` instead.
  */
 const GlidePreset = {
     headerSelector: 'table[role="grid"] thead tr th',

package/dist/presets/glide/viewport.d.ts

@@ -0,0 +1,9 @@
+import { ViewportStrategy } from '../../types';
+export interface GlideViewportOptions {
+    /**
+     * Milliseconds to wait for a cell/row to appear in the DOM after a scroll.
+     * Default: 3000.
+     */
+    attachTimeout?: number;
+}
+export declare const createGlideViewport: (options?: GlideViewportOptions) => ViewportStrategy;

package/dist/presets/glide/viewport.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGlideViewport = void 0;
+/**
+ * Viewport strategy for Glide Data Grid.
+ *
+ * Glide renders an ARIA accessibility table (`table[role="grid"]`) alongside its
+ * canvas. Rows and cells are virtualized: only the currently visible window of
+ * `tbody tr` / `td[aria-colindex]` elements exists in the DOM at any moment.
+ *
+ * This strategy:
+ * - `getVisibleColumnRange` — reads `aria-colindex` values from the first visible row
+ * - `getVisibleRowRange`   — reads `aria-rowindex` values from visible rows (2-based: header = 1)
+ * - `scrollToColumn`       — sets `.dvn-scroller.scrollLeft` via ratio derived from header count, waits for cell mount
+ * - `scrollToRow`          — sets `.dvn-scroller.scrollTop` via measured row height, waits for row mount
+ */
+const sanitize = (value, fallback) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+const createGlideViewport = (options = {}) => {
+    const attachTimeout = sanitize(options.attachTimeout, 3000);
+    return {
+        getVisibleColumnRange: async ({ page }) => {
+            const indices = await page
+                .locator('table[role="grid"] tbody tr')
+                .first()
+                .locator('td[aria-colindex]')
+                .evaluateAll((tds) => tds.map((td) => parseInt(td.getAttribute('aria-colindex') || '1') - 1));
+            if (!indices.length)
+                return { first: 0, last: 0 };
+            return { first: Math.min(...indices), last: Math.max(...indices) };
+        },
+        getVisibleRowRange: async ({ page }) => {
+            // aria-rowindex is 1-based; header row = 1, so data row 0 → aria-rowindex="2"
+            const indices = await page
+                .locator('table[role="grid"] tbody tr[aria-rowindex]')
+                .evaluateAll((trs) => trs.map((tr) => parseInt(tr.getAttribute('aria-rowindex') || '2') - 2));
+            if (!indices.length)
+                return { first: 0, last: 0 };
+            return { first: Math.min(...indices), last: Math.max(...indices) };
+        },
+        scrollToColumn: async (context, colIndex) => {
+            var _a, _b;
+            const { page } = context;
+            const scroller = page.locator('.dvn-scroller').first();
+            // Derive total column count from the initialized header map (available post-init).
+            // Falls back to a ratio seek only by position if headers are unavailable.
+            const headers = await ((_a = context.getHeaders) === null || _a === void 0 ? void 0 : _a.call(context));
+            const totalColumns = (_b = headers === null || headers === void 0 ? void 0 : headers.length) !== null && _b !== void 0 ? _b : 0;
+            if (totalColumns > 0) {
+                await scroller.evaluate((el, { idx, count }) => {
+                    const max = Math.max(0, el.scrollWidth - el.clientWidth);
+                    const ratio = Math.min(1, Math.max(0, (idx + 0.5) / count));
+                    el.scrollLeft = Math.floor(ratio * max);
+                }, { idx: colIndex, count: totalColumns });
+            }
+            const target = page
+                .locator(`table[role="grid"] tbody tr td[aria-colindex="${colIndex + 1}"]`)
+                .first();
+            // Wait for the cell to attach. The first probe is short (800ms fast path); after
+            // any nudge the probe uses the full remaining budget so Glide has time to re-render.
+            // Total ceiling = 800ms + attachTimeout, matching the original two-phase behaviour.
+            const deadline = Date.now() + 800 + attachTimeout;
+            let nudged = false;
+            while (true) {
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    throw Object.assign(new Error(`Timed out after ${attachTimeout}ms waiting for aria-colindex="${colIndex + 1}" to attach`), { name: 'TimeoutError' });
+                try {
+                    await target.waitFor({ state: 'attached', timeout: nudged ? remaining : Math.min(800, remaining) });
+                    break;
+                }
+                catch (err) {
+                    if (!(err instanceof Error) || err.name !== 'TimeoutError')
+                        throw err;
+                    await scroller.evaluate((el) => {
+                        el.scrollLeft = Math.min(el.scrollLeft + el.clientWidth, el.scrollWidth);
+                    });
+                    nudged = true;
+                }
+            }
+        },
+        scrollToRow: async ({ page }, rowIndex) => {
+            const scroller = page.locator('.dvn-scroller').first();
+            // aria-rowindex is 2-based for data rows (header = 1)
+            const ariaRowIndex = rowIndex + 2;
+            const rowSel = `table[role="grid"] tbody tr[aria-rowindex="${ariaRowIndex}"]`;
+            // If the row is already mounted, scroll it into view directly.
+            const isAttached = await page.locator(rowSel).count() > 0;
+            if (isAttached) {
+                await page.locator(rowSel).first().scrollIntoViewIfNeeded();
+            }
+            else {
+                // Measure actual row height from the DOM; fall back to Glide's default (34px).
+                const rowHeight = await page
+                    .locator('table[role="grid"] tbody tr')
+                    .first()
+                    .evaluate((el) => el.getBoundingClientRect().height)
+                    .catch(() => 34);
+                const height = rowHeight > 0 ? rowHeight : 34;
+                await scroller.evaluate((el, { idx, height: h }) => {
+                    const targetTop = idx * h;
+                    el.scrollTop = Math.max(0, targetTop - Math.floor(el.clientHeight / 2));
+                }, { idx: rowIndex, height });
+                await page
+                    .locator(rowSel)
+                    .waitFor({ state: 'attached', timeout: attachTimeout });
+            }
+        },
+    };
+};
+exports.createGlideViewport = createGlideViewport;

package/dist/presets/index.d.ts

@@ -1,3 +1,4 @@
 export { muiTable, muiDataGrid } from './mui';
 export { RDG as rdg } from './rdg';
-export { Glide as glide } from './glide';
+export { Glide as glide, createGlide, createGlideViewport } from './glide';
+export type { GlideOptions, GlideViewportOptions } from './glide';

package/dist/presets/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.glide = exports.rdg = exports.muiDataGrid = exports.muiTable = void 0;
+exports.createGlideViewport = exports.createGlide = exports.glide = exports.rdg = exports.muiDataGrid = exports.muiTable = void 0;
 var mui_1 = require("./mui");
 Object.defineProperty(exports, "muiTable", { enumerable: true, get: function () { return mui_1.muiTable; } });
 Object.defineProperty(exports, "muiDataGrid", { enumerable: true, get: function () { return mui_1.muiDataGrid; } });
@@ -8,3 +8,5 @@ var rdg_1 = require("./rdg");
 Object.defineProperty(exports, "rdg", { enumerable: true, get: function () { return rdg_1.RDG; } });
 var glide_1 = require("./glide");
 Object.defineProperty(exports, "glide", { enumerable: true, get: function () { return glide_1.Glide; } });
+Object.defineProperty(exports, "createGlide", { enumerable: true, get: function () { return glide_1.createGlide; } });
+Object.defineProperty(exports, "createGlideViewport", { enumerable: true, get: function () { return glide_1.createGlideViewport; } });

package/dist/smartRow.js

@@ -11,7 +11,7 @@ const sentinel_1 = require("./utils/sentinel");
  * Returns the target cell locator after navigation.
  */
 const _navigateToCell = async (params) => {
-    const { config, rootLocator, page, resolve, column, index, rowLocator, rowIndex, barrier } = params;
+    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier } = params;
     const rowLabel = typeof rowIndex === 'number' ? `row ${rowIndex}` : 'row ?';
     (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: resolving column "${column}" (colIndex ${index}), ${rowLabel}`);
     // Get active cell if strategy is available
@@ -29,7 +29,7 @@ const _navigateToCell = async (params) => {
             return activeCell.locator;
         }
     }
-    const context = { config, root: rootLocator, page, resolve };
+    const context = { config, root: rootLocator, page, resolve, getHeaders };
     // Shared helper: is the target cell currently in the DOM?
     const targetReached = async () => {
         if (config.strategies.getActiveCell) {
@@ -51,18 +51,18 @@ const _navigateToCell = async (params) => {
     // Runs before navigation primitives; falls through to them if cell still not accessible.
     const viewport = config.strategies.viewport;
     if (viewport && typeof rowIndex === 'number') {
-        // Fast path via range oracle: if the user provides getVisibleColumnRange (and memoizes it),
-        // this check is a near-instant JS lookup — no DOM count() round-trip needed.
+        // Fast path via range oracle: re-used below to avoid a second DOM round-trip.
         // Rows do NOT sync at the barrier here — only scroll boundaries need coordination.
+        let knownColRange = null;
         if (viewport.getVisibleColumnRange) {
-            const colRange = await viewport.getVisibleColumnRange(context);
-            if (colRange && index >= colRange.first && index <= colRange.last) {
+            knownColRange = await viewport.getVisibleColumnRange(context);
+            if (knownColRange && index >= knownColRange.first && index <= knownColRange.last) {
                 const rowRange = viewport.getVisibleRowRange
                     ? await viewport.getVisibleRowRange(context)
                     : null;
                 const rowVisible = !rowRange || (rowIndex >= rowRange.first && rowIndex <= rowRange.last);
                 if (rowVisible && await targetReached()) {
-                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} in visible range [${colRange.first}-${colRange.last}], reading directly`);
+                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} in visible range [${knownColRange.first}-${knownColRange.last}], reading directly`);
                     return getCellLocator();
                 }
             }
@@ -76,9 +76,10 @@ const _navigateToCell = async (params) => {
         // Column is out of view. Scroll to bring it in.
         // In synchronized mode, the last row to arrive triggers the scroll once for all rows.
         const scrollIntoViewport = async () => {
-            const colRange = viewport.getVisibleColumnRange
+            // Reuse the range fetched during the fast-path check; re-query only if unknown.
+            const colRange = knownColRange !== null && knownColRange !== void 0 ? knownColRange : (viewport.getVisibleColumnRange
                 ? await viewport.getVisibleColumnRange(context)
-                : null;
+                : null);
             const colOutOfView = !colRange || index < colRange.first || index > colRange.last;
             if (colOutOfView) {
                 (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} out of view, scrolling`);
@@ -92,14 +93,14 @@ const _navigateToCell = async (params) => {
             if (await targetReached()) {
                 return;
             }
-            // 2D scroll hazard guard: scrolling horizontally may have unmounted the target row.
-            const rowRange = viewport.getVisibleRowRange
-                ? await viewport.getVisibleRowRange(context)
-                : null;
-            const rowOutOfView = rowRange && (rowIndex < rowRange.first || rowIndex > rowRange.last);
-            if (rowOutOfView) {
-                (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: row ${rowIndex} out of view after col scroll, recovering`);
-                if (viewport.scrollToRow) {
+            // 2D scroll hazard: horizontal scroll may evict the target row from the DOM.
+            // scrollToRow moves the viewport to one specific row, which would evict every
+            // other row in a parallel batch — safe only when there are no peers to evict.
+            if ((!barrier || !barrier.isParallel()) && viewport.scrollToRow && viewport.getVisibleRowRange) {
+                const rowRange = await viewport.getVisibleRowRange(context);
+                const rowOutOfView = rowRange && (rowIndex < rowRange.first || rowIndex > rowRange.last);
+                if (rowOutOfView) {
+                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: row ${rowIndex} out of view after col scroll, recovering`);
                     await viewport.scrollToRow(context, rowIndex);
                 }
             }
@@ -272,13 +273,15 @@ const _navigateToCell = async (params) => {
             }
             const horizontalSteps = Math.abs(cDiff);
             if (horizontalSteps > 0) {
-                const settleMs = Math.min(2500, 60 + horizontalSteps * 12);
+                const computed = Math.min(2500, 60 + horizontalSteps * 12);
+                const settleMs = (Number.isFinite(nav.settleMs) && nav.settleMs >= 0) ? nav.settleMs : computed;
                 await page.waitForTimeout(settleMs);
             }
             // Wait for active cell to match target: poll getActiveCell or fallback to fixed delay
             // This is the "Midas Touch" buffer needed for Glide's async accessibility updates.
             const pollIntervalMs = 10;
-            const maxWaitMs = Math.min(6000, 250 + horizontalSteps * 25);
+            const computedMax = Math.min(6000, 250 + horizontalSteps * 25);
+            const maxWaitMs = (Number.isFinite(nav.maxWaitMs) && nav.maxWaitMs >= 0) ? nav.maxWaitMs : computedMax;
             const start = Date.now();
             while (Date.now() - start < maxWaitMs) {
                 if (config.strategies.getActiveCell) {
@@ -363,19 +366,38 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         }
         const smartCell = baseLocator;
         smartCell.bringIntoView = async () => {
+            const page = rootLocator.page();
             const navigatedCell = await _navigateToCell({
                 config,
                 rootLocator,
-                page: rootLocator.page(),
+                page,
                 resolve,
+                getHeaders: table === null || table === void 0 ? void 0 : table.getHeaders,
                 column: colName,
                 index: idx,
                 rowLocator,
                 rowIndex,
                 barrier: smart._barrier
             });
-            if (navigatedCell && navigatedCell._locator) {
-                smartCell._locator = navigatedCell._locator;
+            // Run beforeCellRead hook (same as toJSON does after navigation).
+            if (config.strategies.beforeCellRead) {
+                const getHeaderCell = (table === null || table === void 0 ? void 0 : table.getHeaderCell)
+                    ? table.getHeaderCell.bind(table)
+                    : async (colNameArg) => {
+                        const i = map.get(colNameArg);
+                        if (i === undefined)
+                            throw new Error(`Column "${colNameArg}" not found`);
+                        return resolve(config.headerSelector, rootLocator).nth(i);
+                    };
+                await config.strategies.beforeCellRead({
+                    cell: navigatedCell !== null && navigatedCell !== void 0 ? navigatedCell : baseLocator,
+                    columnName: colName,
+                    columnIndex: idx,
+                    row: rowLocator,
+                    page,
+                    root: rootLocator,
+                    getHeaderCell,
+                });
             }
         };
         return smartCell;
@@ -424,6 +446,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 rootLocator,
                 page,
                 resolve,
+                getHeaders: table === null || table === void 0 ? void 0 : table.getHeaders,
                 column: col,
                 index: idx,
                 rowLocator,
@@ -475,6 +498,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 rootLocator,
                 page: rootLocator.page(),
                 resolve,
+                getHeaders: table === null || table === void 0 ? void 0 : table.getHeaders,
                 column: colName,
                 index: colIdx,
                 rowLocator,

package/dist/strategies/columns.d.ts

@@ -21,6 +21,16 @@ export interface NavigationPrimitives {
      * Implementations should leave a small delta for the caller to correct with primitives.
      */
     seekColumnIndex?: (context: StrategyContext, columnIndex: number) => Promise<void>;
+    /**
+     * Override the settle delay (ms) after horizontal goLeft/goRight steps.
+     * Defaults to `Math.min(2500, 60 + steps * 12)`. Tune when your grid settles faster or slower.
+     */
+    settleMs?: number;
+    /**
+     * Override the maximum poll window (ms) waiting for the active cell to confirm position.
+     * Defaults to `Math.min(6000, 250 + steps * 25)`. Tune when accessibility updates lag differently.
+     */
+    maxWaitMs?: number;
 }
 /**
  * @deprecated Use NavigationPrimitives instead. This will be removed in a future version.

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 * 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, useBulkPagination?: boolean }\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";
+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  /** 0-based page index \u2014 which page this row was collected from. */\n  pageIndex: 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; pageIndex: 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<T>>;\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<T>;\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<T>;\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<T>>;\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, useBulkPagination?: boolean }\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

@@ -559,6 +559,8 @@ export type RowIterationContext<T = any> = {
   rowIndex: number;
   /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
   index: number;
+  /** 0-based page index — which page this row was collected from. */
+  pageIndex: number;
   stop: () => void;
 };
 
@@ -589,7 +591,7 @@ export type RowIterationOptions = {
   useBulkPagination?: boolean;
 };
 
-export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number }> {
+export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number; pageIndex: number }> {
   /**
    * Represents the current page index of the table's DOM.
    * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.
@@ -600,7 +602,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    * Initializes the table by resolving headers. Must be called before using sync methods.
    * @param options Optional timeout for header resolution (default: 3000ms)
    */
-  init(options?: { timeout?: number }): Promise<TableResult>;
+  init(options?: { timeout?: number }): Promise<TableResult<T>>;
 
   /**
    * SYNC: Checks if the table has been initialized.
@@ -620,7 +622,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   getRow: (
     filters: Record<string, FilterValue>,
     options?: { exact?: boolean }
-  ) => SmartRow;
+  ) => SmartRow<T>;
 
   /**
    * Gets a row by 0-based index on the current page.
@@ -629,7 +631,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
    */
   getRowByIndex: (
     index: number
-  ) => SmartRow;
+  ) => SmartRow<T>;
 
   /**
    * ASYNC: Searches for a single row across pages using pagination.
@@ -640,7 +642,7 @@ export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>;
   findRow: (
     filters: Record<string, FilterValue>,
     options?: { exact?: boolean, maxPages?: number }
-  ) => Promise<SmartRow>;
+  ) => Promise<SmartRow<T>>;
 
   /**
    * ASYNC: Searches for all matching rows across pages using pagination.

package/dist/types.d.ts

@@ -516,6 +516,8 @@ export type RowIterationContext<T = any> = {
     rowIndex: number;
     /** 0-based iteration counter — the order this row was visited, not its DOM position or grid identity. */
     index: number;
+    /** 0-based page index — which page this row was collected from. */
+    pageIndex: number;
     stop: () => void;
 };
 /** Concurrency modes for row iteration. */
@@ -547,6 +549,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
     row: SmartRow<T>;
     rowIndex: number;
     index: number;
+    pageIndex: number;
 }> {
     /**
      * Represents the current page index of the table's DOM.
@@ -559,7 +562,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     init(options?: {
         timeout?: number;
-    }): Promise<TableResult>;
+    }): Promise<TableResult<T>>;
     /**
      * SYNC: Checks if the table has been initialized.
      * @returns true if init() has been called and completed, false otherwise
@@ -575,13 +578,13 @@ export interface TableResult<T = any> extends AsyncIterable<{
      */
     getRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
-    }) => SmartRow;
+    }) => SmartRow<T>;
     /**
      * Gets a row by 0-based index on the current page.
      * Throws error if table is not initialized.
      * @param index 0-based row index
      */
-    getRowByIndex: (index: number) => SmartRow;
+    getRowByIndex: (index: number) => SmartRow<T>;
     /**
      * ASYNC: Searches for a single row across pages using pagination.
      * Auto-initializes the table if not already initialized.
@@ -591,7 +594,7 @@ export interface TableResult<T = any> extends AsyncIterable<{
     findRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
-    }) => Promise<SmartRow>;
+    }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for all matching rows across pages using pagination.
      * Auto-initializes the table if not already initialized.

package/dist/useTable.js

@@ -196,6 +196,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         if (pagesJumped > 0) {
             tableState.currentPageIndex += pagesJumped;
             log(`_advancePage: ${primitive} advanced ${pagesJumped} page(s) — now at page ${tableState.currentPageIndex}`);
+            await (0, debugUtils_1.debugDelay)(config, 'pagination');
         }
         else {
             log(`_advancePage: ${primitive} returned false — end of data`);
@@ -261,10 +262,35 @@ const useTable = (rootLocator, configOptions = {}) => {
             return resolve(config.headerSelector, rootLocator).nth(idx);
         },
         countRows: async () => {
-            log("countRows: counting rows in current viewport");
             await _autoInit();
-            const allRows = resolve(config.rowSelector, rootLocator);
-            return allRows.count();
+            const pag = config.strategies.pagination;
+            const hasPagination = config.maxPages > 1 && !!((pag === null || pag === void 0 ? void 0 : pag.goNext) || (pag === null || pag === void 0 ? void 0 : pag.goNextBulk));
+            if (!hasPagination) {
+                log("countRows: counting rows in current viewport (no pagination)");
+                return resolve(config.rowSelector, rootLocator).count();
+            }
+            log(`countRows: paginating up to ${config.maxPages} page(s)`);
+            const tracker = new elementTracker_1.ElementTracker('countRows');
+            let total = 0;
+            let pagesScanned = 1;
+            try {
+                while (true) {
+                    const newIndices = await tracker.getUnseenIndices(resolve(config.rowSelector, rootLocator));
+                    total += newIndices.length;
+                    log(`countRows: page ${pagesScanned} — ${newIndices.length} row(s) (running total: ${total})`);
+                    if (pagesScanned >= config.maxPages)
+                        break;
+                    if (!await _advancePage(false))
+                        break;
+                    pagesScanned++;
+                }
+            }
+            finally {
+                await tracker.cleanup(rootLocator.page());
+            }
+            log(`countRows: ${total} total row(s) across ${pagesScanned} page(s) — resetting`);
+            await result.reset();
+            return total;
         },
         mapColumn: async (columnName, options = {}) => {
             log(`mapColumn: column="${columnName}" options=${safeStringify(options)}`);
@@ -393,6 +419,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 const effectiveMaxPages = config.maxPages;
                 const tracker = new elementTracker_1.ElementTracker('iterator');
                 const useBulk = false; // iterator has no options; default goNext
+                log(`iterator: starting (maxPages=${effectiveMaxPages})`);
                 try {
                     let rowIndex = 0;
                     let pagesScanned = 1;
@@ -402,7 +429,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), index: rowIndex, rowIndex });
+                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex, tableState.currentPageIndex, barrier), index: rowIndex, rowIndex, pageIndex: tableState.currentPageIndex });
                             rowIndex++;
                         }
                         if (pagesScanned >= effectiveMaxPages)
@@ -429,6 +456,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
+                getCurrentPageIndex: () => tableState.currentPageIndex,
             }, callback, options);
         },
         map: async (callback, options = {}) => {
@@ -442,6 +470,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
+                getCurrentPageIndex: () => tableState.currentPageIndex,
             }, callback, options);
         },
         filter: async (predicate, options = {}) => {
@@ -455,6 +484,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
+                getCurrentPageIndex: () => tableState.currentPageIndex,
             }, predicate, options);
         },
         generateConfig: async () => {

package/dist/utils/navigationBarrier.d.ts

@@ -7,6 +7,8 @@ export declare class NavigationBarrier {
     private finishedCount;
     private buckets;
     constructor(total: number);
+    /** True when more than one row shares this barrier (scrollToRow would evict peers). */
+    isParallel(): boolean;
     /**
      * Synchronize all active rows at a specific column index.
      * The last row to arrive will trigger the `moveAction`.

package/dist/utils/navigationBarrier.js

@@ -12,6 +12,10 @@ class NavigationBarrier {
         this.buckets = new Map();
         this.total = total;
     }
+    /** True when more than one row shares this barrier (scrollToRow would evict peers). */
+    isParallel() {
+        return this.total > 1;
+    }
     /**
      * Synchronize all active rows at a specific column index.
      * The last row to arrive will trigger the `moveAction`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.12.0",
+  "version": "6.13.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -90,15 +90,12 @@
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "happy-dom": "^20.8.3",
-    "@commitlint/cli": "^19.7.1",
-    "@commitlint/config-conventional": "^19.7.1",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "husky": "^9.1.7",
     "typescript": "^6.0.2",
     "vitepress": "^1.6.4",
     "vitest": "^3.2.4"
   },
-  "dependencies": {
-    "@scarf/scarf": "^1.4.0"
-  },
   "packageManager": "pnpm@10.33.2"
 }

package/dist/presets/glide/columns.d.ts

@@ -1,14 +0,0 @@
-import { StrategyContext } from '../../types';
-/**
- * Primitive navigation functions for Glide Data Grid.
- * These define HOW to move, not WHEN to move.
- * The orchestration logic lives in _navigateToCell.
- */
-export declare const glideGoUp: (context: StrategyContext) => Promise<void>;
-export declare const glideGoDown: (context: StrategyContext) => Promise<void>;
-export declare const glideGoLeft: (context: StrategyContext) => Promise<void>;
-export declare const glideGoRight: (context: StrategyContext) => Promise<void>;
-/** Coarse `scrollLeft` toward `columnIndex`; `goLeft`/`goRight` correct the remainder. */
-export declare const glideSeekColumnIndex: (context: StrategyContext, columnIndex: number) => Promise<void>;
-/** `scrollLeft = 0` so low `aria-colindex` cells exist again (see smartRow for optional `Home`). */
-export declare const glideSnapFirstColumnIntoView: (context: StrategyContext) => Promise<void>;

package/dist/presets/glide/columns.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.glideSnapFirstColumnIntoView = exports.glideSeekColumnIndex = exports.glideGoRight = exports.glideGoLeft = exports.glideGoDown = exports.glideGoUp = void 0;
-/**
- * Primitive navigation functions for Glide Data Grid.
- * These define HOW to move, not WHEN to move.
- * The orchestration logic lives in _navigateToCell.
- */
-const glideGoUp = async (context) => {
-    await context.page.keyboard.press('ArrowUp');
-};
-exports.glideGoUp = glideGoUp;
-const glideGoDown = async (context) => {
-    await context.page.keyboard.press('ArrowDown');
-};
-exports.glideGoDown = glideGoDown;
-// Horizontal: use page `.dvn-scroller` (canvas root is not its ancestor). Virtualized rows expose
-// a small window of `td[aria-colindex]` that shifts with scrollLeft.
-const nudgePageScroller = async (page, delta) => {
-    const scroller = page.locator('.dvn-scroller').first();
-    await scroller.evaluate((el, d) => {
-        el.scrollLeft += d;
-    }, delta);
-};
-const glideGoLeft = async (context) => {
-    await nudgePageScroller(context.page, -400);
-};
-exports.glideGoLeft = glideGoLeft;
-const glideGoRight = async (context) => {
-    await nudgePageScroller(context.page, 400);
-};
-exports.glideGoRight = glideGoRight;
-/** Coarse `scrollLeft` toward `columnIndex`; `goLeft`/`goRight` correct the remainder. */
-const glideSeekColumnIndex = async (context, columnIndex) => {
-    const { page } = context;
-    const scroller = page.locator('.dvn-scroller').first();
-    await scroller.evaluate((el, colIdx) => {
-        const max = Math.max(0, el.scrollWidth - el.clientWidth);
-        const ratio = Math.min(1, Math.max(0, (colIdx + 0.5) / 64));
-        el.scrollLeft = Math.floor(ratio * max);
-    }, columnIndex);
-    await page.waitForTimeout(100);
-};
-exports.glideSeekColumnIndex = glideSeekColumnIndex;
-/** `scrollLeft = 0` so low `aria-colindex` cells exist again (see smartRow for optional `Home`). */
-const glideSnapFirstColumnIntoView = async (context) => {
-    const { page } = context;
-    await page.locator('.dvn-scroller').first().evaluate((el) => {
-        el.scrollLeft = 0;
-    });
-    await page.waitForTimeout(150);
-};
-exports.glideSnapFirstColumnIntoView = glideSnapFirstColumnIntoView;