@rickcedwhat/playwright-smart-table 6.25.0-next.ec8d20a → 6.25.0-next.f72ee4c

package/dist/strategies/columns.d.ts

@@ -2,7 +2,7 @@ import type { Locator } from '@playwright/test';
 import { StrategyContext } from '../types';
 /**
  * Primitive navigation functions that define HOW to move within a table.
- * The orchestration logic (WHEN to move) lives in _navigateToCell.
+ * The orchestration logic (WHEN to move) lives in navigateToCell (src/engine/cellNavigation.ts).
  */
 export interface NavigationPrimitives {
     goUp?: (context: StrategyContext) => Promise<void>;

package/dist/strategies/contentReady.d.ts

@@ -1,5 +1,23 @@
-import type { ContentReadyStrategy } from '../types';
+import type { ContentReadyStrategy, RowReadyPredicate } from '../types';
 export declare const ContentReadyStrategies: {
+    /**
+     * Waits in the browser until `predicate(rowElement, arg)` returns a truthy value, e.g. until
+     * a skeleton placeholder is gone or every cell has rendered. Resolves when `timeout` expires
+     * even if the predicate never passed, like the other content-ready strategies.
+     *
+     * Uses `locator.waitForFunction` (Playwright 1.62+), which re-resolves the row on each retry
+     * and polls without a round-trip per check. Older versions poll via `locator.evaluate`.
+     * `timeout` and `interval` must be positive finite milliseconds. `interval` only controls
+     * the older-version fallback; native polling is controlled by Playwright.
+     *
+     * @example
+     * contentReady: Strategies.ContentReady.until(row => !row.querySelector('.skeleton'))
+     */
+    until: <Arg = undefined>(predicate: RowReadyPredicate<Arg>, options?: {
+        arg?: Arg;
+        timeout?: number;
+        interval?: number;
+    }) => ContentReadyStrategy;
     /**
      * Polls the row's text content until two consecutive reads match.
      */

package/dist/strategies/contentReady.js

@@ -1,7 +1,88 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContentReadyStrategies = void 0;
+function isTimeout(error) {
+    return (error === null || error === void 0 ? void 0 : error.name) === 'TimeoutError';
+}
+/** Playwright < 1.62 has no `locator.waitForFunction`: poll with one `evaluate` per check. */
+async function pollPredicate(row, page, predicate, arg, timeout, interval) {
+    const deadline = Date.now() + timeout;
+    let source = predicate.toString();
+    // Build a serializable callback; the user predicate executes only inside the browser.
+    const wrap = (expression) => new Function(`return async (row, arg) => Boolean(await (${expression})(row, arg))`)();
+    let evaluateBoolean;
+    try {
+        evaluateBoolean = wrap(source);
+    }
+    catch (_a) {
+        // Like Playwright's serializer, normalize method shorthand into a function expression.
+        source = source.startsWith('async ') ? source.replace(/^async\s+/, 'async function ') : `function ${source}`;
+        evaluateBoolean = wrap(source);
+    }
+    let expired = false;
+    let deadlineTimer;
+    const timeoutReached = new Promise(resolve => {
+        deadlineTimer = setTimeout(() => { expired = true; resolve(); }, timeout);
+    });
+    const poll = async () => {
+        while (!expired && Date.now() < deadline) {
+            // Convert truthiness before serialization, including async DOM-element results.
+            if (await row.evaluate(evaluateBoolean, arg, { timeout: Math.max(1, deadline - Date.now()) }))
+                return;
+            if (expired || Date.now() >= deadline)
+                return;
+            await page.waitForTimeout(Math.min(interval, Math.max(0, deadline - Date.now())));
+        }
+    };
+    try {
+        // evaluate's timeout only bounds locator resolution, not an async predicate's promise.
+        await Promise.race([poll(), timeoutReached]);
+    }
+    finally {
+        clearTimeout(deadlineTimer);
+    }
+}
 exports.ContentReadyStrategies = {
+    /**
+     * Waits in the browser until `predicate(rowElement, arg)` returns a truthy value, e.g. until
+     * a skeleton placeholder is gone or every cell has rendered. Resolves when `timeout` expires
+     * even if the predicate never passed, like the other content-ready strategies.
+     *
+     * Uses `locator.waitForFunction` (Playwright 1.62+), which re-resolves the row on each retry
+     * and polls without a round-trip per check. Older versions poll via `locator.evaluate`.
+     * `timeout` and `interval` must be positive finite milliseconds. `interval` only controls
+     * the older-version fallback; native polling is controlled by Playwright.
+     *
+     * @example
+     * contentReady: Strategies.ContentReady.until(row => !row.querySelector('.skeleton'))
+     */
+    until: (predicate, options = {}) => {
+        var _a, _b;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : 500;
+        const interval = (_b = options.interval) !== null && _b !== void 0 ? _b : 50;
+        if (!Number.isFinite(timeout) || timeout <= 0) {
+            throw new Error('ContentReady.until: timeout must be a positive finite number');
+        }
+        if (!Number.isFinite(interval) || interval <= 0) {
+            throw new Error('ContentReady.until: interval must be a positive finite number');
+        }
+        const fn = predicate;
+        const arg = options.arg;
+        return async (row, page) => {
+            try {
+                if (typeof row.waitForFunction === 'function') {
+                    await row.waitForFunction(fn, arg, { timeout });
+                }
+                else {
+                    await pollPredicate(row, page, fn, arg, timeout, interval);
+                }
+            }
+            catch (error) {
+                if (!isTimeout(error))
+                    throw error;
+            }
+        };
+    },
     /**
      * Polls the row's text content until two consecutive reads match.
      */

package/dist/strategies/index.d.ts

@@ -98,6 +98,11 @@ export declare const Strategies: {
         dataAttribute: (options?: import("./viewport").DataAttributeViewportOptions) => import("..").ViewportStrategy;
     };
     ContentReady: {
+        until: <Arg = undefined>(predicate: import("..").RowReadyPredicate<Arg>, options?: {
+            arg?: Arg;
+            timeout?: number;
+            interval?: number;
+        }) => import("..").ContentReadyStrategy;
         textStable: (options?: {
             timeout?: number;
             interval?: number;

package/dist/types.d.ts

@@ -428,6 +428,8 @@ export interface PaginationPrimitives {
 export type PaginationStrategy = PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export type ContentReadyStrategy = (row: Locator, page: Page) => Promise<void>;
+/** Predicate for `Strategies.ContentReady.until`. Runs in the browser with the row element, so it must not close over test-side variables; pass values via `arg`. */
+export type RowReadyPredicate<Arg = undefined> = (row: HTMLElement | SVGElement, arg: Arg) => unknown;
 export type FillStrategy = (options: {
     row: SmartRow;
     columnName: string;
@@ -638,12 +640,18 @@ export interface TableStrategies {
      * Without this, the clone captures stale content from the previous occupant of the
      * DOM slot — the element is at the correct position but React hasn't re-rendered yet.
      *
-     * Use `Strategies.ContentReady.textStable()` for the built-in text-polling strategy.
+     * Built-ins: `Strategies.ContentReady.textStable()` (text stops changing),
+     * `mutationSettled()` (no DOM mutations for a quiet period), and `until(predicate)`
+     * (an in-browser condition holds, e.g. no skeleton placeholder).
      *
      * @example
      * strategies: {
      *   contentReady: Strategies.ContentReady.textStable({ timeout: 500 }),
      * }
+     * @example
+     * strategies: {
+     *   contentReady: Strategies.ContentReady.until(row => !row.querySelector('.skeleton')),
+     * }
      */
     contentReady?: ContentReadyStrategy;
     /**
@@ -794,6 +802,11 @@ export type RowIterationOptions = {
      * @default false — uses goNext for one-page-at-a-time advancement
      */
     useBulkPagination?: boolean;
+    /**
+     * Cancels the iteration between pages. When aborted, the call rejects with
+     * `signal.reason` (rows already processed are not returned).
+     */
+    signal?: AbortSignal;
 };
 /**
  * Result of {@link useTable}. Implements `AsyncIterable` — `for await (const { row } of table)`
@@ -876,31 +889,37 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * is not configured. Also throws if the row cannot be reached (no silent wrong-row fallback).
      *
      * @param index 0-based logical/data-model row index
-     * @param options - `maxPages` bounds how far to scroll/paginate (defaults to config.maxPages)
+     * @param options - `maxPages` bounds how far to scroll/paginate (defaults to config.maxPages).
+     * `signal` cancels the page scan; the call rejects with `signal.reason`.
      */
     findRowByIndex: (index: number, options?: {
         maxPages?: number;
+        signal?: AbortSignal;
     }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for a single row across pages using pagination.
      * Auto-initializes the table if not already initialized.
      * @param filters - The filter criteria to match
-     * @param options - Search options including exact match and max pages
+     * @param options - Search options including exact match and max pages. `signal` cancels the page scan; the call rejects with `signal.reason`.
      */
     findRow: (filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
+        signal?: AbortSignal;
     }) => Promise<SmartRow<T>>;
     /**
      * ASYNC: Searches for all matching rows across pages using pagination.
      * Auto-initializes the table if not already initialized.
+     * Returned rows can be read independently, including with `concurrency: 'synchronized'`.
+     * Use synchronized `map()` for coordinated column scrolling across virtualized rows.
      * @param filters - The filter criteria to match (omit or pass {} for all rows)
-     * @param options - Search options (exact, maxPages). `useBulkPagination` defaults to `false`: pages advance one at a time via `goNext` so no intermediate page is skipped. Set it to `true` to opt into `goNextBulk` (faster, but skips the rows on jumped-over pages).
+     * @param options - Search options (exact, maxPages). `useBulkPagination` defaults to `false`: pages advance one at a time via `goNext` so no intermediate page is skipped. Set it to `true` to opt into `goNextBulk` (faster, but skips the rows on jumped-over pages). `signal` cancels the page scan; the call rejects with `signal.reason`.
      */
     findRows: (filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
         useBulkPagination?: boolean;
+        signal?: AbortSignal;
     }) => Promise<SmartRowArray<T>>;
     /**
      * Resolves the named column and scrolls it into view.
@@ -911,11 +930,13 @@ export interface TableResult<T = any> extends AsyncIterable<{
     /**
      * Counts the number of rows, optionally filtered.
      * Without arguments, counts all rows. With filters, counts only matching rows.
-     * Paginates when pagination is configured.
+     * Paginates when pagination is configured. `signal` cancels the page scan; the call
+     * rejects with `signal.reason` (the table is still reset to page 1).
      */
     countRows: (filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
+        signal?: AbortSignal;
     }) => Promise<number>;
     /**
      * Iterates over rows and extracts the value of a single column.

package/dist/useTable.js

@@ -27,29 +27,15 @@ const filterEngine_1 = require("./filterEngine");
 const tableMapper_1 = require("./engine/tableMapper");
 const rowFinder_1 = require("./engine/rowFinder");
 const tableIteration_1 = require("./engine/tableIteration");
-const rowResolution_1 = require("./engine/rowResolution");
-const scanPages_1 = require("./engine/scanPages");
+const countRows_1 = require("./engine/countRows");
+const sorting_1 = require("./engine/sorting");
+const rowByIndex_1 = require("./engine/rowByIndex");
+const safeStringify_1 = require("./utils/safeStringify");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
-const elementTracker_1 = require("./utils/elementTracker");
-const loadingWait_1 = require("./utils/loadingWait");
 const pageIndex_1 = require("./utils/pageIndex");
 const smartRowInternals_1 = require("./utils/smartRowInternals");
 const locatorDescription_1 = require("./utils/locatorDescription");
-// Helper to safely serialize objects containing functions for logging
-const safeStringify = (obj) => {
-    try {
-        return JSON.stringify(obj, (_key, value) => {
-            if (typeof value === 'function') {
-                return '[Function]';
-            }
-            return value;
-        });
-    }
-    catch (e) {
-        return '[unserializable]';
-    }
-};
 /**
  * Main hook to interact with a table.
  */
@@ -238,6 +224,11 @@ const useTable = (rootLocator, configOptions = {}) => {
         }
         return didAdvance;
     };
+    const sortingEnv = () => ({
+        config,
+        getPage: () => rootLocator.page(),
+        getContext: () => (Object.assign(Object.assign({}, createStrategyContext()), { getHeaderCell: result.getHeaderCell })),
+    });
     const result = {
         get currentPageIndex() { return tableState.currentPageIndex; },
         set currentPageIndex(v) {
@@ -326,133 +317,24 @@ const useTable = (rootLocator, configOptions = {}) => {
             return resolve(config.headerSelector, rootLocator).nth(idx);
         },
         countRows: async (filters, options) => {
-            var _a, _b, _c, _d;
-            var _e;
             if (tableState.empty)
                 return 0;
             await _autoInit();
-            const filtersRecord = (filters !== null && filters !== void 0 ? filters : {});
-            const hasFilters = Object.keys(filtersRecord).length > 0;
-            const effectiveMaxPages = (_e = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _e !== void 0 ? _e : config.maxPages;
-            const pag = config.strategies.pagination;
-            const hasPagination = effectiveMaxPages > 1 && !!((pag === null || pag === void 0 ? void 0 : pag.goNext) || (pag === null || pag === void 0 ? void 0 : pag.goNextBulk));
-            const domFilters = {};
-            const overrideFilters = {};
-            const syntheticFilters = {};
-            if (hasFilters) {
-                for (const [key, value] of Object.entries(filtersRecord)) {
-                    if ((_a = config.syntheticColumns) === null || _a === void 0 ? void 0 : _a[key]) {
-                        syntheticFilters[key] = value;
-                    }
-                    else if ((_c = (_b = config.columnOverrides) === null || _b === void 0 ? void 0 : _b[key]) === null || _c === void 0 ? void 0 : _c.read) {
-                        overrideFilters[key] = value;
-                    }
-                    else {
-                        domFilters[key] = value;
-                    }
-                }
-            }
-            const hasPostFilters = Object.keys(overrideFilters).length > 0 || Object.keys(syntheticFilters).length > 0;
-            const resolveRows = () => {
-                var _a;
-                let rows = resolve(config.rowSelector, rootLocator);
-                if (Object.keys(domFilters).length > 0) {
-                    const map = tableMapper.getMapSync();
-                    if (!map)
-                        throw new Error('Initialization Error: Table map not available. Call "await table.init()" first.');
-                    rows = filterEngine.applyFilters(rows, domFilters, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, rootLocator.page(), rootLocator);
-                }
-                return rows;
-            };
-            const countPostFilterMatches = async (candidates, indices) => {
-                var _a;
-                if (!hasPostFilters)
-                    return indices.length;
-                const map = tableMapper.getMapSync();
-                if (!map)
-                    throw new Error('Initialization Error: Table map not available. Call "await table.init()" first.');
-                const exact = (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false;
-                const hasOverrides = Object.keys(overrideFilters).length > 0;
-                const hasSynthetics = Object.keys(syntheticFilters).length > 0;
-                let count = 0;
-                for (const idx of indices) {
-                    const row = candidates[idx];
-                    if (hasOverrides && !await rowFinder.matchesOverrideFilters(row, overrideFilters, map, exact))
-                        continue;
-                    if (hasSynthetics && !await rowFinder.matchesSyntheticFilters(row, syntheticFilters, map, exact))
-                        continue;
-                    count++;
-                }
-                return count;
-            };
-            // Wait for table to finish loading before counting
-            const isTableLoading = (_d = config.strategies.loading) === null || _d === void 0 ? void 0 : _d.isTableLoading;
-            if (isTableLoading) {
-                const ctx = createStrategyContext();
-                await (0, loadingWait_1.waitWhileTableLoading)(config, ctx, rootLocator.page(), 'countRows');
-            }
-            if (!hasPagination) {
-                log(`countRows: counting rows in current viewport (no pagination)${hasFilters ? ` filters=${safeStringify(filtersRecord)}` : ''}`);
-                if (!hasPostFilters)
-                    return resolveRows().count();
-                const all = await resolveRows().all();
-                return countPostFilterMatches(all, all.map((_, i) => i));
-            }
-            log(`countRows: paginating up to ${effectiveMaxPages} page(s)${hasFilters ? ` filters=${safeStringify(filtersRecord)}` : ''}`);
-            const tracker = new elementTracker_1.ElementTracker('countRows');
-            let total = 0;
-            let pagesScanned = 1;
-            let paginationError;
-            try {
-                const scanned = await (0, scanPages_1.scanPages)({
-                    advancePage: _advancePage,
-                    getCurrentPageIndex: () => tableState.currentPageIndex,
-                    config,
-                    waitForReady: async () => {
-                        if (!isTableLoading)
-                            return;
-                        const ctx = createStrategyContext();
-                        await (0, loadingWait_1.waitWhileTableLoading)(config, ctx, rootLocator.page(), 'countRows');
-                    },
-                }, async ({ pagesScanned: pageNum }) => {
-                    const rowLocators = resolveRows();
-                    const newIndices = await tracker.getUnseenIndices(rowLocators);
-                    const candidates = await rowLocators.all();
-                    const matched = await countPostFilterMatches(candidates, newIndices);
-                    total += matched;
-                    log(`countRows: page ${pageNum} — ${matched} row(s) (running total: ${total})`);
-                    return 'continue';
-                }, {
-                    maxPages: effectiveMaxPages,
-                    useBulk: false,
-                    label: 'countRows',
-                    finalScanOnEof: true,
-                });
-                pagesScanned = scanned.pagesScanned;
-            }
-            catch (e) {
-                paginationError = e;
-                throw e;
-            }
-            finally {
-                await tracker.cleanup(rootLocator.page());
-                // Always restore page 1, even if pagination threw mid-count (#348), so the table
-                // stays usable for callers that catch the error. If reset() itself fails, only let
-                // it surface when pagination succeeded — otherwise preserve the original error.
-                log(`countRows: ${total} total row(s) across ${pagesScanned} page(s) — resetting`);
-                try {
-                    await result.reset();
-                }
-                catch (resetError) {
-                    if (paginationError === undefined)
-                        throw resetError;
-                    (0, debugUtils_1.logDebug)(config, 'error', 'countRows: reset() failed after pagination error', resetError);
-                }
-            }
-            return total;
+            return (0, countRows_1.countRows)({
+                config,
+                rootLocator,
+                getRowLocators: () => resolve(config.rowSelector, rootLocator),
+                tableMapper,
+                filterEngine,
+                rowFinder,
+                advancePage: _advancePage,
+                getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
+                reset: () => result.reset(),
+            }, filters, options);
         },
         mapColumn: async (columnName, options = {}) => {
-            log(`mapColumn: column="${columnName}" options=${safeStringify(options)}`);
+            log(`mapColumn: column="${columnName}" options=${(0, safeStringify_1.safeStringify)(options)}`);
             await _autoInit();
             const map = await tableMapper.getMap();
             if (!map.has(columnName))
@@ -477,7 +359,7 @@ const useTable = (rootLocator, configOptions = {}) => {
          * Iterates over rows and extracts the value of a single column as strings.
          */
         getColumnValues: async (columnName, options = {}) => {
-            log(`getColumnValues: column="${columnName}" options=${safeStringify(options)}`);
+            log(`getColumnValues: column="${columnName}" options=${(0, safeStringify_1.safeStringify)(options)}`);
             const values = await result.mapColumn(columnName, options);
             return values.map(v => String(v));
         },
@@ -505,7 +387,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             log("Table revalidated.");
         },
         getRow: (filters, options = { exact: false }) => {
-            log(`getRow: filters=${safeStringify(filters)} exact=${options.exact}`);
+            log(`getRow: filters=${(0, safeStringify_1.safeStringify)(filters)} exact=${options.exact}`);
             const syntheticKeys = Object.keys(filters).filter(k => { var _a; return (_a = config.syntheticColumns) === null || _a === void 0 ? void 0 : _a[k]; });
             if (syntheticKeys.length > 0) {
                 throw new Error(`getRow() cannot filter by synthetic column(s): ${syntheticKeys.join(', ')}. ` +
@@ -533,67 +415,23 @@ const useTable = (rootLocator, configOptions = {}) => {
             return _makeSmart(rowLocator, map, index, undefined, undefined, undefined, true);
         },
         findRowByIndex: async (index, options) => {
-            var _a, _b;
-            log(`findRowByIndex: index=${index} options=${safeStringify(options)}`);
             await _autoInit();
-            const map = tableMapper.getMapSync();
-            const resolveRI = config.strategies.resolveRowIndex;
-            const viewport = config.strategies.viewport;
-            // Identifying a row by its logical index requires a resolveRowIndex strategy. Without one
-            // the library can only offer render-window-relative getRowByIndex, or filter-based findRow.
-            if (!resolveRI) {
-                throw new Error(`findRowByIndex(${index}) requires a strategies.resolveRowIndex to identify rows by their logical index. ` +
-                    `Configure one (e.g. read the grid's row-index attribute), or use getRowByIndex() (current render window) / findRow(filters).`);
-            }
-            let foundSelector;
-            // The currently-mounted row whose logical index === index, if any.
-            const findMounted = async () => {
-                const rows = await resolve(config.rowSelector, rootLocator).all();
-                for (const r of rows) {
-                    const result = await resolveRI(r);
-                    if (result === undefined)
-                        continue;
-                    const normalized = (0, rowResolution_1.normalizeRowIndexResult)(result);
-                    if (normalized.index === index) {
-                        foundSelector = normalized.selector;
-                        return r;
-                    }
-                }
-                return null;
-            };
-            // 1. Already mounted (no navigation needed)?
-            let loc = await findMounted();
-            // 2. Fast path: jump straight to it via the viewport's random-access scroll.
-            if (!loc && (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow)) {
-                log(`findRowByIndex: scrolling to row ${index}`);
-                await viewport.scrollToRow(createStrategyContext(), index);
-                loc = await findMounted();
-            }
-            // 3. Fallback: advance pages (on infinite-scroll tables, a "page" is a scroll step) until
-            //    the row is reached. Bounded by maxPages so an unreachable index can't loop forever.
-            if (!loc && config.strategies.pagination) {
-                const effectiveMaxPages = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-                let pagesScanned = 1;
-                while (!loc && pagesScanned < effectiveMaxPages) {
-                    if (!await _advancePage(false))
-                        break;
-                    pagesScanned++;
-                    loc = await findMounted();
-                }
-            }
-            if (!loc) {
-                throw new Error(`findRowByIndex(${index}): could not reach row ${index}. ` +
-                    `Ensure a viewport.scrollToRow or pagination can bring it into view (searched up to maxPages=${(_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages}).`);
-            }
-            await (0, debugUtils_1.debugDelay)(config, 'findRow');
-            return _makeSmart(loc, map, index, tableState.currentPageIndex, undefined, foundSelector);
+            return (0, rowByIndex_1.findRowByIndex)({
+                config,
+                getRowLocators: () => resolve(config.rowSelector, rootLocator),
+                getMap: () => tableMapper.getMapSync(),
+                advancePage: _advancePage,
+                getCurrentPageIndex: () => tableState.currentPageIndex,
+                getContext: () => createStrategyContext(),
+                makeSmartRow: (loc, map, idx, pageIdx, sel) => _makeSmart(loc, map, idx, pageIdx, undefined, sel),
+            }, index, options);
         },
         findRow: async (filters, options) => {
-            log(`findRow: filters=${safeStringify(filters)} options=${safeStringify(options)}`);
+            log(`findRow: filters=${(0, safeStringify_1.safeStringify)(filters)} options=${(0, safeStringify_1.safeStringify)(options)}`);
             return rowFinder.findRow(filters, options);
         },
         findRows: async (filters, options) => {
-            log(`findRows: filters=${safeStringify(filters !== null && filters !== void 0 ? filters : {})} options=${safeStringify(options)}`);
+            log(`findRows: filters=${(0, safeStringify_1.safeStringify)(filters !== null && filters !== void 0 ? filters : {})} options=${(0, safeStringify_1.safeStringify)(options)}`);
             return rowFinder.findRows(filters !== null && filters !== void 0 ? filters : {}, options);
         },
         isInitialized: () => {
@@ -606,49 +444,13 @@ const useTable = (rootLocator, configOptions = {}) => {
         },
         sorting: {
             apply: async (columnName, direction) => {
-                var _a, _b;
-                var _c, _d, _e, _f;
                 await _autoInit();
-                if (!config.strategies.sorting)
-                    throw new Error('No sorting strategy has been configured.');
-                log(`Applying sort for column "${columnName}" (${direction})`);
-                const context = Object.assign(Object.assign({}, createStrategyContext()), { getHeaderCell: result.getHeaderCell });
-                const maxRetries = 3;
-                for (let i = 0; i < maxRetries; i++) {
-                    const currentState = await config.strategies.sorting.getSortState({ columnName, context });
-                    if (currentState === direction) {
-                        log(`Sort for "${columnName}" is already "${direction}".`);
-                        return;
-                    }
-                    await config.strategies.sorting.doSort({ columnName, direction, context });
-                    if ((_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isTableLoading) {
-                        const timeout = (_d = (_c = config.strategies.loading.sortStabilizationTimeout) !== null && _c !== void 0 ? _c : config.strategies.loading.loadingTimeout) !== null && _d !== void 0 ? _d : 10000;
-                        const poll = (_e = config.strategies.loading.sortStabilizationPollInterval) !== null && _e !== void 0 ? _e : 100;
-                        await (0, loadingWait_1.waitWhileTableLoading)(config, context, rootLocator.page(), 'sorting.apply', {
-                            timeout,
-                            pollInterval: poll,
-                        });
-                    }
-                    else {
-                        const fallback = (_f = (_b = config.strategies.loading) === null || _b === void 0 ? void 0 : _b.sortStabilizationFallbackDelay) !== null && _f !== void 0 ? _f : 200;
-                        await rootLocator.page().waitForTimeout(fallback);
-                    }
-                    await (0, debugUtils_1.debugDelay)(config, 'default');
-                    const newState = await config.strategies.sorting.getSortState({ columnName, context });
-                    if (newState === direction) {
-                        log(`Successfully sorted "${columnName}" to "${direction}".`);
-                        return;
-                    }
-                }
-                throw new Error(`Failed to sort column "${columnName}" to "${direction}" after ${maxRetries} attempts.`);
+                return (0, sorting_1.applySort)(sortingEnv(), columnName, direction);
             },
             getState: async (columnName) => {
                 log(`sorting.getState: column="${columnName}"`);
                 await _autoInit();
-                if (!config.strategies.sorting)
-                    throw new Error('No sorting strategy has been configured.');
-                const context = Object.assign(Object.assign({}, createStrategyContext()), { getHeaderCell: result.getHeaderCell });
-                return config.strategies.sorting.getSortState({ columnName, context });
+                return (0, sorting_1.getSortState)(sortingEnv(), columnName);
             }
         },
         // ─── Shared async row iterator ───────────────────────────────────────────
@@ -716,7 +518,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         },
         // ─── Row iteration (delegated to engine/tableIteration) ──────────────────
         forEach: async (callback, options = {}) => {
-            log(`forEach: options=${safeStringify(options)}`);
+            log(`forEach: options=${(0, safeStringify_1.safeStringify)(options)}`);
             await _autoInit();
             await (0, tableIteration_1.runForEach)({
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
@@ -731,7 +533,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             }, callback, options);
         },
         map: async (callback, options = {}) => {
-            log(`map: options=${safeStringify(options)}`);
+            log(`map: options=${(0, safeStringify_1.safeStringify)(options)}`);
             await _autoInit();
             return (0, tableIteration_1.runMap)({
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
@@ -746,7 +548,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             }, callback, options);
         },
         toArray: async (callback, options = {}) => {
-            log(`toArray: options=${safeStringify(options)}`);
+            log(`toArray: options=${(0, safeStringify_1.safeStringify)(options)}`);
             const cb = callback !== null && callback !== void 0 ? callback : (({ row }) => row.toJSON());
             try {
                 return await result.map(cb, options);
@@ -756,7 +558,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
         },
         filter: async (predicate, options = {}) => {
-            log(`filter: options=${safeStringify(options)}`);
+            log(`filter: options=${(0, safeStringify_1.safeStringify)(options)}`);
             await _autoInit();
             return (0, tableIteration_1.runFilter)({
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),

package/dist/utils/navigationBarrier.js

@@ -51,7 +51,6 @@ class NavigationBarrier {
      * The fn receives a fresh `targetReached` check; if the previous row's scroll
      * already brought this row into view, fn can no-op immediately.
      */
-    // fallow-ignore-next-line unused-class-member
     async runExclusiveRecovery(fn) {
         if (!this.recoveryMutex)
             this.recoveryMutex = new mutex_1.Mutex();

package/dist/utils/safeStringify.d.ts

@@ -0,0 +1,2 @@
+/** JSON.stringify for debug logs: functions become "[Function]" and cycles don't throw. */
+export declare const safeStringify: (obj: any) => string;

package/dist/utils/safeStringify.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeStringify = void 0;
+/** JSON.stringify for debug logs: functions become "[Function]" and cycles don't throw. */
+const safeStringify = (obj) => {
+    try {
+        return JSON.stringify(obj, (_key, value) => {
+            if (typeof value === 'function') {
+                return '[Function]';
+            }
+            return value;
+        });
+    }
+    catch (e) {
+        return '[unserializable]';
+    }
+};
+exports.safeStringify = safeStringify;

package/dist/utils/smartRowArray.d.ts

@@ -4,7 +4,7 @@ import { SmartRow } from '../types';
  */
 export interface SmartRowArray<T = any> extends Array<SmartRow<T>> {
     /**
-     * Converts all rows to JSON objects
+     * Converts all rows to JSON objects, reading sequentially to avoid competing viewport moves.
      */
     toJSON(): Promise<T[]>;
 }