@rickcedwhat/playwright-smart-table 6.25.0-next.c784f2c → 6.25.0-next.c81cb3d

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

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

package/dist/engine/countRows.js

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

package/dist/engine/rowByIndex.d.ts

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

package/dist/engine/rowByIndex.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findRowByIndex = findRowByIndex;
+const rowResolution_1 = require("./rowResolution");
+const scanPages_1 = require("./scanPages");
+const debugUtils_1 = require("../utils/debugUtils");
+const safeStringify_1 = require("../utils/safeStringify");
+/**
+ * Finds the row whose logical index (per `strategies.resolveRowIndex`) is `index`:
+ * already mounted, else via `viewport.scrollToRow`, else by advancing pages until it
+ * mounts (bounded by `maxPages`). Callers must have initialized the table.
+ */
+async function findRowByIndex(env, index, options) {
+    var _a;
+    const { config } = env;
+    (0, debugUtils_1.logDebug)(config, 'verbose', `findRowByIndex: index=${index} options=${(0, safeStringify_1.safeStringify)(options)}`);
+    const resolveRI = config.strategies.resolveRowIndex;
+    const viewport = config.strategies.viewport;
+    // Identifying a row by its logical index requires a resolveRowIndex strategy. Without one
+    // the library can only offer render-window-relative getRowByIndex, or filter-based findRow.
+    if (!resolveRI) {
+        throw new Error(`findRowByIndex(${index}) requires a strategies.resolveRowIndex to identify rows by their logical index. ` +
+            `Configure one (e.g. read the grid's row-index attribute), or use getRowByIndex() (current render window) / findRow(filters).`);
+    }
+    let foundSelector;
+    // The currently-mounted row whose logical index === index, if any.
+    const findMounted = async () => {
+        const rows = await env.getRowLocators().all();
+        for (const r of rows) {
+            const result = await resolveRI(r);
+            if (result === undefined)
+                continue;
+            const normalized = (0, rowResolution_1.normalizeRowIndexResult)(result);
+            if (normalized.index === index) {
+                foundSelector = normalized.selector;
+                return r;
+            }
+        }
+        return null;
+    };
+    // 1. Already mounted (no navigation needed)?
+    let loc = await findMounted();
+    // 2. Fast path: jump straight to it via the viewport's random-access scroll.
+    if (!loc && (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow)) {
+        (0, debugUtils_1.logDebug)(config, 'verbose', `findRowByIndex: scrolling to row ${index}`);
+        await viewport.scrollToRow(env.getContext(), index);
+        loc = await findMounted();
+    }
+    // 3. Fallback: advance pages (on infinite-scroll tables, a "page" is a scroll step) until
+    //    the row is mounted. Page 1 was already searched above.
+    const maxPages = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
+    const scanForMounted = async () => {
+        let hit = null;
+        await (0, scanPages_1.scanPages)({ advancePage: env.advancePage, getCurrentPageIndex: env.getCurrentPageIndex, config }, async ({ pagesScanned }) => {
+            if (pagesScanned > 1)
+                hit = await findMounted();
+            return hit ? 'stop' : 'continue';
+        }, { maxPages, useBulk: false, label: 'findRowByIndex', finalScanOnEof: false });
+        return hit;
+    };
+    if (!loc && config.strategies.pagination) {
+        loc = await scanForMounted();
+    }
+    if (!loc) {
+        throw new Error(`findRowByIndex(${index}): could not reach row ${index}. ` +
+            `Ensure a viewport.scrollToRow or pagination can bring it into view (searched up to maxPages=${maxPages}).`);
+    }
+    await (0, debugUtils_1.debugDelay)(config, 'findRow');
+    return env.makeSmartRow(loc, env.getMap(), index, env.getCurrentPageIndex(), foundSelector);
+}

package/dist/engine/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>;