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

package/dist/engine/cellNavigation.d.ts

@@ -0,0 +1,24 @@
+import type { Locator, Page } from '@playwright/test';
+import type { FinalTableConfig } from '../types';
+import type { NavigationBarrier } from '../utils/navigationBarrier';
+export interface NavigateToCellParams {
+    config: FinalTableConfig<any>;
+    rootLocator: Locator;
+    page: Page;
+    resolve: (item: any, parent: Locator | Page) => Locator;
+    getHeaders?: () => Promise<string[]>;
+    column: string;
+    index: number;
+    rowLocator: Locator;
+    rowIndex?: number;
+    renderWindowPosition?: boolean;
+    barrier?: NavigationBarrier;
+    allowMissingCell?: boolean;
+}
+/**
+ * Navigates to a cell with active cell optimization.
+ * Uses `strategies.viewport` first (2D virtualized tables), then `strategies.navigation`
+ * primitives (goUp/goDown/goLeft/goRight, optional snap/seek/goHome).
+ * Returns the target cell locator after navigation.
+ */
+export declare const navigateToCell: (params: NavigateToCellParams) => Promise<Locator>;

package/dist/engine/cellNavigation.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.navigateToCell = void 0;
+const rowResolution_1 = require("./rowResolution");
+const debugUtils_1 = require("../utils/debugUtils");
+const log = (config, msg) => (0, debugUtils_1.logDebug)(config, 'verbose', msg);
+/**
+ * Navigates to a cell with active cell optimization.
+ * Uses `strategies.viewport` first (2D virtualized tables), then `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 ?';
+    log(config, `_navigateToCell: resolving column "${column}" (colIndex ${index}), ${rowLabel}`);
+    const getActiveCell = config.strategies.getActiveCell;
+    const readActiveCell = async () => getActiveCell ? getActiveCell({ config, root: rootLocator, page, resolve }) : null;
+    const isActiveTarget = (ac) => !!ac && ac.rowIndex === rowIndex && ac.columnIndex === index;
+    // Optimization: Check if we are ALREADY at the target cell
+    if (getActiveCell) {
+        const activeCell = await readActiveCell();
+        if (activeCell && isActiveTarget(activeCell)) {
+            log(config, `_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 getCellLocator = () => config.strategies.getCellLocator
+        ? config.strategies.getCellLocator({ row: rowLocator, root: rootLocator, columnName: column, columnIndex: index, rowIndex, page, config })
+        : resolve(config.cellSelector, rowLocator).nth(index);
+    const nav = {
+        config, page, column, index, rowLocator, rowIndex, barrier, allowMissingCell, resolve,
+        context: { config, root: rootLocator, page, resolve, getHeaders },
+        readActiveCell,
+        isActiveTarget,
+        // 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.
+        targetReached: async () => isActiveTarget(await readActiveCell()) || (await getCellLocator().count() > 0),
+        getCellLocator,
+    };
+    // 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') {
+        const viaViewport = await navigateViaViewport(nav, viewport, rowIndex);
+        if (viaViewport)
+            return viaViewport;
+    }
+    if (config.strategies.navigation) {
+        return navigateViaPrimitives(nav, config.strategies.navigation);
+    }
+    // No horizontal strategies configured; assume table is 1D or fully rendered,
+    // and let standard Playwright auto-waiting handle any lazy-loading delays.
+    return getCellLocator();
+};
+exports.navigateToCell = navigateToCell;
+/** Checks in to the barrier without a move action so peers aren't left waiting. */
+async function checkIn(nav) {
+    if (nav.barrier)
+        await nav.barrier.sync(nav.index);
+}
+/** Runs `action` once for the whole batch when a barrier is present, otherwise directly. */
+async function coordinated(nav, action) {
+    return nav.barrier ? nav.barrier.sync(nav.index, action) : action();
+}
+const inRange = (value, range) => value >= range.first && value <= range.last;
+/** True when the row is in the visible row range and the target cell is (or soon becomes) attached. */
+async function isCellAttachedInView(nav, viewport, rowIndex) {
+    const rowRange = viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(nav.context) : null;
+    if (rowRange && !inRange(rowIndex, rowRange))
+        return false;
+    if (await nav.targetReached())
+        return true;
+    try {
+        await nav.getCellLocator().waitFor({ state: 'attached', timeout: 500 });
+        return true;
+    }
+    catch (error) {
+        if ((error === null || error === void 0 ? void 0 : error.name) !== 'TimeoutError')
+            throw error;
+        return false;
+    }
+}
+/**
+ * Fast path: is the cell already readable without scrolling? Uses the column range oracle
+ * when available, else DOM presence. Rows do NOT sync at the barrier with a move action
+ * here — only scroll boundaries need coordination.
+ */
+async function readIfInView(nav, viewport, rowIndex) {
+    const { config, context, index } = nav;
+    if (!viewport.getVisibleColumnRange) {
+        // No range oracle — fall back to DOM count() check.
+        if (!await nav.targetReached())
+            return null;
+        await checkIn(nav);
+        return nav.getCellLocator();
+    }
+    const knownColRange = await viewport.getVisibleColumnRange(context);
+    if (!knownColRange || !inRange(index, knownColRange))
+        return null;
+    if (!await isCellAttachedInView(nav, viewport, rowIndex))
+        return null;
+    log(config, `_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.
+    await checkIn(nav);
+    return nav.getCellLocator();
+}
+/**
+ * Viewport phase. Returns the cell locator, or null to fall through to navigation primitives
+ * (only when `strategies.navigation` is configured; otherwise throws on a miss).
+ */
+async function navigateViaViewport(nav, viewport, rowIndex) {
+    const { config, context, index } = nav;
+    const inView = await readIfInView(nav, viewport, rowIndex);
+    if (inView)
+        return inView;
+    // 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.
+    await coordinated(nav, 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.
+        log(config, `_navigateToCell: col ${index} out of view, scrolling`);
+        if (viewport.scrollToColumn) {
+            await viewport.scrollToColumn(context, index);
+        }
+    });
+    await recoverEvictedRow(nav, viewport, rowIndex);
+    if (await nav.targetReached()) {
+        return nav.getCellLocator();
+    }
+    // Cell still not accessible — fall through to navigation primitives if configured.
+    if (config.strategies.navigation)
+        return null;
+    if (nav.allowMissingCell)
+        return nav.getCellLocator();
+    throw new Error(await describeViewportMiss(nav, viewport, rowIndex));
+}
+/**
+ * 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.
+ */
+async function recoverEvictedRow(nav, viewport, rowIndex) {
+    if (await nav.targetReached())
+        return;
+    const scrollToRow = viewport.scrollToRow;
+    if (!scrollToRow)
+        return;
+    const recover = async () => {
+        if (!await nav.targetReached()) {
+            log(nav.config, `_navigateToCell: row ${rowIndex} evicted by col scroll, recovering`);
+            await scrollToRow(nav.context, rowIndex);
+        }
+    };
+    if (nav.barrier) {
+        await nav.barrier.runExclusiveRecovery(recover);
+    }
+    else {
+        await recover();
+    }
+}
+async function visibleRanges(nav) {
+    const viewport = nav.config.strategies.viewport;
+    const colRange = (viewport === null || viewport === void 0 ? void 0 : viewport.getVisibleColumnRange) ? await viewport.getVisibleColumnRange(nav.context) : null;
+    const rowRange = (viewport === null || viewport === void 0 ? void 0 : viewport.getVisibleRowRange) ? await viewport.getVisibleRowRange(nav.context) : null;
+    return { colRange, rowRange };
+}
+async function describeViewportMiss(nav, viewport, rowIndex) {
+    const colRange = viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(nav.context) : null;
+    const rowRange = viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(nav.context) : null;
+    let errMsg = `SmartTable: could not reach cell for column "${nav.column}" (colIndex ${nav.index}) at row ${rowIndex}.\n`;
+    errMsg += colRange
+        ? `  Visible column range: [${colRange.first}–${colRange.last}]. Column is out of view and no navigation fallback is configured.\n`
+        : `  Column is out of view and no navigation fallback is configured.\n`;
+    if (rowRange) {
+        errMsg += `  Visible row range: [${rowRange.first}–${rowRange.last}]. ${inRange(rowIndex, rowRange) ? 'Row is in view.' : 'Row is out of view.'}\n`;
+    }
+    errMsg += `  → Add a \`strategies.navigation\` or \`strategies.viewport.scrollToColumn\` to handle off-screen columns.`;
+    return errMsg;
+}
+/** Navigation-primitive phase (goUp/goDown/goLeft/goRight, optional snap/seek). */
+async function navigateViaPrimitives(nav, primitives) {
+    const { rowIndex } = nav;
+    if (await nav.targetReached()) {
+        // Already there. If we have a barrier, check-in to stay in lock-step.
+        await checkIn(nav);
+        return nav.getCellLocator();
+    }
+    if (typeof rowIndex !== 'number') {
+        if (nav.allowMissingCell)
+            return nav.getCellLocator();
+        throw new Error('Row index is required for navigation');
+    }
+    const focused = await focusUnfocusedCell(nav);
+    if (focused)
+        return focused;
+    // Not there, perform (coordinated) navigation
+    const navResult = await coordinated(nav, () => stepToCell(nav, primitives, rowIndex));
+    return finishNavigation(nav, navResult, rowIndex);
+}
+/** Picks the cell after stepping: the one stepToCell found mid-navigation, else the final locator. */
+async function finishNavigation(nav, navResult, rowIndex) {
+    if (navResult && typeof navResult.count === 'function' && await navResult.count() > 0) {
+        return navResult;
+    }
+    const finalCell = nav.getCellLocator();
+    if (await finalCell.count() > 0 || nav.allowMissingCell)
+        return finalCell;
+    const { colRange, rowRange } = await visibleRanges(nav);
+    let errMsg = `SmartTable: could not reach cell for column "${nav.column}" (colIndex ${nav.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)
+        errMsg += `  Visible row range: [${rowRange.first}–${rowRange.last}].\n`;
+    throw new Error(errMsg);
+}
+/**
+ * If getActiveCell is present but returns null (no focus), and the cell is in the DOM,
+ * focus it once before entering the navigation loop.
+ */
+async function focusUnfocusedCell(nav) {
+    if (!nav.config.strategies.getActiveCell)
+        return null;
+    if (await nav.readActiveCell())
+        return null;
+    const cell = nav.resolve(nav.config.cellSelector, nav.rowLocator).nth(nav.index);
+    if (await cell.count() === 0)
+        return null;
+    log(nav.config, `_navigateToCell: cell "${nav.column}" found but not focused; focusing.`);
+    await cell.focus();
+    // Re-check target
+    if (!await nav.targetReached())
+        return null;
+    await checkIn(nav);
+    return cell;
+}
+/** Tracks the active cell position while stepping (stays at the last known value when focus is unknown). */
+class Position {
+    constructor(nav) {
+        this.nav = nav;
+        this.row = 0;
+        this.col = 0;
+    }
+    async sync() {
+        const ac = await this.nav.readActiveCell();
+        if (ac) {
+            this.row = ac.rowIndex;
+            this.col = ac.columnIndex;
+        }
+    }
+}
+/** A configured non-negative wait, or the computed default. */
+const waitOrDefault = (configured, computed) => (Number.isFinite(configured) && configured >= 0) ? configured : computed;
+async function repeatStep(times, step) {
+    if (!step)
+        return;
+    for (let i = 0; i < times; i++)
+        await step();
+}
+/** Column-0 snap and long-distance seek, both owned by the navigation primitive. */
+async function alignColumn(nav, primitives, pos) {
+    const { config, context, index } = nav;
+    // Core must not special-case canvas/Home — that was pre-viewport Glide glue.
+    if (index === 0 && primitives.snapFirstColumnIntoView) {
+        log(config, '_navigateToCell: snapFirstColumnIntoView for column index 0');
+        await primitives.snapFirstColumnIntoView(context);
+        await pos.sync();
+    }
+    if (Math.abs(index - pos.col) > 12 && primitives.seekColumnIndex) {
+        log(config, `_navigateToCell: seekColumnIndex approx for column ${index}`);
+        await primitives.seekColumnIndex(context, index);
+        await pos.sync();
+    }
+}
+/**
+ * After horizontal steps, poll until getActiveCell / DOM presence confirms the target
+ * (a11y trees and virtual mounts often lag the scroll). Tune via navigation.maxWaitMs.
+ */
+async function pollForTarget(nav, primitives, horizontalSteps) {
+    const pollIntervalMs = 10;
+    const maxWaitMs = waitOrDefault(primitives.maxWaitMs, Math.min(6000, 250 + horizontalSteps * 25));
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        const ac = await nav.readActiveCell();
+        if (ac && nav.isActiveTarget(ac))
+            return ac.locator;
+        if (await nav.targetReached())
+            break;
+        await nav.page.waitForTimeout(pollIntervalMs);
+    }
+    return undefined;
+}
+/** Steps with the navigation primitives from the active cell to the target, then waits for it. */
+async function stepToCell(nav, primitives, rowIndex) {
+    const { context, index } = nav;
+    const pos = new Position(nav);
+    await pos.sync();
+    // Navigate vertically (tight loop)
+    const rDiff = rowIndex - pos.row;
+    const goVertical = rDiff > 0 ? primitives.goDown : primitives.goUp;
+    await repeatStep(Math.abs(rDiff), goVertical && (() => goVertical(context)));
+    await pos.sync();
+    await alignColumn(nav, primitives, pos);
+    const cDiff = index - pos.col;
+    const goHorizontal = cDiff > 0 ? primitives.goRight : primitives.goLeft;
+    await repeatStep(Math.abs(cDiff), goHorizontal && (() => goHorizontal(context)));
+    const horizontalSteps = Math.abs(cDiff);
+    if (horizontalSteps > 0) {
+        await nav.page.waitForTimeout(waitOrDefault(primitives.settleMs, Math.min(2500, 60 + horizontalSteps * 12)));
+    }
+    return pollForTarget(nav, primitives, horizontalSteps);
+}

package/dist/engine/countRows.d.ts

@@ -24,4 +24,5 @@ export interface CountRowsEnv<T = any> {
 export declare function countRows<T>(env: CountRowsEnv<T>, filters?: Record<string, FilterValue>, options?: {
     exact?: boolean;
     maxPages?: number;
+    signal?: AbortSignal;
 }): Promise<number>;

package/dist/engine/countRows.js

@@ -40,15 +40,15 @@ function requireMap(tableMapper) {
  * Callers must have initialized the table.
  */
 async function countRows(env, filters, options) {
-    var _a;
-    var _b, _c;
+    var _a, _b, _c, _d, _e;
+    var _f, _g;
     const { config, rootLocator, tableMapper, rowFinder } = env;
     const filtersRecord = filters !== null && filters !== void 0 ? filters : {};
     const hasFilters = Object.keys(filtersRecord).length > 0;
-    const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages;
+    const effectiveMaxPages = (_f = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _f !== void 0 ? _f : config.maxPages;
     const pag = config.strategies.pagination;
     const hasPagination = effectiveMaxPages > 1 && !!((pag === null || pag === void 0 ? void 0 : pag.goNext) || (pag === null || pag === void 0 ? void 0 : pag.goNextBulk));
-    const exact = (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false;
+    const exact = (_g = options === null || options === void 0 ? void 0 : options.exact) !== null && _g !== void 0 ? _g : false;
     const { domFilters, overrideFilters, syntheticFilters } = partitionFilters(config, filtersRecord);
     const hasOverrides = Object.keys(overrideFilters).length > 0;
     const hasSynthetics = Object.keys(syntheticFilters).length > 0;
@@ -80,14 +80,23 @@ async function countRows(env, filters, options) {
             return;
         await (0, loadingWait_1.waitWhileTableLoading)(config, env.getContext(), rootLocator.page(), 'countRows');
     };
+    (_b = options === null || options === void 0 ? void 0 : options.signal) === null || _b === void 0 ? void 0 : _b.throwIfAborted();
     await waitForReady();
+    (_c = options === null || options === void 0 ? void 0 : options.signal) === null || _c === void 0 ? void 0 : _c.throwIfAborted();
     const filterSuffix = hasFilters ? ` filters=${(0, safeStringify_1.safeStringify)(filtersRecord)}` : '';
     if (!hasPagination) {
         log(config, `countRows: counting rows in current viewport (no pagination)${filterSuffix}`);
-        if (!hasPostFilters)
-            return resolveRows().count();
-        const all = await resolveRows().all();
-        return countPostFilterMatches(all, all.map((_, i) => i));
+        let count;
+        if (!hasPostFilters) {
+            count = await resolveRows().count();
+        }
+        else {
+            const all = await resolveRows().all();
+            (_d = options === null || options === void 0 ? void 0 : options.signal) === null || _d === void 0 ? void 0 : _d.throwIfAborted();
+            count = await countPostFilterMatches(all, all.map((_, i) => i));
+        }
+        (_e = options === null || options === void 0 ? void 0 : options.signal) === null || _e === void 0 ? void 0 : _e.throwIfAborted();
+        return count;
     }
     log(config, `countRows: paginating up to ${effectiveMaxPages} page(s)${filterSuffix}`);
     const tracker = new elementTracker_1.ElementTracker('countRows');
@@ -113,6 +122,7 @@ async function countRows(env, filters, options) {
             useBulk: false,
             label: 'countRows',
             finalScanOnEof: true,
+            signal: options === null || options === void 0 ? void 0 : options.signal,
         });
         pagesScanned = scanned.pagesScanned;
     }

package/dist/engine/rowByIndex.d.ts

@@ -16,4 +16,5 @@ export interface RowByIndexEnv<T = any> {
  */
 export declare function findRowByIndex<T>(env: RowByIndexEnv<T>, index: number, options?: {
     maxPages?: number;
+    signal?: AbortSignal;
 }): Promise<SmartRow<T>>;

package/dist/engine/rowByIndex.js

@@ -11,7 +11,9 @@ const safeStringify_1 = require("../utils/safeStringify");
  * mounts (bounded by `maxPages`). Callers must have initialized the table.
  */
 async function findRowByIndex(env, index, options) {
-    var _a;
+    var _a, _b, _c, _d, _e;
+    var _f;
+    (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.throwIfAborted();
     const { config } = env;
     (0, debugUtils_1.logDebug)(config, 'verbose', `findRowByIndex: index=${index} options=${(0, safeStringify_1.safeStringify)(options)}`);
     const resolveRI = config.strategies.resolveRowIndex;
@@ -25,9 +27,12 @@ async function findRowByIndex(env, index, options) {
     let foundSelector;
     // The currently-mounted row whose logical index === index, if any.
     const findMounted = async () => {
+        var _a, _b;
         const rows = await env.getRowLocators().all();
+        (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.throwIfAborted();
         for (const r of rows) {
             const result = await resolveRI(r);
+            (_b = options === null || options === void 0 ? void 0 : options.signal) === null || _b === void 0 ? void 0 : _b.throwIfAborted();
             if (result === undefined)
                 continue;
             const normalized = (0, rowResolution_1.normalizeRowIndexResult)(result);
@@ -40,22 +45,25 @@ async function findRowByIndex(env, index, options) {
     };
     // 1. Already mounted (no navigation needed)?
     let loc = await findMounted();
+    (_b = options === null || options === void 0 ? void 0 : options.signal) === null || _b === void 0 ? void 0 : _b.throwIfAborted();
     // 2. Fast path: jump straight to it via the viewport's random-access scroll.
     if (!loc && (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow)) {
         (0, debugUtils_1.logDebug)(config, 'verbose', `findRowByIndex: scrolling to row ${index}`);
         await viewport.scrollToRow(env.getContext(), index);
+        (_c = options === null || options === void 0 ? void 0 : options.signal) === null || _c === void 0 ? void 0 : _c.throwIfAborted();
         loc = await findMounted();
+        (_d = options === null || options === void 0 ? void 0 : options.signal) === null || _d === void 0 ? void 0 : _d.throwIfAborted();
     }
     // 3. Fallback: advance pages (on infinite-scroll tables, a "page" is a scroll step) until
     //    the row is mounted. Page 1 was already searched above.
-    const maxPages = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
+    const maxPages = (_f = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _f !== void 0 ? _f : config.maxPages;
     const scanForMounted = async () => {
         let hit = null;
         await (0, scanPages_1.scanPages)({ advancePage: env.advancePage, getCurrentPageIndex: env.getCurrentPageIndex, config }, async ({ pagesScanned }) => {
             if (pagesScanned > 1)
                 hit = await findMounted();
             return hit ? 'stop' : 'continue';
-        }, { maxPages, useBulk: false, label: 'findRowByIndex', finalScanOnEof: false });
+        }, { maxPages, useBulk: false, label: 'findRowByIndex', finalScanOnEof: false, signal: options === null || options === void 0 ? void 0 : options.signal });
         return hit;
     };
     if (!loc && config.strategies.pagination) {
@@ -66,5 +74,6 @@ async function findRowByIndex(env, index, options) {
             `Ensure a viewport.scrollToRow or pagination can bring it into view (searched up to maxPages=${maxPages}).`);
     }
     await (0, debugUtils_1.debugDelay)(config, 'findRow');
+    (_e = options === null || options === void 0 ? void 0 : options.signal) === null || _e === void 0 ? void 0 : _e.throwIfAborted();
     return env.makeSmartRow(loc, env.getMap(), index, env.getCurrentPageIndex(), foundSelector);
 }

package/dist/engine/rowFinder.d.ts

@@ -23,6 +23,7 @@ export declare class RowFinder<T = any> {
     findRow(filters: Record<string, FilterValue>, options?: {
         exact?: boolean;
         maxPages?: number;
+        signal?: AbortSignal;
     }): Promise<SmartRow<T>>;
     private waitForTableReady;
     /** Unfiltered rows keep the plain `SmartRow #n` name that `_makeSmart` applies. */
@@ -31,6 +32,7 @@ export declare class RowFinder<T = any> {
         exact?: boolean;
         maxPages?: number;
         useBulkPagination?: boolean;
+        signal?: AbortSignal;
     }): Promise<SmartRowArray<T>>;
     private findRowLocator;
     private resolveRowIndex;

package/dist/engine/rowFinder.js

@@ -204,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)`);
         }
@@ -268,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>;