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

package/dist/smartRow.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const rowResolution_1 = require("./engine/rowResolution");
+const cellNavigation_1 = require("./engine/cellNavigation");
+const rowSnapshot_1 = require("./engine/rowSnapshot");
 const fill_1 = require("./strategies/fill");
 const stringUtils_1 = require("./utils/stringUtils");
 const debugUtils_1 = require("./utils/debugUtils");
@@ -8,309 +10,6 @@ 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).
- * Returns the target cell locator after navigation.
- */
-const _navigateToCell = async (params) => {
-    var _a;
-    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, barrier, allowMissingCell } = params;
-    // getRowByIndex supplies a position in the mounted row set. Resolve it while the
-    // selected row is still mounted, before horizontal scrolling can evict it.
-    const rowIndex = params.renderWindowPosition && config.strategies.viewport && config.strategies.resolveRowIndex
-        ? (_a = (await (0, rowResolution_1.resolveLogicalRowIndex)(rowLocator, config, () => undefined))) === null || _a === void 0 ? void 0 : _a.index
-        : params.rowIndex;
-    const rowLabel = typeof rowIndex === 'number' ? `row ${rowIndex}` : 'row ?';
-    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: resolving column "${column}" (colIndex ${index}), ${rowLabel}`);
-    // Get active cell if strategy is available
-    let activeCell = null;
-    if (config.strategies.getActiveCell) {
-        activeCell = await config.strategies.getActiveCell({
-            config,
-            root: rootLocator,
-            page,
-            resolve
-        });
-        // Optimization: Check if we are ALREADY at the target cell
-        if (activeCell && activeCell.rowIndex === rowIndex && activeCell.columnIndex === index) {
-            (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: Already at target cell {row: ${rowIndex}, col: ${index}}`);
-            // Still participate in the barrier (no-op) so peers are not left waiting.
-            if (barrier)
-                await barrier.sync(index);
-            return activeCell.locator;
-        }
-    }
-    const context = { config, root: rootLocator, page, resolve, getHeaders };
-    // Shared helper: is the target cell currently in the DOM?
-    const targetReached = async () => {
-        if (config.strategies.getActiveCell) {
-            const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-            if (ac && ac.rowIndex === rowIndex && ac.columnIndex === index)
-                return true;
-        }
-        // Locator presence: virtualized grids (e.g. Glide) often attach the target `td` after scroll
-        // while focus id lags; do not require getActiveCell to match for this to count as reached.
-        const cell = config.strategies.getCellLocator
-            ? config.strategies.getCellLocator({ row: rowLocator, root: rootLocator, columnName: column, columnIndex: index, rowIndex, page, config })
-            : resolve(config.cellSelector, rowLocator).nth(index);
-        return (await cell.count() > 0);
-    };
-    const getCellLocator = () => config.strategies.getCellLocator
-        ? config.strategies.getCellLocator({ row: rowLocator, root: rootLocator, columnName: column, columnIndex: index, rowIndex, page, config })
-        : resolve(config.cellSelector, rowLocator).nth(index);
-    // Viewport-oracle phase: direct positioning for 2D virtualized tables.
-    // Runs before navigation primitives; falls through to them if cell still not accessible.
-    const viewport = config.strategies.viewport;
-    if (viewport && typeof rowIndex === 'number') {
-        // Fast path via range oracle: re-used below to avoid a second DOM round-trip.
-        // Rows do NOT sync at the barrier here — only scroll boundaries need coordination.
-        let knownColRange = null;
-        if (viewport.getVisibleColumnRange) {
-            knownColRange = await viewport.getVisibleColumnRange(context);
-            if (knownColRange && index >= knownColRange.first && index <= knownColRange.last) {
-                const rowRange = viewport.getVisibleRowRange
-                    ? await viewport.getVisibleRowRange(context)
-                    : null;
-                const rowVisible = !rowRange || (rowIndex >= rowRange.first && rowIndex <= rowRange.last);
-                let cellAttached = rowVisible && await targetReached();
-                if (rowVisible && !cellAttached) {
-                    try {
-                        await getCellLocator().waitFor({ state: 'attached', timeout: 500 });
-                        cellAttached = true;
-                    }
-                    catch (error) {
-                        if ((error === null || error === void 0 ? void 0 : error.name) !== 'TimeoutError')
-                            throw error;
-                    }
-                }
-                if (cellAttached) {
-                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} in visible range [${knownColRange.first}-${knownColRange.last}], reading directly`);
-                    // Check in to the barrier without a moveAction — peers that need the scroll
-                    // still supply their own action and will trigger it when all rows arrive.
-                    if (barrier)
-                        await barrier.sync(index);
-                    return getCellLocator();
-                }
-            }
-        }
-        else if (await targetReached()) {
-            // No range oracle — fall back to DOM count() check.
-            if (barrier)
-                await barrier.sync(index);
-            return getCellLocator();
-        }
-        // Column is out of view. Scroll to bring it in.
-        // In synchronized mode, the last row to arrive triggers the scroll once for all rows.
-        const scrollIntoViewport = async () => {
-            // Always scroll — scrollToColumn is idempotent (bounds-checks before acting).
-            // The trigger row may already have the cell via overscan, but other rows in the
-            // batch might not; skipping the scroll here would silently starve them.
-            (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} out of view, scrolling`);
-            if (viewport.scrollToColumn) {
-                await viewport.scrollToColumn(context, index);
-            }
-        };
-        if (barrier) {
-            await barrier.sync(index, scrollIntoViewport);
-        }
-        else {
-            await scrollIntoViewport();
-        }
-        // Per-row 2D recovery: horizontal scroll may evict rows from the vertical viewport
-        // (scrollbar layout shift) or rows may simply be outside the virtual row window.
-        // Recovery is serialized via the barrier's mutex so concurrent rows don't race on
-        // scrollTop — adjacent rows often appear in view for free after the previous recovery.
-        // scrollToRow must only adjust scrollTop (not scrollLeft) to preserve the column
-        // position established by scrollToColumn.
-        if (!await targetReached() && viewport.scrollToRow && typeof rowIndex === 'number') {
-            const scrollToRow = viewport.scrollToRow;
-            const recover = async () => {
-                if (!await targetReached()) {
-                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: row ${rowIndex} evicted by col scroll, recovering`);
-                    await scrollToRow(context, rowIndex);
-                }
-            };
-            if (barrier) {
-                await barrier.runExclusiveRecovery(recover);
-            }
-            else {
-                await recover();
-            }
-        }
-        if (await targetReached()) {
-            return getCellLocator();
-        }
-        // Cell still not accessible — fall through to navigation primitives if configured.
-        if (!config.strategies.navigation) {
-            if (allowMissingCell)
-                return getCellLocator();
-            const colRange = viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
-            const rowRange = viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
-            let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex}.\n`;
-            if (colRange) {
-                errMsg += `  Visible column range: [${colRange.first}–${colRange.last}]. Column is out of view and no navigation fallback is configured.\n`;
-            }
-            else {
-                errMsg += `  Column is out of view and no navigation fallback is configured.\n`;
-            }
-            if (rowRange && rowIndex !== undefined) {
-                const inView = rowIndex >= rowRange.first && rowIndex <= rowRange.last;
-                errMsg += `  Visible row range: [${rowRange.first}–${rowRange.last}]. ${inView ? 'Row is in view.' : 'Row is out of view.'}\n`;
-            }
-            errMsg += `  → Add a \`strategies.navigation\` or \`strategies.viewport.scrollToColumn\` to handle off-screen columns.`;
-            throw new Error(errMsg);
-        }
-    }
-    // Use navigation primitives if available
-    if (config.strategies.navigation) {
-        const nav = config.strategies.navigation;
-        if (await targetReached()) {
-            // Already there. If we have a barrier, check-in to stay in lock-step.
-            if (barrier)
-                await barrier.sync(index);
-            return getCellLocator();
-        }
-        if (typeof rowIndex !== 'number') {
-            if (allowMissingCell)
-                return getCellLocator();
-            throw new Error('Row index is required for navigation');
-        }
-        // If getActiveCell is present but returns null (no focus), and cell is in DOM,
-        // try to focus it once before entering navigation loop.
-        if (config.strategies.getActiveCell) {
-            const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-            if (!ac) {
-                const cell = resolve(config.cellSelector, rowLocator).nth(index);
-                if (await cell.count() > 0) {
-                    (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: cell "${column}" found but not focused; focusing.`);
-                    await cell.focus();
-                    // Re-check target
-                    if (await targetReached()) {
-                        if (barrier)
-                            await barrier.sync(index);
-                        return cell;
-                    }
-                }
-            }
-        }
-        const navigateUntilReached = async () => {
-            let currRow = 0;
-            let currCol = 0;
-            if (config.strategies.getActiveCell) {
-                const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-                if (ac) {
-                    currRow = ac.rowIndex;
-                    currCol = ac.columnIndex;
-                }
-            }
-            const rDiff = rowIndex - currRow;
-            // Navigate vertically (tight loop)
-            for (let i = 0; i < Math.abs(rDiff); i++) {
-                if (rDiff > 0 && nav.goDown)
-                    await nav.goDown(context);
-                else if (rDiff < 0 && nav.goUp)
-                    await nav.goUp(context);
-            }
-            if (config.strategies.getActiveCell) {
-                const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-                if (ac) {
-                    currRow = ac.rowIndex;
-                    currCol = ac.columnIndex;
-                }
-            }
-            // Column-0 snap is owned by the navigation primitive (scrollLeft=0, Home, etc.).
-            // Core must not special-case canvas/Home — that was pre-viewport Glide glue.
-            if (index === 0 && nav.snapFirstColumnIntoView) {
-                (0, debugUtils_1.logDebug)(config, 'verbose', '_navigateToCell: snapFirstColumnIntoView for column index 0');
-                await nav.snapFirstColumnIntoView(context);
-                if (config.strategies.getActiveCell) {
-                    const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-                    if (ac) {
-                        currRow = ac.rowIndex;
-                        currCol = ac.columnIndex;
-                    }
-                }
-            }
-            let cDiff = index - currCol;
-            if (Math.abs(cDiff) > 12 && nav.seekColumnIndex) {
-                (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: seekColumnIndex approx for column ${index}`);
-                await nav.seekColumnIndex(context, index);
-                if (config.strategies.getActiveCell) {
-                    const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-                    if (ac) {
-                        currRow = ac.rowIndex;
-                        currCol = ac.columnIndex;
-                    }
-                }
-                cDiff = index - currCol;
-            }
-            for (let i = 0; i < Math.abs(cDiff); i++) {
-                if (cDiff > 0 && nav.goRight)
-                    await nav.goRight(context);
-                else if (cDiff < 0 && nav.goLeft)
-                    await nav.goLeft(context);
-            }
-            const horizontalSteps = Math.abs(cDiff);
-            if (horizontalSteps > 0) {
-                const computed = Math.min(2500, 60 + horizontalSteps * 12);
-                const settleMs = (Number.isFinite(nav.settleMs) && nav.settleMs >= 0) ? nav.settleMs : computed;
-                await page.waitForTimeout(settleMs);
-            }
-            // After horizontal steps, poll until getActiveCell / DOM presence confirms the target
-            // (a11y trees and virtual mounts often lag the scroll). Tune via navigation.maxWaitMs.
-            const pollIntervalMs = 10;
-            const computedMax = Math.min(6000, 250 + horizontalSteps * 25);
-            const maxWaitMs = (Number.isFinite(nav.maxWaitMs) && nav.maxWaitMs >= 0) ? nav.maxWaitMs : computedMax;
-            const start = Date.now();
-            while (Date.now() - start < maxWaitMs) {
-                if (config.strategies.getActiveCell) {
-                    const ac = await config.strategies.getActiveCell({ config, root: rootLocator, page, resolve });
-                    if (ac && ac.rowIndex === rowIndex && ac.columnIndex === index) {
-                        return ac.locator;
-                    }
-                }
-                if (await targetReached()) {
-                    break;
-                }
-                await page.waitForTimeout(pollIntervalMs);
-            }
-        };
-        // Not there, perform (coordinated) navigation
-        let navResult;
-        if (barrier) {
-            navResult = await barrier.sync(index, navigateUntilReached);
-        }
-        else {
-            navResult = await navigateUntilReached();
-        }
-        // navigateUntilReached may return a Locator it found mid-navigation
-        if (navResult && typeof navResult.count === 'function') {
-            const loc = navResult;
-            if (await loc.count() > 0)
-                return loc;
-        }
-        // Return final locator if reached
-        const finalCell = getCellLocator();
-        if (await finalCell.count() > 0)
-            return finalCell;
-        if (allowMissingCell)
-            return finalCell;
-        const colRange = viewport && viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
-        const rowRange = viewport && viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
-        let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex} after exhausting navigation strategies. Ensure navigation primitives are correctly implemented.\n`;
-        if (colRange) {
-            errMsg += `  Visible column range: [${colRange.first}–${colRange.last}].\n`;
-        }
-        if (rowRange && rowIndex !== undefined) {
-            errMsg += `  Visible row range: [${rowRange.first}–${rowRange.last}].\n`;
-        }
-        throw new Error(errMsg);
-    }
-    // No horizontal strategies configured; assume table is 1D or fully rendered,
-    // and let standard Playwright auto-waiting handle any lazy-loading delays.
-    return getCellLocator();
-};
 /**
  * Factory to create a SmartRow by extending a Playwright Locator.
  * We avoid Class/Proxy to ensure full compatibility with Playwright's expect(locator) matchers.
@@ -356,7 +55,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         const smartCell = (0, locatorDescription_1.describeLocator)(baseLocator, cellDescription, config);
         smartCell.bringIntoView = async () => {
             const page = rootLocator.page();
-            const navigatedCell = await _navigateToCell({
+            const navigatedCell = await (0, cellNavigation_1.navigateToCell)({
                 config,
                 rootLocator,
                 page,
@@ -371,14 +70,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             });
             // Run beforeCellRead hook (same as toJSON does after navigation).
             if (config.strategies.beforeCellRead) {
-                const getHeaderCell = (table === null || table === void 0 ? void 0 : table.getHeaderCell)
-                    ? table.getHeaderCell.bind(table)
-                    : async (colNameArg) => {
-                        const i = map.get(colNameArg);
-                        if (i === undefined)
-                            throw new Error(`Column "${colNameArg}" not found`);
-                        return resolve(config.headerSelector, rootLocator).nth(i);
-                    };
+                const getHeaderCell = (0, rowSnapshot_1.headerCellGetter)({ config, rootLocator, resolve, map, table });
                 await config.strategies.beforeCellRead({
                     cell: navigatedCell !== null && navigatedCell !== void 0 ? navigatedCell : baseLocator,
                     columnName: colName,
@@ -419,7 +111,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         const page = rootLocator.page();
         // Same nav pipeline as toJSON / getCell().bringIntoView() (#430) so virtualized
         // off-screen columns don't return empty/stale text.
-        const cell = await _navigateToCell({
+        const cell = await (0, cellNavigation_1.navigateToCell)({
             config,
             rootLocator,
             page,
@@ -444,385 +136,13 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         }
         return (await cell.innerText()).trim();
     };
+    const snapshotEnv = {
+        config, rootLocator, resolve, map, row: smart, rowLocator, rowIndex, table, renderWindowPosition,
+    };
     smart.toJSON = async (options) => {
-        var _a, _b, _c, _d, _e, _f;
-        var _g, _h, _j;
-        // Atomic mode: 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.
-        if (options === null || options === void 0 ? void 0 : options.atomic) {
-            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();
-            // Re-pin: the row locator is a positional nth-child from the iteration loop.
-            // On recycling virtualizers, elements can shift between SmartRow creation and
-            // this clone — the nth element may now show a different row's content.
-            // Verify via resolveRowIndex and rescan if drifted.
-            let cloneTarget = rowLocator;
-            const resolveRI = config.strategies.resolveRowIndex;
-            const isSelfHealing = smart._selfHealing === true;
-            const rescanForRow = resolveRI && typeof rowIndex === 'number' && !isSelfHealing
-                ? async () => {
-                    const rows = await resolve(config.rowSelector, 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;
-                }
-                : null;
-            if (rescanForRow) {
-                let drifted = false;
-                try {
-                    const curResult = await resolveRI(rowLocator);
-                    const curIndex = curResult !== undefined
-                        ? (0, rowResolution_1.normalizeRowIndexResult)(curResult).index
-                        : undefined;
-                    drifted = curIndex !== rowIndex;
-                }
-                catch (_k) {
-                    drifted = true;
-                }
-                if (drifted) {
-                    const inBatch = smart._inBatch === true || !!smart._barrier;
-                    let recovered = await rescanForRow();
-                    if (!recovered && !inBatch && ((_a = config.strategies.viewport) === null || _a === void 0 ? void 0 : _a.scrollToRow)) {
-                        await config.strategies.viewport.scrollToRow({ root: rootLocator, config, page, resolve }, rowIndex);
-                        const deadline = Date.now() + 500;
-                        while (!recovered && Date.now() < deadline) {
-                            recovered = await rescanForRow();
-                            if (!recovered)
-                                await page.waitForTimeout(50);
-                        }
-                    }
-                    if (!recovered) {
-                        throw new Error(`[SmartTable] toJSON({ atomic: true }): row ${rowIndex} recycled out of the DOM and could not be recovered. ` +
-                            (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.`));
-                    }
-                    cloneTarget = recovered;
-                }
-            }
-            // Wait for async content renders to settle before cloning.
-            if (config.strategies.contentReady) {
-                await config.strategies.contentReady(cloneTarget, page);
-                // Revalidate: the element may have recycled during the await.
-                if (rescanForRow) {
-                    let postIdx;
-                    try {
-                        const r = await resolveRI(cloneTarget);
-                        postIdx = r !== undefined ? (0, rowResolution_1.normalizeRowIndexResult)(r).index : undefined;
-                    }
-                    catch (_l) {
-                        postIdx = undefined;
-                    }
-                    if (postIdx !== rowIndex) {
-                        const reFound = await rescanForRow();
-                        if (reFound)
-                            cloneTarget = reFound;
-                    }
-                }
-            }
-            // Step 1: clone row in browser memory (NOT in the DOM), extract 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.
-            const cloneHandle = await cloneTarget.evaluateHandle(el => el.cloneNode(true));
-            let snapshot;
-            try {
-                snapshot = 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();
-            }
-            // Determine which columns have overrides (need lazy materialization)
-            const columnsToProcess = [...map.entries()]
-                .filter(([col]) => !(options === null || options === void 0 ? void 0 : options.columns) || options.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); });
-            // Step 2: 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)}`;
-            let materialized = false;
-            const materializeRow = async () => {
-                if (materialized)
-                    return;
-                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]);
-                materialized = true;
-            };
-            const cleanupSnapshot = async () => {
-                if (!materialized)
-                    return;
-                await page.evaluate(id => { var _a; return (_a = document.getElementById(id)) === null || _a === void 0 ? void 0 : _a.remove(); }, snapId);
-            };
-            // Step 3: build getCell helper — returns Locator to cell in materialized row
-            const getCell = (colName) => {
-                const colIdx = map.get(colName);
-                if (colIdx === undefined)
-                    throw new Error(`[SmartTable] getCell: column "${colName}" not found`);
-                return page.locator(`#${snapId}`).locator(cellSel).nth(colIdx);
-            };
-            try {
-                if (hasAnyOverride)
-                    await materializeRow();
-                const result = {};
-                for (const [col, idx] of columnsToProcess) {
-                    const columnOverride = (_b = config.columnOverrides) === null || _b === void 0 ? void 0 : _b[col];
-                    const mapper = columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read;
-                    if (mapper) {
-                        const cell = page.locator(`#${snapId}`).locator(cellSel).nth(idx);
-                        try {
-                            result[col] = await mapper(cell, { row: smart, 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;
-                    }
-                }
-                for (const [name, def] of Object.entries((_g = config.syntheticColumns) !== null && _g !== void 0 ? _g : {})) {
-                    if ((options === null || options === void 0 ? void 0 : options.columns) && !options.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));
-                }
-                return result;
-            }
-            finally {
-                await cleanupSnapshot();
-            }
-        }
-        const result = {};
-        const page = rootLocator.page();
-        // Build a getHeaderCell helper for the beforeCellRead context.
-        // Uses the table reference if available, otherwise falls back to index-based lookup.
-        const getHeaderCell = (table === null || table === void 0 ? void 0 : table.getHeaderCell)
-            ? table.getHeaderCell.bind(table)
-            : async (colName) => {
-                const idx = map.get(colName);
-                if (idx === undefined)
-                    throw new Error(`Column "${colName}" not found`);
-                return resolve(config.headerSelector, rootLocator).nth(idx);
-            };
-        // #366 / #392: on virtualized tables the row's DOM node can recycle between the
-        // per-column awaits below. 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 the original rescan-then-scrollToRow approach.
-        const resolveRI = config.strategies.resolveRowIndex;
-        const canPin = !!resolveRI && typeof rowIndex === 'number';
-        const isSelfHealing = smart._selfHealing === true;
-        const stableCtx = { root: rootLocator, config, page, resolve };
-        const inBatch = smart._inBatch === true || !!smart._barrier;
-        let lastGood = rowLocator;
-        const resolveStableRow = async () => {
-            var _a;
-            // Self-healing locator: always re-queries the DOM by attribute — no rescan needed.
-            if (isSelfHealing)
-                return rowLocator;
-            if (!canPin)
-                return rowLocator;
-            const result = await resolveRI(lastGood);
-            const resolvedIndex = result !== undefined ? (0, rowResolution_1.normalizeRowIndexResult)(result).index : undefined;
-            if (resolvedIndex === rowIndex)
-                return lastGood; // still correct
-            // Drifted (recycled). Re-locate the row carrying the expected logical index.
-            const rescan = async () => {
-                const rows = await resolve(config.rowSelector, 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;
-            };
-            let recovered = await rescan();
-            if (!recovered && !inBatch && ((_a = config.strategies.viewport) === null || _a === void 0 ? void 0 : _a.scrollToRow)) {
-                await config.strategies.viewport.scrollToRow(stableCtx, rowIndex);
-                recovered = await rescan();
-            }
-            if (!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. ` +
-                    (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.`));
-            }
-            lastGood = recovered;
-            return recovered;
-        };
-        // getCell for non-atomic mode: returns a live cell Locator via the column map.
-        // Uses the last-known-good row from the re-pin so it's as fresh as possible,
-        // but returns raw cell Locators, not override-processed values.
-        const getCellLive = (colName) => {
-            const colIdx = map.get(colName);
-            if (colIdx === undefined)
-                throw new Error(`[SmartTable] getCell: column "${colName}" not found`);
-            const row = lastGood;
-            if (config.strategies.getCellLocator) {
-                return config.strategies.getCellLocator({
-                    row, root: rootLocator, columnName: colName,
-                    columnIndex: colIdx, rowIndex, page, config,
-                });
-            }
-            return resolve(config.cellSelector, row).nth(colIdx);
-        };
-        for (const [col, idx] of map.entries()) {
-            if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(col)) {
-                continue;
-            }
-            // Re-pin to the correct logical row before reading this column (#366).
-            const stableRow = await resolveStableRow();
-            // Check if we have a column override for this column
-            const columnOverride = (_c = config.columnOverrides) === null || _c === void 0 ? void 0 : _c[col];
-            const mapper = columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read;
-            // --- Navigation Logic Start ---
-            const cell = config.strategies.getCellLocator
-                ? config.strategies.getCellLocator({
-                    row: stableRow,
-                    root: rootLocator,
-                    columnName: col,
-                    columnIndex: idx,
-                    rowIndex: rowIndex,
-                    page: page,
-                    config
-                })
-                : resolve(config.cellSelector, stableRow).nth(idx);
-            let targetCell = cell;
-            // Always call _navigateToCell to ensure Lock-Step synchronization
-            // even if the cell is already present (it handles check-in inside)
-            const navigatedCell = await _navigateToCell({
-                config,
-                rootLocator,
-                page,
-                resolve,
-                getHeaders: table === null || table === void 0 ? void 0 : table.getHeaders,
-                column: col,
-                index: idx,
-                rowLocator: stableRow,
-                rowIndex,
-                renderWindowPosition,
-                barrier: smart._barrier,
-                allowMissingCell: !!mapper,
-            });
-            if (navigatedCell) {
-                targetCell = navigatedCell;
-            }
-            // --- Navigation Logic End ---
-            // Call beforeCellRead hook if configured.
-            // 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,
-                });
-            }
-            // Cell loading wait (if configured)
-            const isCellLoading = (_d = config.strategies.loading) === null || _d === void 0 ? void 0 : _d.isCellLoading;
-            const rawCellTimeout = (_e = config.strategies.loading) === null || _e === void 0 ? void 0 : _e.cellLoadingTimeout;
-            // undefined = unset (read as-is immediately); 0 = no wait (immediate check); >0 = wait up to N ms
-            const cellLoadingTimeout = rawCellTimeout !== undefined && Number.isFinite(rawCellTimeout) && rawCellTimeout >= 0
-                ? rawCellTimeout
-                : undefined;
-            const onCellLoadingTimeout = (_h = (_f = config.strategies.loading) === null || _f === void 0 ? void 0 : _f.onCellLoadingTimeout) !== null && _h !== void 0 ? _h : 'read-as-is';
-            if (isCellLoading) {
-                let loading = await isCellLoading(targetCell, col, smart);
-                // 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.
-                if (!loading && cellLoadingTimeout !== undefined && cellLoadingTimeout > 0) {
-                    const peek = await targetCell.evaluate((el) => (el.textContent || '').trim()).catch(() => '');
-                    if (peek === '') {
-                        const graceDeadline = Date.now() + Math.min(250, cellLoadingTimeout);
-                        while (!loading && Date.now() < graceDeadline) {
-                            await page.waitForTimeout(25);
-                            loading = await isCellLoading(targetCell, col, smart);
-                        }
-                    }
-                }
-                if (loading && cellLoadingTimeout !== undefined) {
-                    (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — waiting up to ${cellLoadingTimeout}ms`);
-                    const deadline = Date.now() + cellLoadingTimeout;
-                    let cellResolved = !(await isCellLoading(targetCell, col, smart)); // immediate check (handles timeout=0)
-                    while (!cellResolved && Date.now() < deadline) {
-                        await page.waitForTimeout(100);
-                        cellResolved = !(await isCellLoading(targetCell, col, smart));
-                    }
-                    if (!cellResolved) {
-                        (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — still loading after ${cellLoadingTimeout}ms, action: ${typeof onCellLoadingTimeout === 'function' ? 'callback' : onCellLoadingTimeout}`);
-                        if (typeof onCellLoadingTimeout === 'function') {
-                            result[col] = await onCellLoadingTimeout(targetCell, col, smart);
-                            continue;
-                        }
-                        if (onCellLoadingTimeout === 'skip') {
-                            result[col] = '';
-                            continue;
-                        }
-                        if (onCellLoadingTimeout === 'throw') {
-                            throw new Error(`[SmartTable] Cell "${col}" (row ${rowIndex}) did not finish loading within ${cellLoadingTimeout}ms`);
-                        }
-                        // 'read-as-is': fall through to normal read
-                    }
-                }
-                // If no timeout or resolved: fall through to normal read
-            }
-            if (mapper) {
-                // Apply mapper
-                const mappedValue = await mapper(targetCell, { row: smart, columnName: col, columnIndex: idx, getCell: getCellLive });
-                result[col] = mappedValue;
-            }
-            else {
-                // Default string extraction
-                const text = await targetCell.innerText();
-                result[col] = (text || '').trim();
-            }
-        }
-        for (const [name, def] of Object.entries((_j = config.syntheticColumns) !== null && _j !== void 0 ? _j : {})) {
-            if ((options === null || options === void 0 ? void 0 : options.columns) && !options.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));
-        }
-        return result;
+        return (options === null || options === void 0 ? void 0 : options.atomic)
+            ? (0, rowSnapshot_1.readRowAtomic)(snapshotEnv, options.columns)
+            : (0, rowSnapshot_1.readRowLive)(snapshotEnv, options === null || options === void 0 ? void 0 : options.columns);
     };
     smart.smartFill = async (data, fillOptions) => {
         var _a, _b;
@@ -838,7 +158,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             if (colIdx === undefined) {
                 throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, [...map.keys(), ...Object.keys((_c = config.syntheticColumns) !== null && _c !== void 0 ? _c : {})]));
             }
-            await _navigateToCell({
+            await (0, cellNavigation_1.navigateToCell)({
                 config,
                 rootLocator,
                 page: rootLocator.page(),