@rickcedwhat/playwright-smart-table 6.24.0 → 6.25.0-next.1e71a54

package/dist/engine/rowFinder.js

@@ -5,10 +5,10 @@ const debugUtils_1 = require("../utils/debugUtils");
 const smartRowArray_1 = require("../utils/smartRowArray");
 const elementTracker_1 = require("../utils/elementTracker");
 const sentinel_1 = require("../utils/sentinel");
-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 +111,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 +135,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;
@@ -164,25 +171,23 @@ class RowFinder {
                 const newIndices = await tracker.getUnseenIndices(rowLocators);
                 const currentRows = await rowLocators.all();
                 let added = 0;
-                const useBarrier = this.config.concurrency === 'synchronized' && newIndices.length > 1;
-                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);
+                    // These rows outlive the scan and may be consumed individually. Only
+                    // iteration engines that own every callback can attach a batch barrier.
+                    const smartRow = 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 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();
                         if (loadingOutcome === 'throw') {
                             throw new Error(`[SmartTable] Row ${allRows.length} did not finish loading within ${(_a = this.config.strategies.loading) === null || _a === void 0 ? void 0 : _a.rowLoadingTimeout}ms`);
                         }
                         continue;
                     }
                     if (hasOverrideFilters && !await this.matchesOverrideFilters(currentRows[idx], overrideFilters, map, (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false)) {
-                        barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
                         continue;
                     }
                     if (hasSyntheticFilters && !await this.matchesSyntheticFilters(currentRows[idx], syntheticFilters, map, (_d = options === null || options === void 0 ? void 0 : options.exact) !== null && _d !== void 0 ? _d : false)) {
-                        barrier === null || barrier === void 0 ? void 0 : barrier.markFinished();
                         continue;
                     }
                     allRows.push(smartRow);
@@ -195,6 +200,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 +265,7 @@ class RowFinder {
             useBulk,
             label: 'findRow',
             finalScanOnEof: true,
+            signal: options.signal,
         });
         return found;
     }

package/dist/engine/rowResolution.d.ts

@@ -29,7 +29,7 @@ export type RowLoadingOutcome = 'process' | 'skip' | 'throw';
  * 'skip'`), while `map`/`forEach`/`filter` process it as-is (`'process'`) — and map, in that
  * case, never even probes `isRowLoading`. Both are preserved exactly.
  *
- * The helper never throws and never touches the navigation barrier; it returns a decision so
- * each caller keeps its own barrier bookkeeping and error message.
+ * Timeout returns a decision so each caller keeps its own barrier bookkeeping and error
+ * message. Predicate errors propagate unchanged.
  */
 export declare function resolveRowLoading(row: SmartRow, loading: LoadingStrategy | undefined, noTimeoutAction: 'skip' | 'process', log?: (msg: string) => void): Promise<RowLoadingOutcome>;

package/dist/engine/rowResolution.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeRowIndexResult = normalizeRowIndexResult;
 exports.resolveLogicalRowIndex = resolveLogicalRowIndex;
 exports.resolveRowLoading = resolveRowLoading;
+const deadline_1 = require("../utils/deadline");
 /** Extract the numeric index from a {@link RowIndexResult}. */
 function normalizeRowIndexResult(result) {
     return typeof result === 'number' ? { index: result } : result;
@@ -36,8 +37,8 @@ async function resolveLogicalRowIndex(row, config, fallback) {
  * 'skip'`), while `map`/`forEach`/`filter` process it as-is (`'process'`) — and map, in that
  * case, never even probes `isRowLoading`. Both are preserved exactly.
  *
- * The helper never throws and never touches the navigation barrier; it returns a decision so
- * each caller keeps its own barrier bookkeeping and error message.
+ * Timeout returns a decision so each caller keeps its own barrier bookkeeping and error
+ * message. Predicate errors propagate unchanged.
  */
 async function resolveRowLoading(row, loading, noTimeoutAction, log) {
     var _a;
@@ -53,18 +54,21 @@ async function resolveRowLoading(row, loading, noTimeoutAction, log) {
     // map's fast path: with no timeout and a process-default, it never probes isRowLoading.
     if (timeout === undefined && noTimeoutAction === 'process')
         return 'process';
-    if (!(await isRowLoading(row)))
+    const deadline = Date.now() + (timeout !== null && timeout !== void 0 ? timeout : Infinity);
+    const check = () => (0, deadline_1.withinDeadline)(() => isRowLoading(row), deadline, true);
+    if (!(await check()))
         return 'process';
     // Row is loading with no timeout configured → legacy skip (findRows).
     if (timeout === undefined)
         return 'skip';
     log === null || log === void 0 ? void 0 : log(`row ${row.rowIndex} — waiting up to ${timeout}ms for row to load`);
-    const deadline = Date.now() + timeout;
-    let resolved = !(await isRowLoading(row)); // immediate check (handles timeout=0)
+    let resolved = (timeout === 0 || Date.now() < deadline) && !(await check());
     while (!resolved && Date.now() < deadline) {
         // Page accessed lazily (only while actually polling), matching the pre-refactor code.
-        await row.page().waitForTimeout(100);
-        resolved = !(await isRowLoading(row));
+        await row.page().waitForTimeout(Math.min(100, deadline - Date.now()));
+        if (Date.now() >= deadline)
+            break;
+        resolved = !(await check());
     }
     if (resolved)
         return 'process';

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,422 @@
+"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");
+const deadline_1 = require("../utils/deadline");
+/** `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;
+/** Capture a mounted position's identity once, before readiness or navigation can recycle it. */
+async function resolveSnapshotIdentity(env) {
+    if (!env.renderWindowPosition || !env.config.strategies.resolveRowIndex)
+        return env;
+    const identity = await (0, rowResolution_1.resolveLogicalRowIndex)(env.rowLocator, env.config, () => undefined);
+    // Keep the public SmartRow's mounted position unchanged; all snapshot recovery and
+    // navigation use this read's logical identity. An unknown identity is not position 0.
+    return Object.assign(Object.assign({}, env), { rowIndex: identity === null || identity === void 0 ? void 0 : identity.index, renderWindowPosition: false });
+}
+// ─── 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) {
+            cloneTarget = await recoverDriftedRow(env, rowIndex);
+        }
+    }
+    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.');
+    }
+    env = await resolveSnapshotIdentity(env);
+    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(Math.min(intervalMs, deadline - Date.now()));
+        if (Date.now() >= deadline)
+            break;
+        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, deadline) {
+    const peek = await (0, deadline_1.withinDeadline)(() => targetCell.evaluate((el) => (el.textContent || '').trim()).catch(() => ''), deadline, null);
+    if (peek === null)
+        return true; // Deadline expired: apply the cell loading timeout policy.
+    if (peek !== '')
+        return false;
+    return pollUntil(page, Math.min(Date.now() + 250, deadline), 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 timeout = cellLoadingTimeoutOf(config);
+    const deadline = Date.now() + (timeout !== null && timeout !== void 0 ? timeout : Infinity);
+    const isLoading = () => (0, deadline_1.withinDeadline)(() => isCellLoading(targetCell, col, smart), deadline, true);
+    let loading = await isLoading();
+    if (!loading && timeout !== undefined && timeout > 0) {
+        loading = await graceForLoadingIndicator(page, targetCell, isLoading, deadline);
+    }
+    if (!loading || timeout === undefined)
+        return { read: true };
+    (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — waiting up to ${timeout}ms`);
+    const isLoaded = async () => !(await isLoading());
+    const initial = (timeout === 0 || Date.now() < deadline) && await isLoaded();
+    const cellResolved = await pollUntil(page, deadline, 100, isLoaded, initial);
+    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;
+    env = await resolveSnapshotIdentity(env);
+    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;