@rickcedwhat/playwright-smart-table 6.24.0-next.cc0fbcb → 6.25.0-next.0d74239

package/dist/useTable.js

@@ -27,28 +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");
-// 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]';
-    }
-};
+const locatorDescription_1 = require("./utils/locatorDescription");
 /**
  * Main hook to interact with a table.
  */
@@ -153,7 +140,13 @@ const useTable = (rootLocator, configOptions = {}) => {
         const effectiveLocator = healSelector
             ? rootLocator.locator(healSelector)
             : rowLocator;
-        const sr = (0, smartRow_1.default)(effectiveLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier, renderWindowPosition);
+        // Keep a caller-supplied description (e.g. the filters) across self-healing; otherwise name the row by index.
+        const existingDescription = (0, locatorDescription_1.getLocatorDescription)(rowLocator);
+        const description = existingDescription !== null && existingDescription !== void 0 ? existingDescription : (rowIndex !== undefined ? (0, locatorDescription_1.describeRowByIndex)(rowIndex) : undefined);
+        const describedLocator = description !== undefined && (healSelector !== undefined || existingDescription === undefined)
+            ? (0, locatorDescription_1.describeLocator)(effectiveLocator, description, config)
+            : effectiveLocator;
+        const sr = (0, smartRow_1.default)(describedLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier, renderWindowPosition);
         if (healSelector)
             (0, smartRowInternals_1.internals)(sr)._selfHealing = true;
         return sr;
@@ -231,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) {
@@ -319,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))
@@ -470,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));
         },
@@ -498,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(', ')}. ` +
@@ -514,7 +403,8 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw new Error('Initialization Error: You attempted to access a row before the table structure was mapped. Please call "await table.init()" once before using synchronous row access.');
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = filterEngine.applyFilters(allRows, filters, map, options.exact || false, rootLocator.page(), rootLocator);
-            return _makeSmart(matchedRows, map, undefined); // sync path cannot compute real index
+            const describedRows = (0, locatorDescription_1.describeLocator)(matchedRows, (0, locatorDescription_1.describeRowByFilters)(filters), config);
+            return _makeSmart(describedRows, map, undefined); // sync path cannot compute real index
         },
         getRowByIndex: (index) => {
             log(`getRowByIndex: index=${index}`);
@@ -525,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: () => {
@@ -598,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 ───────────────────────────────────────────
@@ -708,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),
@@ -723,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),
@@ -738,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);
@@ -748,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/locatorDescription.d.ts

@@ -0,0 +1,15 @@
+import type { Locator } from '@playwright/test';
+import type { FilterValue, FinalTableConfig } from '../types';
+/** `Name="Alice", Status=/act/i` — readable in traces, unlike JSON.stringify (which turns RegExp into `{}`). */
+export declare const formatFilters: (filters: Record<string, FilterValue>) => string;
+export declare const describeRowByFilters: (filters: Record<string, FilterValue>) => string;
+/** `SmartRow #3`, or `SmartRow #3 where Dept="Eng"` when the row came from a filtered search. */
+export declare const describeRowByIndex: (rowIndex: number, filters?: Record<string, FilterValue>) => string;
+export declare const describeSentinelRow: (filters: Record<string, FilterValue>) => string;
+/**
+ * Applies `locator.describe()` (Playwright 1.53+) so traces, HTML reports and error messages show a
+ * readable name instead of the raw selector chain. Older Playwright versions get the locator back unchanged.
+ */
+export declare const describeLocator: (locator: Locator, description: string, config?: FinalTableConfig) => Locator;
+/** The description already applied to a locator, or undefined (unsupported or never described). */
+export declare const getLocatorDescription: (locator: Locator) => string | undefined;

package/dist/utils/locatorDescription.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLocatorDescription = exports.describeLocator = exports.describeSentinelRow = exports.describeRowByIndex = exports.describeRowByFilters = exports.formatFilters = void 0;
+const debugUtils_1 = require("./debugUtils");
+const MAX_VALUE_LENGTH = 40;
+const locatorDescriptions = new WeakMap();
+let loggedUnsupported = false;
+const formatFilterValue = (value) => {
+    if (value instanceof RegExp)
+        return value.toString();
+    if (typeof value === 'function')
+        return '<locator filter>';
+    if (typeof value === 'number')
+        return String(value);
+    const text = value.length > MAX_VALUE_LENGTH ? `${value.slice(0, MAX_VALUE_LENGTH)}…` : value;
+    return JSON.stringify(text);
+};
+/** `Name="Alice", Status=/act/i` — readable in traces, unlike JSON.stringify (which turns RegExp into `{}`). */
+const formatFilters = (filters) => Object.entries(filters).map(([col, value]) => `${col}=${formatFilterValue(value)}`).join(', ');
+exports.formatFilters = formatFilters;
+const describeRowByFilters = (filters) => {
+    const formatted = (0, exports.formatFilters)(filters);
+    return formatted ? `SmartRow where ${formatted}` : 'SmartRow';
+};
+exports.describeRowByFilters = describeRowByFilters;
+/** `SmartRow #3`, or `SmartRow #3 where Dept="Eng"` when the row came from a filtered search. */
+const describeRowByIndex = (rowIndex, filters = {}) => {
+    const formatted = (0, exports.formatFilters)(filters);
+    return formatted ? `SmartRow #${rowIndex} where ${formatted}` : `SmartRow #${rowIndex}`;
+};
+exports.describeRowByIndex = describeRowByIndex;
+const describeSentinelRow = (filters) => {
+    const formatted = (0, exports.formatFilters)(filters);
+    return formatted ? `SmartRow not found: ${formatted}` : 'SmartRow not found';
+};
+exports.describeSentinelRow = describeSentinelRow;
+/**
+ * Applies `locator.describe()` (Playwright 1.53+) so traces, HTML reports and error messages show a
+ * readable name instead of the raw selector chain. Older Playwright versions get the locator back unchanged.
+ */
+const describeLocator = (locator, description, config) => {
+    if (typeof locator.describe === 'function') {
+        const described = locator.describe(description);
+        locatorDescriptions.set(described, description);
+        return described;
+    }
+    if ((config === null || config === void 0 ? void 0 : config.debug) && !loggedUnsupported) {
+        loggedUnsupported = true;
+        (0, debugUtils_1.logDebug)(config, 'info', 'Upgrade @playwright/test to 1.53+ to see SmartRow / SmartCell names in traces and error messages');
+    }
+    return locator;
+};
+exports.describeLocator = describeLocator;
+/** The description already applied to a locator, or undefined (unsupported or never described). */
+const getLocatorDescription = (locator) => { var _a; return typeof locator.description === 'function' ? (_a = locator.description()) !== null && _a !== void 0 ? _a : undefined : locatorDescriptions.get(locator); };
+exports.getLocatorDescription = getLocatorDescription;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.24.0-next.cc0fbcb",
+  "version": "6.25.0-next.0d74239",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",