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

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();
@@ -195,6 +204,7 @@ class RowFinder {
                 useBulk,
                 label: 'findRows',
                 finalScanOnEof: hasPagination,
+                signal: options === null || options === void 0 ? void 0 : options.signal,
             });
             (0, debugUtils_1.logDebug)(this.config, 'verbose', `findRows: done — ${allRows.length} row(s) collected across ${pagesScanned} page(s)`);
         }
@@ -259,6 +269,7 @@ class RowFinder {
             useBulk,
             label: 'findRow',
             finalScanOnEof: true,
+            signal: options.signal,
         });
         return found;
     }

package/dist/engine/rowSnapshot.d.ts

@@ -0,0 +1,28 @@
+import type { Locator, Page } from '@playwright/test';
+import type { FinalTableConfig, SmartRow, TableResult } from '../types';
+import type { SmartRowInternals } from '../utils/smartRowInternals';
+/** Everything `toJSON` needs from the SmartRow being read. */
+export interface RowSnapshotEnv<T = any> {
+    config: FinalTableConfig<T>;
+    rootLocator: Locator;
+    resolve: (item: any, parent: Locator | Page) => Locator;
+    map: Map<string, number>;
+    row: SmartRow<T> & SmartRowInternals;
+    rowLocator: Locator;
+    rowIndex: number | undefined;
+    table: TableResult<T> | null;
+    renderWindowPosition: boolean;
+}
+/** `getHeaderCell` for strategy hooks: the table's when available, else an index lookup. */
+export declare function headerCellGetter<T>(env: Pick<RowSnapshotEnv<T>, 'config' | 'rootLocator' | 'resolve' | 'map' | 'table'>): (columnName: string) => Promise<Locator>;
+/**
+ * `toJSON({ atomic: true })`: snapshot the row in a single evaluate, then apply column
+ * overrides against a frozen reconstruction. Zero inter-column stagger — even in-place
+ * React re-renders can't affect it because overrides read from a detached clone.
+ */
+export declare function readRowAtomic<T>(env: RowSnapshotEnv<T>, columns?: string[]): Promise<T>;
+/**
+ * Default `toJSON()`: reads each column from the live DOM, navigating to it first
+ * (keeps synchronized batches in lock-step) and re-pinning the row before each read.
+ */
+export declare function readRowLive<T>(env: RowSnapshotEnv<T>, columns?: string[]): Promise<T>;

package/dist/engine/rowSnapshot.js

@@ -0,0 +1,407 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.headerCellGetter = headerCellGetter;
+exports.readRowAtomic = readRowAtomic;
+exports.readRowLive = readRowLive;
+const rowResolution_1 = require("./rowResolution");
+const cellNavigation_1 = require("./cellNavigation");
+const debugUtils_1 = require("../utils/debugUtils");
+/** `getHeaderCell` for strategy hooks: the table's when available, else an index lookup. */
+function headerCellGetter(env) {
+    const { table } = env;
+    return (table === null || table === void 0 ? void 0 : table.getHeaderCell)
+        ? table.getHeaderCell.bind(table)
+        : async (colName) => {
+            const idx = env.map.get(colName);
+            if (idx === undefined)
+                throw new Error(`Column "${colName}" not found`);
+            return env.resolve(env.config.headerSelector, env.rootLocator).nth(idx);
+        };
+}
+/** Adds synthetic columns to `result`; their compute() reads already-read columns from `result`. */
+async function computeSyntheticColumns(env, result, columns) {
+    var _a;
+    const smart = env.row;
+    for (const [name, def] of Object.entries((_a = env.config.syntheticColumns) !== null && _a !== void 0 ? _a : {})) {
+        if (columns && !columns.includes(name))
+            continue;
+        const snapshotRow = Object.create(smart);
+        snapshotRow.getValue = async (col) => {
+            if (col in result)
+                return String(result[col]);
+            return smart.getValue(col);
+        };
+        result[name] = String(await def.compute(snapshotRow));
+    }
+}
+const isBatchRow = (row) => row._inBatch === true || !!row._barrier;
+// ─── Atomic snapshot ─────────────────────────────────────────────────────────
+/** Mounted row whose logical index (per resolveRowIndex) is `rowIndex`; tolerates rows detaching mid-scan. */
+async function rescanForRow(env, rowIndex) {
+    const resolveRI = env.config.strategies.resolveRowIndex;
+    const rows = await env.resolve(env.config.rowSelector, env.rootLocator).all();
+    for (const r of rows) {
+        try {
+            const rResult = await resolveRI(r);
+            if (rResult !== undefined && (0, rowResolution_1.normalizeRowIndexResult)(rResult).index === rowIndex)
+                return r;
+        }
+        catch (_a) { /* element may have detached during scan */ }
+    }
+    return null;
+}
+async function logicalIndexOf(env, loc) {
+    try {
+        const r = await env.config.strategies.resolveRowIndex(loc);
+        return r !== undefined ? (0, rowResolution_1.normalizeRowIndexResult)(r).index : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+const recycledRowHint = (inBatch, batchNote, otherwise) => inBatch ? batchNote : otherwise;
+/** Scrolls the row back into view and rescans for it for up to 500ms. */
+async function scrollBackAndRescan(env, rowIndex) {
+    var _a;
+    const { config, rootLocator, resolve } = env;
+    const scrollToRow = (_a = config.strategies.viewport) === null || _a === void 0 ? void 0 : _a.scrollToRow;
+    if (!scrollToRow)
+        return null;
+    const page = rootLocator.page();
+    await scrollToRow({ root: rootLocator, config, page, resolve }, rowIndex);
+    const deadline = Date.now() + 500;
+    let recovered = null;
+    while (!recovered && Date.now() < deadline) {
+        recovered = await rescanForRow(env, rowIndex);
+        if (!recovered)
+            await page.waitForTimeout(50);
+    }
+    return recovered;
+}
+/**
+ * Re-pin: the row locator is a positional nth-child from the iteration loop.
+ * On recycling virtualizers, elements can shift between SmartRow creation and
+ * the clone — the nth element may now show a different row's content.
+ * Verify via resolveRowIndex and rescan if drifted.
+ */
+async function recoverDriftedRow(env, rowIndex) {
+    const inBatch = isBatchRow(env.row);
+    let recovered = await rescanForRow(env, rowIndex);
+    if (!recovered && !inBatch)
+        recovered = await scrollBackAndRescan(env, rowIndex);
+    if (recovered)
+        return recovered;
+    throw new Error(`[SmartTable] toJSON({ atomic: true }): row ${rowIndex} recycled out of the DOM and could not be recovered. ` +
+        recycledRowHint(inBatch, `(During a map/forEach batch, scroll-back recovery is disabled to avoid disrupting sibling rows.)`, `Ensure a viewport.scrollToRow strategy can restore the row.`));
+}
+/** The element to clone: the row itself, re-pinned if it drifted, after `contentReady` settles. */
+async function resolveCloneTarget(env) {
+    const { config, rowIndex } = env;
+    const canRepin = !!config.strategies.resolveRowIndex && typeof rowIndex === 'number' && env.row._selfHealing !== true;
+    let cloneTarget = env.rowLocator;
+    if (canRepin && await logicalIndexOf(env, cloneTarget) !== rowIndex) {
+        cloneTarget = await recoverDriftedRow(env, rowIndex);
+    }
+    // Wait for async content renders to settle before cloning.
+    if (config.strategies.contentReady) {
+        await config.strategies.contentReady(cloneTarget, env.rootLocator.page());
+        // Revalidate: the element may have recycled during the await.
+        if (canRepin && await logicalIndexOf(env, cloneTarget) !== rowIndex) {
+            const reFound = await rescanForRow(env, rowIndex);
+            if (reFound)
+                cloneTarget = reFound;
+        }
+    }
+    return cloneTarget;
+}
+/**
+ * Clones the row in browser memory (NOT in the DOM) and extracts text + row HTML.
+ * Uses textContent (not innerText) because the clone is detached — innerText
+ * falls back to textContent on detached nodes per HTML spec, so be explicit.
+ */
+async function cloneRow(target, cellSel) {
+    const cloneHandle = await target.evaluateHandle(el => el.cloneNode(true));
+    try {
+        return await cloneHandle.evaluate((row, sel) => {
+            const cells = row.querySelectorAll(sel);
+            return {
+                rowHTML: row.outerHTML,
+                cells: [...cells].map(c => ({
+                    text: (c.textContent || '').trim(),
+                })),
+            };
+        }, cellSel);
+    }
+    finally {
+        await cloneHandle.dispose();
+    }
+}
+/**
+ * `toJSON({ atomic: true })`: snapshot the row in a single evaluate, then apply column
+ * overrides against a frozen reconstruction. Zero inter-column stagger — even in-place
+ * React re-renders can't affect it because overrides read from a detached clone.
+ */
+async function readRowAtomic(env, columns) {
+    var _a, _b;
+    const { config, map, rootLocator } = env;
+    const cellSel = config.cellSelector;
+    if (typeof cellSel !== 'string') {
+        throw new Error('[SmartTable] toJSON({ atomic: true }) requires cellSelector to be a CSS string, not a function.');
+    }
+    const page = rootLocator.page();
+    const snapshot = await cloneRow(await resolveCloneTarget(env), cellSel);
+    // Determine which columns have overrides (need lazy materialization)
+    const columnsToProcess = [...map.entries()].filter(([col]) => !columns || columns.includes(col));
+    const hasAnyOverride = columnsToProcess.some(([col]) => { var _a, _b; return !!((_b = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col]) === null || _b === void 0 ? void 0 : _b.read); });
+    // Lazily materialize the row if any override needs a Locator.
+    // Uses position:fixed off-screen (NOT display:none — that breaks innerText).
+    const snapId = `__st_snap_${Math.random().toString(36).slice(2, 10)}`;
+    const snapCell = (colIdx) => page.locator(`#${snapId}`).locator(cellSel).nth(colIdx);
+    const getCell = (colName) => {
+        const colIdx = map.get(colName);
+        if (colIdx === undefined)
+            throw new Error(`[SmartTable] getCell: column "${colName}" not found`);
+        return snapCell(colIdx);
+    };
+    if (hasAnyOverride) {
+        await page.evaluate(([html, id]) => {
+            const c = document.createElement('div');
+            c.id = id;
+            c.style.cssText = 'position:fixed;left:-99999px;top:-99999px;opacity:0;pointer-events:none';
+            // Wrap in <table><tbody> so the browser's HTML parser keeps <tr>/<td> intact.
+            c.innerHTML = `<table><tbody>${html}</tbody></table>`;
+            document.body.appendChild(c);
+        }, [snapshot.rowHTML, snapId]);
+    }
+    try {
+        const result = {};
+        for (const [col, idx] of columnsToProcess) {
+            const mapper = (_b = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col]) === null || _b === void 0 ? void 0 : _b.read;
+            if (mapper) {
+                try {
+                    result[col] = await mapper(snapCell(idx), { row: env.row, columnName: col, columnIndex: idx, getCell });
+                }
+                catch (err) {
+                    const wrapped = new Error(`[SmartTable] toJSON({ atomic: true }): column override for "${col}" failed — ${err.message}`);
+                    wrapped.cause = err;
+                    throw wrapped;
+                }
+            }
+            else if (idx < snapshot.cells.length) {
+                result[col] = snapshot.cells[idx].text;
+            }
+        }
+        await computeSyntheticColumns(env, result, columns);
+        return result;
+    }
+    finally {
+        if (hasAnyOverride)
+            await page.evaluate(id => { var _a; return (_a = document.getElementById(id)) === null || _a === void 0 ? void 0 : _a.remove(); }, snapId);
+    }
+}
+// ─── Live read ───────────────────────────────────────────────────────────────
+/**
+ * #366 / #392: on virtualized tables the row's DOM node can recycle between the
+ * per-column awaits of a live read. When a self-healing locator is in use (the row locator was
+ * rebuilt with a CSS selector, e.g. `[data-rowindex="47"]`), the locator automatically
+ * re-queries the DOM — no rescan needed. For plain-number strategies (JS-only, no
+ * selector), fall back to rescan-then-scrollToRow.
+ *
+ * Returns `resolveStableRow` (call before each column) and `current` (last known-good row).
+ */
+function createRowPinner(env) {
+    const { config, rowLocator, rowIndex } = env;
+    const resolveRI = config.strategies.resolveRowIndex;
+    const canPin = !!resolveRI && typeof rowIndex === 'number' && env.row._selfHealing !== true;
+    let lastGood = rowLocator;
+    const resolveStableRow = async () => {
+        // Self-healing locator: always re-queries the DOM by attribute — no rescan needed.
+        if (!canPin)
+            return rowLocator;
+        const result = await resolveRI(lastGood);
+        if (result !== undefined && (0, rowResolution_1.normalizeRowIndexResult)(result).index === rowIndex)
+            return lastGood; // still correct
+        // Drifted (recycled). Re-locate the row carrying the expected logical index.
+        lastGood = await relocateRecycledRow(env, rowIndex);
+        return lastGood;
+    };
+    return { resolveStableRow, current: () => lastGood };
+}
+/** Mounted row whose logical index is `rowIndex` (strict: resolveRowIndex errors propagate). */
+async function rescanStrict(env, rowIndex) {
+    const resolveRI = env.config.strategies.resolveRowIndex;
+    const rows = await env.resolve(env.config.rowSelector, env.rootLocator).all();
+    for (const r of rows) {
+        const rResult = await resolveRI(r);
+        if (rResult !== undefined && (0, rowResolution_1.normalizeRowIndexResult)(rResult).index === rowIndex)
+            return r;
+    }
+    return null;
+}
+/** Live-read recovery: rescan, then (outside batches) scrollToRow and rescan once more. */
+async function relocateRecycledRow(env, rowIndex) {
+    var _a;
+    const { config, rootLocator, resolve } = env;
+    const inBatch = isBatchRow(env.row);
+    let recovered = await rescanStrict(env, rowIndex);
+    const scrollToRow = (_a = config.strategies.viewport) === null || _a === void 0 ? void 0 : _a.scrollToRow;
+    if (!recovered && !inBatch && scrollToRow) {
+        await scrollToRow({ root: rootLocator, config, page: rootLocator.page(), resolve }, rowIndex);
+        recovered = await rescanStrict(env, rowIndex);
+    }
+    if (recovered)
+        return recovered;
+    throw new Error(`[SmartTable] toJSON: row ${rowIndex} recycled out of the DOM mid-read and could not be recovered — ` +
+        `the returned object would mix fields from different rows. ` +
+        recycledRowHint(inBatch, `(During a map/forEach batch, scroll-back recovery is disabled to avoid disrupting sibling rows; the row must stay mounted for the read.)`, `Ensure a viewport.scrollToRow can restore the row.`));
+}
+function cellIn(env, row, colName, colIdx) {
+    const { config, rootLocator } = env;
+    if (config.strategies.getCellLocator) {
+        return config.strategies.getCellLocator({
+            row, root: rootLocator, columnName: colName,
+            columnIndex: colIdx, rowIndex: env.rowIndex, page: rootLocator.page(), config,
+        });
+    }
+    return env.resolve(config.cellSelector, row).nth(colIdx);
+}
+/** undefined = unset (read as-is immediately); 0 = no wait (immediate check); >0 = wait up to N ms */
+function cellLoadingTimeoutOf(config) {
+    var _a;
+    const raw = (_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.cellLoadingTimeout;
+    return raw !== undefined && Number.isFinite(raw) && raw >= 0 ? raw : undefined;
+}
+/** Polls `check` every `intervalMs` until it returns true or `deadline` passes. */
+async function pollUntil(page, deadline, intervalMs, check, initial) {
+    let done = initial;
+    while (!done && Date.now() < deadline) {
+        await page.waitForTimeout(intervalMs);
+        done = await check();
+    }
+    return done;
+}
+/**
+ * First-paint race: the cell node can attach a tick before the loading
+ * indicator mounts. A single false-negative then reads "" and skips
+ * onCellLoadingTimeout. Only grace when the cell still looks empty.
+ */
+async function graceForLoadingIndicator(page, targetCell, isLoading, timeout) {
+    const peek = await targetCell.evaluate((el) => (el.textContent || '').trim()).catch(() => '');
+    if (peek !== '')
+        return false;
+    return pollUntil(page, Date.now() + Math.min(250, timeout), 25, isLoading, false);
+}
+/** What to do when a cell is still loading after `cellLoadingTimeout`. */
+async function onStillLoading(env, targetCell, col, timeout) {
+    var _a;
+    var _b;
+    const { config, row: smart } = env;
+    const onCellLoadingTimeout = (_b = (_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.onCellLoadingTimeout) !== null && _b !== void 0 ? _b : 'read-as-is';
+    (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — still loading after ${timeout}ms, action: ${typeof onCellLoadingTimeout === 'function' ? 'callback' : onCellLoadingTimeout}`);
+    if (typeof onCellLoadingTimeout === 'function') {
+        return { read: false, value: await onCellLoadingTimeout(targetCell, col, smart) };
+    }
+    if (onCellLoadingTimeout === 'skip')
+        return { read: false, value: '' };
+    if (onCellLoadingTimeout === 'throw') {
+        throw new Error(`[SmartTable] Cell "${col}" (row ${env.rowIndex}) did not finish loading within ${timeout}ms`);
+    }
+    // 'read-as-is': fall through to normal read
+    return { read: true };
+}
+/**
+ * Applies `loading.isCellLoading` / `cellLoadingTimeout` / `onCellLoadingTimeout` to one cell.
+ * Returns `{ read: true }` to read the cell normally, or the value to use instead.
+ */
+async function waitForCellLoaded(env, targetCell, col) {
+    var _a;
+    const { config, row: smart } = env;
+    const isCellLoading = (_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isCellLoading;
+    if (!isCellLoading)
+        return { read: true };
+    const page = env.rootLocator.page();
+    const isLoading = () => isCellLoading(targetCell, col, smart);
+    const timeout = cellLoadingTimeoutOf(config);
+    let loading = await isLoading();
+    if (!loading && timeout !== undefined && timeout > 0) {
+        loading = await graceForLoadingIndicator(page, targetCell, isLoading, timeout);
+    }
+    if (!loading || timeout === undefined)
+        return { read: true };
+    (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — waiting up to ${timeout}ms`);
+    const deadline = Date.now() + timeout;
+    const isLoaded = async () => !(await isLoading());
+    const cellResolved = await pollUntil(page, deadline, 100, isLoaded, await isLoaded()); // immediate check (handles timeout=0)
+    return cellResolved ? { read: true } : onStillLoading(env, targetCell, col, timeout);
+}
+/**
+ * Default `toJSON()`: reads each column from the live DOM, navigating to it first
+ * (keeps synchronized batches in lock-step) and re-pinning the row before each read.
+ */
+async function readRowLive(env, columns) {
+    var _a, _b, _c;
+    const { config, map, rootLocator, rowIndex } = env;
+    const result = {};
+    const page = rootLocator.page();
+    const getHeaderCell = headerCellGetter(env);
+    const pinner = createRowPinner(env);
+    // getCell for column overrides: a live cell Locator on the last-known-good row,
+    // as fresh as possible, but raw (not override-processed).
+    const getCellLive = (colName) => {
+        const colIdx = map.get(colName);
+        if (colIdx === undefined)
+            throw new Error(`[SmartTable] getCell: column "${colName}" not found`);
+        return cellIn(env, pinner.current(), colName, colIdx);
+    };
+    for (const [col, idx] of map.entries()) {
+        if (columns && !columns.includes(col))
+            continue;
+        // Re-pin to the correct logical row before reading this column (#366).
+        const stableRow = await pinner.resolveStableRow();
+        const mapper = (_b = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col]) === null || _b === void 0 ? void 0 : _b.read;
+        const cell = cellIn(env, stableRow, col, idx);
+        // Always navigate to keep Lock-Step synchronization even if the cell is
+        // already present (navigateToCell handles the barrier check-in).
+        const navigatedCell = await (0, cellNavigation_1.navigateToCell)({
+            config,
+            rootLocator,
+            page,
+            resolve: env.resolve,
+            getHeaders: (_c = env.table) === null || _c === void 0 ? void 0 : _c.getHeaders,
+            column: col,
+            index: idx,
+            rowLocator: stableRow,
+            rowIndex,
+            renderWindowPosition: env.renderWindowPosition,
+            barrier: env.row._barrier,
+            allowMissingCell: !!mapper,
+        });
+        const targetCell = navigatedCell !== null && navigatedCell !== void 0 ? navigatedCell : cell;
+        // Fires for BOTH columnOverrides.read and the default innerText path.
+        if (config.strategies.beforeCellRead) {
+            await config.strategies.beforeCellRead({
+                cell: targetCell,
+                columnName: col,
+                columnIndex: idx,
+                row: stableRow,
+                page,
+                root: rootLocator,
+                getHeaderCell,
+            });
+        }
+        const loadOutcome = await waitForCellLoaded(env, targetCell, col);
+        if (!loadOutcome.read) {
+            result[col] = loadOutcome.value;
+            continue;
+        }
+        if (mapper) {
+            result[col] = await mapper(targetCell, { row: env.row, columnName: col, columnIndex: idx, getCell: getCellLive });
+        }
+        else {
+            const text = await targetCell.innerText();
+            result[col] = (text || '').trim();
+        }
+    }
+    await computeSyntheticColumns(env, result, columns);
+    return result;
+}

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 {
@@ -52,6 +52,11 @@ export interface ScanPagesOptions {
      * Matches runMap / findRows EOF behavior. @default true
      */
     finalScanOnEof?: boolean;
+    /**
+     * Checked before each page and before each advance. When aborted, the scan throws
+     * `signal.reason` instead of returning partial results (#488).
+     */
+    signal?: AbortSignal;
 }
 export declare function scanPages(env: ScanPagesEnv, onPage: (ctx: ScanPageContext) => Promise<ScanDecision>, options: ScanPagesOptions): Promise<{
     pagesScanned: number;

package/dist/engine/scanPages.js

@@ -2,6 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanPages = scanPages;
 const debugUtils_1 = require("../utils/debugUtils");
+function throwIfAborted(env, label, signal) {
+    if (!(signal === null || signal === void 0 ? void 0 : signal.aborted))
+        return;
+    (0, debugUtils_1.logDebug)(env.config, 'info', `${label}: aborted via AbortSignal at page ${env.getCurrentPageIndex()}`);
+    throw signal.reason;
+}
 async function scanPages(env, onPage, options) {
     var _a, _b;
     const maxPages = options.maxPages;
@@ -12,14 +18,17 @@ async function scanPages(env, onPage, options) {
     let reachedEnd = false;
     (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: starting (maxPages=${maxPages}, useBulk=${useBulk}, finalScanOnEof=${finalScanOnEof})`);
     while (true) {
+        throwIfAborted(env, label, options.signal);
         if (env.waitForReady) {
             await env.waitForReady();
+            throwIfAborted(env, label, options.signal);
         }
         const decision = await onPage({
             pagesScanned,
             pageIndex: env.getCurrentPageIndex(),
             isFinalScan: reachedEnd,
         });
+        throwIfAborted(env, label, options.signal);
         if (decision === 'stop') {
             (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: onPage returned stop at page ${env.getCurrentPageIndex()}`);
             break;
@@ -27,8 +36,10 @@ async function scanPages(env, onPage, options) {
         if (pagesScanned >= maxPages || reachedEnd) {
             break;
         }
+        throwIfAborted(env, label, options.signal);
         const prevPage = env.getCurrentPageIndex();
         const didAdvance = await env.advancePage(useBulk);
+        throwIfAborted(env, label, options.signal);
         if (!didAdvance) {
             if (finalScanOnEof) {
                 (0, debugUtils_1.logDebug)(env.config, 'verbose', `${label}: pagination returned false — final scan`);

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;
@@ -195,6 +196,7 @@ async function runMap(env, callback, options = {}, label = 'map') {
             useBulk,
             label,
             finalScanOnEof: true,
+            signal: options.signal,
         });
         log(env.config, `${label}: complete — ${results.length} result(s) across ${pagesScanned} page(s)`);
     }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { PLAYWRIGHT_SMART_TABLE_VERSION } from './packageVersion';
 export { useTable } from './useTable';
-export type { TableConfig, TableResult, SmartRow, SmartCell, Selector, TableSelector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, SyntheticColumnDef, ColumnOverride, ColumnOverrideReadContext, TableStrategies, LoadingStrategy, ViewportStrategy, FilterStrategy, NavigationPrimitives, DedupeStrategy, ContentReadyStrategy, FillStrategy, PaginationStrategy, HeaderStrategy, } from './types';
+export type { TableConfig, TableResult, SmartRow, SmartCell, Selector, TableSelector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, SyntheticColumnDef, ColumnOverride, ColumnOverrideReadContext, TableStrategies, LoadingStrategy, ViewportStrategy, FilterStrategy, NavigationPrimitives, DedupeStrategy, ContentReadyStrategy, RowReadyPredicate, FillStrategy, PaginationStrategy, HeaderStrategy, } from './types';
 export { Strategies } from './strategies';
 export * as presets from './presets';
 /**