@rickcedwhat/playwright-smart-table 6.24.0 → 6.25.0-next.49ce2de

package/dist/engine/countRows.d.ts

@@ -0,0 +1,27 @@
+import type { Locator } from '@playwright/test';
+import type { FilterValue, FinalTableConfig, TableContext } from '../types';
+import type { FilterEngine } from '../filterEngine';
+import type { TableMapper } from './tableMapper';
+import type { RowFinder } from './rowFinder';
+export interface CountRowsEnv<T = any> {
+    config: FinalTableConfig<T>;
+    rootLocator: Locator;
+    getRowLocators: () => Locator;
+    tableMapper: TableMapper;
+    filterEngine: FilterEngine;
+    rowFinder: RowFinder<T>;
+    advancePage: (useBulk: boolean) => Promise<boolean>;
+    getCurrentPageIndex: () => number;
+    getContext: () => TableContext;
+    /** Restores page 1 after a paginated count. */
+    reset: () => Promise<void>;
+}
+/**
+ * Counts matching rows on the current page, or across pages when pagination and
+ * `maxPages > 1` allow it. A paginated count always resets to page 1 afterwards (#348).
+ * Callers must have initialized the table.
+ */
+export declare function countRows<T>(env: CountRowsEnv<T>, filters?: Record<string, FilterValue>, options?: {
+    exact?: boolean;
+    maxPages?: number;
+}): Promise<number>;

package/dist/engine/countRows.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countRows = countRows;
+const scanPages_1 = require("./scanPages");
+const elementTracker_1 = require("../utils/elementTracker");
+const debugUtils_1 = require("../utils/debugUtils");
+const loadingWait_1 = require("../utils/loadingWait");
+const safeStringify_1 = require("../utils/safeStringify");
+function log(config, msg) {
+    (0, debugUtils_1.logDebug)(config, 'verbose', msg);
+}
+/** Splits filters by how they're evaluated: DOM text, `columnOverrides.read`, or synthetic columns. */
+function partitionFilters(config, filters) {
+    var _a, _b, _c;
+    const domFilters = {};
+    const overrideFilters = {};
+    const syntheticFilters = {};
+    for (const [key, value] of Object.entries(filters)) {
+        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;
+        }
+    }
+    return { domFilters, overrideFilters, syntheticFilters };
+}
+function requireMap(tableMapper) {
+    const map = tableMapper.getMapSync();
+    if (!map)
+        throw new Error('Initialization Error: Table map not available. Call "await table.init()" first.');
+    return map;
+}
+/**
+ * Counts matching rows on the current page, or across pages when pagination and
+ * `maxPages > 1` allow it. A paginated count always resets to page 1 afterwards (#348).
+ * Callers must have initialized the table.
+ */
+async function countRows(env, filters, options) {
+    var _a;
+    var _b, _c;
+    const { config, rootLocator, tableMapper, rowFinder } = env;
+    const filtersRecord = filters !== null && filters !== void 0 ? filters : {};
+    const hasFilters = Object.keys(filtersRecord).length > 0;
+    const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : 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 exact = (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false;
+    const { domFilters, overrideFilters, syntheticFilters } = partitionFilters(config, filtersRecord);
+    const hasOverrides = Object.keys(overrideFilters).length > 0;
+    const hasSynthetics = Object.keys(syntheticFilters).length > 0;
+    const hasPostFilters = hasOverrides || hasSynthetics;
+    const resolveRows = () => {
+        const rows = env.getRowLocators();
+        if (Object.keys(domFilters).length === 0)
+            return rows;
+        return env.filterEngine.applyFilters(rows, domFilters, requireMap(tableMapper), exact, rootLocator.page(), rootLocator);
+    };
+    const countPostFilterMatches = async (candidates, indices) => {
+        if (!hasPostFilters)
+            return indices.length;
+        const map = requireMap(tableMapper);
+        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;
+    };
+    const isTableLoading = (_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isTableLoading;
+    const waitForReady = async () => {
+        if (!isTableLoading)
+            return;
+        await (0, loadingWait_1.waitWhileTableLoading)(config, env.getContext(), rootLocator.page(), 'countRows');
+    };
+    await waitForReady();
+    const filterSuffix = hasFilters ? ` filters=${(0, safeStringify_1.safeStringify)(filtersRecord)}` : '';
+    if (!hasPagination) {
+        log(config, `countRows: counting rows in current viewport (no pagination)${filterSuffix}`);
+        if (!hasPostFilters)
+            return resolveRows().count();
+        const all = await resolveRows().all();
+        return countPostFilterMatches(all, all.map((_, i) => i));
+    }
+    log(config, `countRows: paginating up to ${effectiveMaxPages} page(s)${filterSuffix}`);
+    const tracker = new elementTracker_1.ElementTracker('countRows');
+    let total = 0;
+    let pagesScanned = 1;
+    let paginationError;
+    try {
+        const scanned = await (0, scanPages_1.scanPages)({
+            advancePage: env.advancePage,
+            getCurrentPageIndex: env.getCurrentPageIndex,
+            config,
+            waitForReady,
+        }, 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(config, `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(config, `countRows: ${total} total row(s) across ${pagesScanned} page(s) — resetting`);
+        try {
+            await env.reset();
+        }
+        catch (resetError) {
+            if (paginationError === undefined)
+                throw resetError;
+            (0, debugUtils_1.logDebug)(config, 'error', 'countRows: reset() failed after pagination error', resetError);
+        }
+    }
+    return total;
+}

package/dist/engine/rowByIndex.d.ts

@@ -0,0 +1,19 @@
+import type { Locator } from '@playwright/test';
+import type { FinalTableConfig, SmartRow, TableContext } from '../types';
+export interface RowByIndexEnv<T = any> {
+    config: FinalTableConfig<T>;
+    getRowLocators: () => Locator;
+    getMap: () => Map<string, number>;
+    advancePage: (useBulk: boolean) => Promise<boolean>;
+    getCurrentPageIndex: () => number;
+    getContext: () => TableContext;
+    makeSmartRow: (rowLocator: Locator, map: Map<string, number>, rowIndex: number, tablePageIndex: number, healSelector?: string) => SmartRow<T>;
+}
+/**
+ * Finds the row whose logical index (per `strategies.resolveRowIndex`) is `index`:
+ * already mounted, else via `viewport.scrollToRow`, else by advancing pages until it
+ * mounts (bounded by `maxPages`). Callers must have initialized the table.
+ */
+export declare function findRowByIndex<T>(env: RowByIndexEnv<T>, index: number, options?: {
+    maxPages?: number;
+}): Promise<SmartRow<T>>;

package/dist/engine/rowByIndex.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findRowByIndex = findRowByIndex;
+const rowResolution_1 = require("./rowResolution");
+const scanPages_1 = require("./scanPages");
+const debugUtils_1 = require("../utils/debugUtils");
+const safeStringify_1 = require("../utils/safeStringify");
+/**
+ * Finds the row whose logical index (per `strategies.resolveRowIndex`) is `index`:
+ * already mounted, else via `viewport.scrollToRow`, else by advancing pages until it
+ * mounts (bounded by `maxPages`). Callers must have initialized the table.
+ */
+async function findRowByIndex(env, index, options) {
+    var _a;
+    const { config } = env;
+    (0, debugUtils_1.logDebug)(config, 'verbose', `findRowByIndex: index=${index} options=${(0, safeStringify_1.safeStringify)(options)}`);
+    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 env.getRowLocators().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)) {
+        (0, debugUtils_1.logDebug)(config, 'verbose', `findRowByIndex: scrolling to row ${index}`);
+        await viewport.scrollToRow(env.getContext(), index);
+        loc = await findMounted();
+    }
+    // 3. Fallback: advance pages (on infinite-scroll tables, a "page" is a scroll step) until
+    //    the row is mounted. Page 1 was already searched above.
+    const maxPages = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
+    const scanForMounted = async () => {
+        let hit = null;
+        await (0, scanPages_1.scanPages)({ advancePage: env.advancePage, getCurrentPageIndex: env.getCurrentPageIndex, config }, async ({ pagesScanned }) => {
+            if (pagesScanned > 1)
+                hit = await findMounted();
+            return hit ? 'stop' : 'continue';
+        }, { maxPages, useBulk: false, label: 'findRowByIndex', finalScanOnEof: false });
+        return hit;
+    };
+    if (!loc && config.strategies.pagination) {
+        loc = await scanForMounted();
+    }
+    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=${maxPages}).`);
+    }
+    await (0, debugUtils_1.debugDelay)(config, 'findRow');
+    return env.makeSmartRow(loc, env.getMap(), index, env.getCurrentPageIndex(), foundSelector);
+}

package/dist/engine/rowFinder.d.ts

@@ -25,6 +25,8 @@ export declare class RowFinder<T = any> {
         maxPages?: number;
     }): Promise<SmartRow<T>>;
     private waitForTableReady;
+    /** Unfiltered rows keep the plain `SmartRow #n` name that `_makeSmart` applies. */
+    private nameFilteredRow;
     findRows(filters?: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;

package/dist/engine/rowFinder.js

@@ -9,6 +9,7 @@ const navigationBarrier_1 = require("../utils/navigationBarrier");
 const rowResolution_1 = require("./rowResolution");
 const resolveCellLocator_1 = require("../utils/resolveCellLocator");
 const scanPages_1 = require("./scanPages");
+const locatorDescription_1 = require("../utils/locatorDescription");
 const loadingWait_1 = require("../utils/loadingWait");
 class RowFinder {
     constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow, tableState = { currentPageIndex: 0 }, advancePage = async () => false) {
@@ -111,12 +112,13 @@ class RowFinder {
             await (0, debugUtils_1.debugDelay)(this.config, 'findRow');
             const map = await this.tableMapper.getMap();
             const resolved = await this.resolveRowIndex(rowLocator);
-            return this.makeSmartRow(rowLocator, map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, undefined, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
+            const describedRow = (0, locatorDescription_1.describeLocator)(rowLocator, (0, locatorDescription_1.describeRowByFilters)(filters), this.config);
+            return this.makeSmartRow(describedRow, map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, undefined, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
         }
         (0, debugUtils_1.logDebug)(this.config, 'error', 'Row not found', filters);
         await (0, debugUtils_1.debugDelay)(this.config, 'findRow');
-        const sentinel = this.resolve(this.config.rowSelector, this.rootLocator)
-            .filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
+        const sentinel = (0, locatorDescription_1.describeLocator)(this.resolve(this.config.rowSelector, this.rootLocator)
+            .filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() }), (0, locatorDescription_1.describeSentinelRow)(filters), this.config);
         const smartRow = this.makeSmartRow(sentinel, await this.tableMapper.getMap(), undefined);
         smartRow[sentinel_1.SENTINEL_ROW] = true;
         return smartRow;
@@ -134,6 +136,12 @@ class RowFinder {
         };
         await (0, loadingWait_1.waitWhileTableLoading)(this.config, context, this.rootLocator.page(), 'waitForTableReady');
     }
+    /** Unfiltered rows keep the plain `SmartRow #n` name that `_makeSmart` applies. */
+    nameFilteredRow(row, resolved, filters) {
+        if (!resolved || Object.keys(filters).length === 0)
+            return row;
+        return (0, locatorDescription_1.describeLocator)(row, (0, locatorDescription_1.describeRowByIndex)(resolved.index, filters), this.config);
+    }
     async findRows(filters = {}, options) {
         var _a;
         var _b, _c;
@@ -168,7 +176,8 @@ class RowFinder {
                 const barrier = useBarrier ? new navigationBarrier_1.NavigationBarrier(newIndices.length) : undefined;
                 for (const idx of newIndices) {
                     const resolved = await (0, rowResolution_1.resolveLogicalRowIndex)(currentRows[idx], this.config, () => allRows.length);
-                    const smartRow = this.makeSmartRow(currentRows[idx], map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
+                    const rowLocator = this.nameFilteredRow(currentRows[idx], resolved, filtersRecord);
+                    const smartRow = this.makeSmartRow(rowLocator, map, resolved === null || resolved === void 0 ? void 0 : resolved.index, this.tableState.currentPageIndex, barrier, resolved === null || resolved === void 0 ? void 0 : resolved.selector);
                     const loadingOutcome = await (0, rowResolution_1.resolveRowLoading)(smartRow, this.config.strategies.loading, 'skip', (msg) => (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: ${msg}`));
                     if (loadingOutcome !== 'process') {
                         barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();

package/dist/engine/scanPages.d.ts

@@ -21,10 +21,10 @@ import type { FinalTableConfig } from '../types';
  * | findRow | yes | options.useBulkPagination | yes | DOM/post filters only |
  * | countRows | yes | no (single-step) | yes | count-only / post filters |
  * | async iterator | yes | no | via runMap path | same as map |
- * | findRowByIndex | no* | no | n/a | scroll/search, not a full scan |
+ * | findRowByIndex | no | no | no | stops once the target index is mounted* |
  * | bringIntoView | n/a | path planner | n/a | not a page scan |
  *
- * \* findRowByIndex stops when the target index is mounted; it does not collect rows.
+ * \* findRowByIndex only falls back to scanPages after the mounted / viewport.scrollToRow paths miss.
  */
 export type ScanDecision = 'continue' | 'stop';
 export interface ScanPageContext {

package/dist/engine/sorting.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from '@playwright/test';
+import type { FinalTableConfig, StrategyContext } from '../types';
+export interface SortingEnv<T = any> {
+    config: FinalTableConfig<T>;
+    getPage: () => Page;
+    /** Strategy context including `getHeaderCell`. */
+    getContext: () => StrategyContext;
+}
+/** Drives the sorting strategy until `columnName` reports `direction`, retrying up to 3 times. */
+export declare function applySort<T>(env: SortingEnv<T>, columnName: string, direction: 'asc' | 'desc'): Promise<void>;
+export declare function getSortState<T>(env: SortingEnv<T>, columnName: string): Promise<'asc' | 'desc' | 'none'>;

package/dist/engine/sorting.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySort = applySort;
+exports.getSortState = getSortState;
+const debugUtils_1 = require("../utils/debugUtils");
+const loadingWait_1 = require("../utils/loadingWait");
+const MAX_SORT_ATTEMPTS = 3;
+function requireSorting(config) {
+    if (!config.strategies.sorting)
+        throw new Error('No sorting strategy has been configured.');
+    return config.strategies.sorting;
+}
+/** Waits for the table to settle after `doSort`: `isTableLoading` when configured, otherwise a fixed delay. */
+async function waitForSortToSettle(env, context) {
+    var _a, _b, _c, _d;
+    const loading = env.config.strategies.loading;
+    if (loading === null || loading === void 0 ? void 0 : loading.isTableLoading) {
+        const timeout = (_b = (_a = loading.sortStabilizationTimeout) !== null && _a !== void 0 ? _a : loading.loadingTimeout) !== null && _b !== void 0 ? _b : 10000;
+        const pollInterval = (_c = loading.sortStabilizationPollInterval) !== null && _c !== void 0 ? _c : 100;
+        await (0, loadingWait_1.waitWhileTableLoading)(env.config, context, env.getPage(), 'sorting.apply', { timeout, pollInterval });
+    }
+    else {
+        await env.getPage().waitForTimeout((_d = loading === null || loading === void 0 ? void 0 : loading.sortStabilizationFallbackDelay) !== null && _d !== void 0 ? _d : 200);
+    }
+}
+/** Drives the sorting strategy until `columnName` reports `direction`, retrying up to 3 times. */
+async function applySort(env, columnName, direction) {
+    const sorting = requireSorting(env.config);
+    (0, debugUtils_1.logDebug)(env.config, 'verbose', `Applying sort for column "${columnName}" (${direction})`);
+    const context = env.getContext();
+    for (let i = 0; i < MAX_SORT_ATTEMPTS; i++) {
+        const currentState = await sorting.getSortState({ columnName, context });
+        if (currentState === direction) {
+            (0, debugUtils_1.logDebug)(env.config, 'verbose', `Sort for "${columnName}" is already "${direction}".`);
+            return;
+        }
+        await sorting.doSort({ columnName, direction, context });
+        await waitForSortToSettle(env, context);
+        await (0, debugUtils_1.debugDelay)(env.config, 'default');
+        const newState = await sorting.getSortState({ columnName, context });
+        if (newState === direction) {
+            (0, debugUtils_1.logDebug)(env.config, 'verbose', `Successfully sorted "${columnName}" to "${direction}".`);
+            return;
+        }
+    }
+    throw new Error(`Failed to sort column "${columnName}" to "${direction}" after ${MAX_SORT_ATTEMPTS} attempts.`);
+}
+async function getSortState(env, columnName) {
+    const sorting = requireSorting(env.config);
+    return sorting.getSortState({ columnName, context: env.getContext() });
+}

package/dist/engine/tableIteration.js

@@ -45,8 +45,9 @@ async function runMap(env, callback, options = {}, label = 'map') {
         let rowIndex = 0;
         let stopped = false;
         let stoppedIndex = Infinity;
+        // In parallel/synchronized mode rows can call stop() out of order; the earliest row wins.
         const stop = (idx) => {
-            if (!stopped) {
+            if (idx < stoppedIndex) {
                 log(env.config, `${label}: stop() called at row ${idx} — halting`);
                 stopped = true;
                 stoppedIndex = idx;

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.24.0";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.25.0-next.49ce2de";

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.24.0";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.25.0-next.49ce2de";

package/dist/presets/glide/index.js

@@ -102,7 +102,6 @@ const GlideDefaultStrategies = {
     getActiveCell: glideGetActiveCell
 };
 /** Strategies only for Glide Data Grid. Includes fillSimple; use when you want to supply your own selectors or override fill. */
-// fallow-ignore-next-line unused-export
 exports.GlideStrategies = Object.assign(Object.assign({}, GlideDefaultStrategies), { fillSimple: glideFillSimple });
 /**
  * Factory that returns a configured Glide preset.

package/dist/presets/rdg.js

@@ -99,7 +99,6 @@ const RDGDefaultStrategies = {
     pagination: rdgPaginationStrategy
 };
 /** Full strategies for React Data Grid. Use when you want to supply your own selectors: `strategies: presets.rdg.Strategies` */
-// fallow-ignore-next-line unused-export
 exports.RDGStrategies = RDGDefaultStrategies;
 /**
  * Full preset for React Data Grid (selectors + default strategies).
@@ -174,7 +173,6 @@ const rdg2DViewportStrategy = {
 };
 /** Default strategies for the RDG2D preset (extends RDG with viewport recovery). */
 const RDG2DDefaultStrategies = Object.assign(Object.assign({}, RDGDefaultStrategies), { viewport: rdg2DViewportStrategy });
-// fallow-ignore-next-line unused-export
 exports.RDG2DStrategies = RDG2DDefaultStrategies;
 /**
  * Full preset for React Data Grid with 2D virtualization (rows + columns both virtualized).

package/dist/smartRow.js

@@ -7,6 +7,7 @@ const debugUtils_1 = require("./utils/debugUtils");
 const paginationPath_1 = require("./utils/paginationPath");
 const sentinel_1 = require("./utils/sentinel");
 const pageIndex_1 = require("./utils/pageIndex");
+const locatorDescription_1 = require("./utils/locatorDescription");
 /**
  * Internal helper to navigate to a cell with active cell optimization.
  * Uses `strategies.navigation` primitives (goUp/goDown/goLeft/goRight, optional snap/seek/goHome).
@@ -328,7 +329,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
     // Attach Methods
     smart.getCell = (colName) => {
         var _a;
-        var _b;
+        var _b, _c;
         if ((_a = config.syntheticColumns) === null || _a === void 0 ? void 0 : _a[colName]) {
             throw new Error(`Column "${colName}" is synthetic (no DOM cell) — use getValue("${colName}") or toJSON() instead`);
         }
@@ -351,7 +352,8 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         else {
             baseLocator = resolve(config.cellSelector, rowLocator).nth(idx);
         }
-        const smartCell = baseLocator;
+        const cellDescription = `${(_c = (0, locatorDescription_1.getLocatorDescription)(rowLocator)) !== null && _c !== void 0 ? _c : 'SmartRow'} › "${colName}" cell`;
+        const smartCell = (0, locatorDescription_1.describeLocator)(baseLocator, cellDescription, config);
         smartCell.bringIntoView = async () => {
             const page = rootLocator.page();
             const navigatedCell = await _navigateToCell({
@@ -850,36 +852,44 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 barrier: smart._barrier
             });
             const columnOverride = (_b = config.columnOverrides) === null || _b === void 0 ? void 0 : _b[colName];
-            if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) {
-                const cellLocator = smart.getCell(colName);
-                let currentValue;
-                if (columnOverride.read) {
-                    currentValue = await columnOverride.read(cellLocator, {
-                        row: smart, columnName: colName, columnIndex: colIdx,
-                        getCell: (name) => smart.getCell(name),
+            try {
+                if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) {
+                    const cellLocator = smart.getCell(colName);
+                    let currentValue;
+                    if (columnOverride.read) {
+                        currentValue = await columnOverride.read(cellLocator, {
+                            row: smart, columnName: colName, columnIndex: colIdx,
+                            getCell: (name) => smart.getCell(name),
+                        });
+                    }
+                    await columnOverride.write({
+                        cell: cellLocator,
+                        targetValue: value,
+                        currentValue,
+                        row: smart
+                    });
+                }
+                else {
+                    const strategy = config.strategies.fill || fill_1.FillStrategies.default;
+                    (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);
+                    await strategy({
+                        row: smart,
+                        columnName: colName,
+                        value,
+                        index: rowIndex !== null && rowIndex !== void 0 ? rowIndex : -1,
+                        page: rowLocator.page(),
+                        rootLocator,
+                        config,
+                        table: table,
+                        fillOptions
                     });
                 }
-                await columnOverride.write({
-                    cell: cellLocator,
-                    targetValue: value,
-                    currentValue,
-                    row: smart
-                });
             }
-            else {
-                const strategy = config.strategies.fill || fill_1.FillStrategies.default;
-                (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);
-                await strategy({
-                    row: smart,
-                    columnName: colName,
-                    value,
-                    index: rowIndex !== null && rowIndex !== void 0 ? rowIndex : -1,
-                    page: rowLocator.page(),
-                    rootLocator,
-                    config,
-                    table: table,
-                    fillOptions
-                });
+            catch (err) {
+                const source = (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.write) ? 'columnOverrides.write' : 'fill strategy';
+                const wrapped = new Error(`[SmartTable] smartFill: ${source} for "${colName}" failed — ${err instanceof Error ? err.message : String(err)}`);
+                wrapped.cause = err;
+                throw wrapped;
             }
             // Delay after filling
             await (0, debugUtils_1.debugDelay)(config, 'getCell');

package/dist/strategies/contentReady.d.ts

@@ -1,5 +1,4 @@
 import type { ContentReadyStrategy } from '../types';
-export type { ContentReadyStrategy };
 export declare const ContentReadyStrategies: {
     /**
      * Polls the row's text content until two consecutive reads match.

package/dist/strategies/index.d.ts

@@ -3,7 +3,6 @@ export * from './sorting';
 export * from './columns';
 export * from './headers';
 export * from './fill';
-export type { ColumnResolutionStrategy } from './resolution';
 export * from './dedupe';
 export * from './loading';
 export * from './stabilization';
@@ -102,10 +101,10 @@ export declare const Strategies: {
         textStable: (options?: {
             timeout?: number;
             interval?: number;
-        }) => import("./contentReady").ContentReadyStrategy;
+        }) => import("..").ContentReadyStrategy;
         mutationSettled: (options?: {
             timeout?: number;
             quietPeriod?: number;
-        }) => import("./contentReady").ContentReadyStrategy;
+        }) => import("..").ContentReadyStrategy;
     };
 };

package/dist/strategies/resolution.d.ts

@@ -1,4 +1,5 @@
 import { StrategyContext } from '../types';
+/** @deprecated Not used by the library. Will be removed in v7. */
 export interface ColumnResolutionStrategy {
     /**
      * Resolves a column name (string or Regex) to a column index.
@@ -17,6 +18,3 @@ export interface ColumnResolutionStrategy {
         headerMap: Map<string, number>;
     }): string;
 }
-export declare const ResolutionStrategies: {
-    default: ColumnResolutionStrategy;
-};

package/dist/strategies/resolution.js

@@ -1,30 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResolutionStrategies = void 0;
-exports.ResolutionStrategies = {
-    default: {
-        resolveIndex: ({ query, headerMap }) => {
-            // 1. Exact / String Match
-            if (typeof query === 'string') {
-                if (headerMap.has(query))
-                    return headerMap.get(query);
-            }
-            // 2. Regex Match
-            if (query instanceof RegExp) {
-                for (const [colName, idx] of headerMap.entries()) {
-                    if (query.test(colName))
-                        return idx;
-                }
-                return undefined;
-            }
-            // 3. (Optional) Fuzzy String Match fallback could go here
-            // But for strict default strategy, we might want to keep it simple first
-            // The original code didn't do fuzzy *resolution* logic inside the get(), it just did strict get().
-            // The fuzzy logic was only for *suggestions* on error.
-            return undefined;
-        },
-        resolveName: ({ query }) => {
-            return query.toString();
-        }
-    }
-};