@rickcedwhat/playwright-smart-table 6.20.1-next.720a2e5 → 6.20.1-next.b5aa4bd

package/dist/engine/rowFinder.js

@@ -7,6 +7,7 @@ const elementTracker_1 = require("../utils/elementTracker");
 const sentinel_1 = require("../utils/sentinel");
 const navigationBarrier_1 = require("../utils/navigationBarrier");
 const rowResolution_1 = require("./rowResolution");
+const resolveCellLocator_1 = require("../utils/resolveCellLocator");
 class RowFinder {
     constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow, tableState = { currentPageIndex: 0 }, advancePage = async () => false) {
         this.rootLocator = rootLocator;
@@ -56,12 +57,26 @@ class RowFinder {
             if (colIndex === undefined)
                 continue;
             const override = this.config.columnOverrides[colName];
-            const cell = this.resolve(this.config.cellSelector, rowLocator).nth(colIndex);
+            const cell = (0, resolveCellLocator_1.resolveCellLocator)({
+                config: this.config,
+                resolve: this.resolve,
+                row: rowLocator,
+                root: this.rootLocator,
+                columnName: colName,
+                columnIndex: colIndex,
+            });
             const getCell = (name) => {
                 const idx = map.get(name);
                 if (idx === undefined)
                     throw new Error(`Column "${name}" not found`);
-                return this.resolve(this.config.cellSelector, rowLocator).nth(idx);
+                return (0, resolveCellLocator_1.resolveCellLocator)({
+                    config: this.config,
+                    resolve: this.resolve,
+                    row: rowLocator,
+                    root: this.rootLocator,
+                    columnName: name,
+                    columnIndex: idx,
+                });
             };
             const context = {
                 row: this.makeSmartRow(rowLocator, map, undefined),

package/dist/engine/tableIteration.js

@@ -37,6 +37,7 @@ async function runMap(env, callback, options = {}, label = 'map') {
     const tracker = new elementTracker_1.ElementTracker(label);
     log(env.config, `${label}: starting (maxPages=${effectiveMaxPages}, mode=${concurrency}, dedupe=${!!dedupeStrategy})`);
     const results = [];
+    const seenLogicalIndices = new Set();
     try {
         let rowIndex = 0;
         let stopped = false;
@@ -114,6 +115,13 @@ async function runMap(env, callback, options = {}, label = 'map') {
                         if (stopped && enumIndex > stoppedIndex) {
                             return SKIP;
                         }
+                        // When resolveRowIndex is configured, identical logical indices across pages
+                        // indicate the same record (e.g. re-created DOM elements in recycling
+                        // virtualizers whose WeakMap entry was GC'd). Skip without processing.
+                        if (row.rowIndex !== undefined && seenLogicalIndices.has(row.rowIndex)) {
+                            log(env.config, `${label}: skipping duplicate logical row ${row.rowIndex}`);
+                            return SKIP;
+                        }
                         // Wait for the row to finish loading BEFORE evaluating its dedupe key (Bug #355).
                         // map/forEach/filter process a still-loading row when no timeout is set (unlike
                         // findRows, which skips) — see resolveRowLoading's `noTimeoutAction`.
@@ -144,6 +152,9 @@ async function runMap(env, callback, options = {}, label = 'map') {
                         if (dedupeKeys && dedupeKey !== undefined && result !== SKIP) {
                             dedupeKeys.add(dedupeKey);
                         }
+                        if (row.rowIndex !== undefined && result !== SKIP) {
+                            seenLogicalIndices.add(row.rowIndex);
+                        }
                         return result;
                     }
                     finally {

package/dist/filterEngine.d.ts

@@ -10,6 +10,10 @@ export declare class FilterEngine {
      * Note: `rootLocator` is optional for backward compatibility in call sites that already
      * pass only the page. When strategies.filter is present we construct a TableContext
      * using the provided `rootLocator`.
+     *
+     * When `strategies.getCellLocator` is set, cells are resolved through that strategy
+     * (via a `:scope` row stub) so column-virtualized grids that use `aria-colindex` / etc.
+     * are not filtered with fragile `.nth(colIndex)` DOM order.
      */
     applyFilters(baseRows: Locator, filters: Record<string, FilterValue>, map: Map<string, number>, exact: boolean, page: Page, rootLocator?: Locator): Locator;
 }

package/dist/filterEngine.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FilterEngine = void 0;
 const stringUtils_1 = require("./utils/stringUtils");
+const resolveCellLocator_1 = require("./utils/resolveCellLocator");
 class FilterEngine {
     constructor(config, resolve) {
         this.config = config;
@@ -13,6 +14,10 @@ class FilterEngine {
      * Note: `rootLocator` is optional for backward compatibility in call sites that already
      * pass only the page. When strategies.filter is present we construct a TableContext
      * using the provided `rootLocator`.
+     *
+     * When `strategies.getCellLocator` is set, cells are resolved through that strategy
+     * (via a `:scope` row stub) so column-virtualized grids that use `aria-colindex` / etc.
+     * are not filtered with fragile `.nth(colIndex)` DOM order.
      */
     applyFilters(baseRows, filters, map, exact, page, rootLocator) {
         var _a;
@@ -41,10 +46,16 @@ class FilterEngine {
                 });
                 continue;
             }
-            // Default Filter Logic
-            const cellTemplate = this.resolve(this.config.cellSelector, page);
-            // Playwright scoping: `cellTemplate.nth(colIndex)` will be re-based when used in filtered.filter({ has: ... })
-            const targetCell = cellTemplate.nth(colIndex);
+            // Prefer getCellLocator (column-virtualized presets); else cellSelector.nth.
+            // Playwright re-bases the `has` locator into each candidate row.
+            const targetCell = (0, resolveCellLocator_1.resolveCellLocatorForFilter)({
+                config: this.config,
+                resolve: this.resolve,
+                page,
+                root: rootLocator,
+                columnName: colName,
+                columnIndex: colIndex,
+            });
             if (typeof filterVal === 'function') {
                 // Locator-based filter: (cell) => cell.locator(...)
                 filtered = filtered.filter({

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { PLAYWRIGHT_SMART_TABLE_VERSION } from './packageVersion';
 export { useTable } from './useTable';
-export type { TableConfig, TableResult, SmartRow, SmartCell, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, SyntheticColumnDef, ColumnOverride, ColumnOverrideReadContext, } from './types';
+export type { TableConfig, TableResult, SmartRow, SmartCell, Selector, FilterValue, PaginationPrimitives, SortingStrategy, FillOptions, RowIterationContext, RowIterationOptions, TableContext, StrategyContext, BeforeCellReadFn, GetCellLocatorFn, GetActiveCellFn, DebugConfig, SyntheticColumnDef, ColumnOverride, ColumnOverrideReadContext, TableStrategies, LoadingStrategy, ViewportStrategy, FilterStrategy, NavigationPrimitives, DedupeStrategy, ContentReadyStrategy, FillStrategy, PaginationStrategy, HeaderStrategy, } from './types';
 export { Strategies } from './strategies';
 export * as presets from './presets';
-/** @deprecated Use `presets` instead. Plugins will be removed in v7.0.0. */
+/**
+ * @deprecated Use `presets` instead (`presets.muiDataGrid`, `presets.rdg`, `presets.glide`, …).
+ * `Plugins` will be removed in v7.0.0.
+ * Note: `Plugins.MUI` is the **DataGrid** preset only — for MUI Table use `presets.muiTable`.
+ */
 export { Plugins } from './plugins';
 export { mergeTableConfig } from './utils/mergeTableConfig';

package/dist/index.js

@@ -42,7 +42,11 @@ Object.defineProperty(exports, "useTable", { enumerable: true, get: function ()
 var strategies_1 = require("./strategies");
 Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
 exports.presets = __importStar(require("./presets"));
-/** @deprecated Use `presets` instead. Plugins will be removed in v7.0.0. */
+/**
+ * @deprecated Use `presets` instead (`presets.muiDataGrid`, `presets.rdg`, `presets.glide`, …).
+ * `Plugins` will be removed in v7.0.0.
+ * Note: `Plugins.MUI` is the **DataGrid** preset only — for MUI Table use `presets.muiTable`.
+ */
 var plugins_1 = require("./plugins");
 Object.defineProperty(exports, "Plugins", { enumerable: true, get: function () { return plugins_1.Plugins; } });
 var mergeTableConfig_1 = require("./utils/mergeTableConfig");

package/dist/packageVersion.d.ts

@@ -3,4 +3,4 @@
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.20.1-next.720a2e5";
+export declare const PLAYWRIGHT_SMART_TABLE_VERSION: "6.20.1-next.b5aa4bd";

package/dist/packageVersion.js

@@ -6,4 +6,4 @@ exports.PLAYWRIGHT_SMART_TABLE_VERSION = void 0;
  * Generated by scripts/embed-version.mjs from package.json
  */
 /** Semver of this package. Use in logs or diagnostics to confirm the installed build. */
-exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.20.1-next.720a2e5";
+exports.PLAYWRIGHT_SMART_TABLE_VERSION = "6.20.1-next.b5aa4bd";

package/dist/plugins/index.d.ts

@@ -1,13 +1,32 @@
 /**
  * @deprecated Use `presets` instead. Plugins will be removed in v7.0.0.
- * Presets for specific table/grid libraries. Each plugin exposes:
- * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Presets.MUI, maxPages: 5 }).
- * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Presets.MUI.Strategies }).
+ *
+ * Compatibility shim over official presets:
+ * - `Plugins.MUI` → `presets.muiDataGrid` (**DataGrid only** — not `presets.muiTable`)
+ * - `Plugins.RDG` → `presets.rdg`
+ * - `Plugins.Glide` → `presets.glide`
+ *
+ * Prefer: `useTable(loc, { ...presets.muiDataGrid, maxPages: 5 })`.
+ * Strategies only: `useTable(loc, { rowSelector: '...', strategies: presets.muiDataGrid.strategies })`.
  */
 export declare const Plugins: {
     /** @deprecated Use `presets.rdg` */
     RDG: {
-        Strategies: import("../types").TableStrategies | undefined;
+        Strategies: {
+            header: (context: import("..").TableContext) => Promise<string[]>;
+            getCellLocator: ({ row, columnIndex }: {
+                row: import("@playwright/test").Locator;
+                columnIndex: number;
+            }) => import("@playwright/test").Locator;
+            navigation: {
+                goRight: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goLeft: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goDown: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goUp: ({ root }: import("..").StrategyContext) => Promise<void>;
+                goHome: ({ root }: import("..").StrategyContext) => Promise<void>;
+            };
+            pagination: import("..").PaginationPrimitives;
+        };
         headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
         rowSelector?: string | undefined;
         cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
@@ -22,14 +41,33 @@ export declare const Plugins: {
         autoScroll?: boolean | undefined;
         debug?: import("..").DebugConfig | undefined;
         onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
-        strategies?: import("../types").TableStrategies | undefined;
+        strategies?: import("..").TableStrategies | undefined;
         columnOverrides?: Partial<Record<string | number | symbol, import("..").ColumnOverride<any>>> | undefined;
         syntheticColumns?: Record<string, import("..").SyntheticColumnDef<any>> | undefined;
         emptyState?: import("@playwright/test").Locator | undefined;
     };
     /** @deprecated Use `presets.glide` */
     Glide: {
-        Strategies: import("../types").TableStrategies | undefined;
+        Strategies: {
+            fillSimple: import("..").FillStrategy;
+            fill: import("..").FillStrategy;
+            pagination: import("..").PaginationPrimitives;
+            header: (context: import("..").StrategyContext, options?: {
+                limit?: number;
+                selector?: string;
+                scrollAmount?: number;
+            }) => Promise<string[]>;
+            viewport: import("..").ViewportStrategy;
+            loading: {
+                isHeaderLoading: () => Promise<boolean>;
+            };
+            getCellLocator: ({ row, columnIndex }: any) => any;
+            getActiveCell: ({ page }: any) => Promise<{
+                rowIndex: number;
+                columnIndex: number;
+                locator: any;
+            } | null>;
+        };
         headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
         rowSelector?: string | undefined;
         cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
@@ -44,14 +82,17 @@ export declare const Plugins: {
         autoScroll?: boolean | undefined;
         debug?: import("..").DebugConfig | undefined;
         onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
-        strategies?: import("../types").TableStrategies | undefined;
+        strategies?: import("..").TableStrategies | undefined;
         columnOverrides?: Partial<Record<string | number | symbol, import("..").ColumnOverride<any>>> | undefined;
         syntheticColumns?: Record<string, import("..").SyntheticColumnDef<any>> | undefined;
         emptyState?: import("@playwright/test").Locator | undefined;
     };
-    /** @deprecated Use `presets.muiDataGrid` */
+    /**
+     * @deprecated Use `presets.muiDataGrid`.
+     * DataGrid only — for MUI `<Table>` use `presets.muiTable`.
+     */
     MUI: {
-        Strategies: import("../types").TableStrategies | undefined;
+        Strategies: import("..").TableStrategies | undefined;
         headerSelector?: string | ((root: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
         rowSelector?: string | undefined;
         cellSelector?: string | ((row: import("@playwright/test").Locator) => import("@playwright/test").Locator) | undefined;
@@ -66,7 +107,7 @@ export declare const Plugins: {
         autoScroll?: boolean | undefined;
         debug?: import("..").DebugConfig | undefined;
         onReset?: ((context: import("..").TableContext) => Promise<void>) | undefined;
-        strategies?: import("../types").TableStrategies | undefined;
+        strategies?: import("..").TableStrategies | undefined;
         columnOverrides?: Partial<Record<string | number | symbol, import("..").ColumnOverride<any>>> | undefined;
         syntheticColumns?: Record<string, import("..").SyntheticColumnDef<any>> | undefined;
         emptyState?: import("@playwright/test").Locator | undefined;

package/dist/plugins/index.js

@@ -4,15 +4,23 @@ exports.Plugins = void 0;
 const presets_1 = require("../presets");
 /**
  * @deprecated Use `presets` instead. Plugins will be removed in v7.0.0.
- * Presets for specific table/grid libraries. Each plugin exposes:
- * - Plugins.X — full preset (selectors + headerTransformer if any + strategies). Spread: useTable(loc, { ...Presets.MUI, maxPages: 5 }).
- * - Plugins.X.Strategies — strategies only. Use with your own selectors: useTable(loc, { rowSelector: '...', strategies: Presets.MUI.Strategies }).
+ *
+ * Compatibility shim over official presets:
+ * - `Plugins.MUI` → `presets.muiDataGrid` (**DataGrid only** — not `presets.muiTable`)
+ * - `Plugins.RDG` → `presets.rdg`
+ * - `Plugins.Glide` → `presets.glide`
+ *
+ * Prefer: `useTable(loc, { ...presets.muiDataGrid, maxPages: 5 })`.
+ * Strategies only: `useTable(loc, { rowSelector: '...', strategies: presets.muiDataGrid.strategies })`.
  */
 exports.Plugins = {
     /** @deprecated Use `presets.rdg` */
-    RDG: Object.assign(Object.assign({}, presets_1.rdg), { Strategies: presets_1.rdg.strategies }),
+    RDG: Object.assign(Object.assign({}, presets_1.rdg), { Strategies: presets_1.rdg.Strategies }),
     /** @deprecated Use `presets.glide` */
-    Glide: Object.assign(Object.assign({}, presets_1.glide), { Strategies: presets_1.glide.strategies }),
-    /** @deprecated Use `presets.muiDataGrid` */
+    Glide: Object.assign(Object.assign({}, presets_1.glide), { Strategies: presets_1.glide.Strategies }),
+    /**
+     * @deprecated Use `presets.muiDataGrid`.
+     * DataGrid only — for MUI `<Table>` use `presets.muiTable`.
+     */
     MUI: Object.assign(Object.assign({}, presets_1.muiDataGrid), { Strategies: presets_1.muiDataGrid.strategies }),
 };

package/dist/presets/glide/index.d.ts

@@ -12,7 +12,7 @@ export declare const GlideStrategies: {
         selector?: string;
         scrollAmount?: number;
     }) => Promise<string[]>;
-    viewport: import("../../types").ViewportStrategy;
+    viewport: import("../..").ViewportStrategy;
     loading: {
         isHeaderLoading: () => Promise<boolean>;
     };

package/dist/presets/glide/index.js

@@ -123,8 +123,8 @@ function createGlide(options = {}) {
 }
 /**
  * Full preset for Glide Data Grid (selectors + default strategies only).
- * Spread: useTable(loc, { ...Plugins.Glide, maxPages: 5 }).
- * Strategies only (including fillSimple): useTable(loc, { rowSelector: '...', strategies: Plugins.Glide.Strategies }).
+ * Spread: `useTable(loc, { ...presets.glide, maxPages: 5 })`.
+ * Strategies only (including fillSimple): `useTable(loc, { rowSelector: '...', strategies: presets.glide.Strategies })`.
  * For a non-64-column grid, use `createGlide({ columnCount })` instead.
  */
 const GlidePreset = {

package/dist/presets/rdg.d.ts

@@ -1,6 +1,6 @@
 import type { Locator } from '@playwright/test';
 import { TableContext, TableConfig, ViewportStrategy, StrategyContext } from '../types';
-/** Full strategies for React Data Grid. Use when you want to supply your own selectors: strategies: Plugins.RDG.Strategies */
+/** Full strategies for React Data Grid. Use when you want to supply your own selectors: `strategies: presets.rdg.Strategies` */
 export declare const RDGStrategies: {
     header: (context: TableContext) => Promise<string[]>;
     getCellLocator: ({ row, columnIndex }: {

package/dist/presets/rdg.js

@@ -92,20 +92,20 @@ const rdgNavigation = {
         });
     }
 };
-/** Default strategies for the RDG preset (used when you spread Plugins.RDG). */
+/** Default strategies for the RDG preset (used when you spread `presets.rdg`). */
 const RDGDefaultStrategies = {
     header: scrollRightHeaderRDG,
     getCellLocator: rdgGetCellLocator,
     navigation: rdgNavigation,
     pagination: rdgPaginationStrategy
 };
-/** Full strategies for React Data Grid. Use when you want to supply your own selectors: strategies: Plugins.RDG.Strategies */
+/** Full strategies for React Data Grid. Use when you want to supply your own selectors: `strategies: presets.rdg.Strategies` */
 // fallow-ignore-next-line unused-export
 exports.RDGStrategies = RDGDefaultStrategies;
 /**
  * Full preset for React Data Grid (selectors + default strategies).
- * Spread: useTable(loc, { ...Plugins.RDG, maxPages: 5 }).
- * Strategies only: useTable(loc, { rowSelector: '...', strategies: Plugins.RDG.Strategies }).
+ * Spread: `useTable(loc, { ...presets.rdg, maxPages: 5 })`.
+ * Strategies only: `useTable(loc, { rowSelector: '...', strategies: presets.rdg.Strategies })`.
  */
 const RDGPreset = {
     rowSelector: '[role="row"].rdg-row',

package/dist/smartRow.js

@@ -196,6 +196,8 @@ const _navigateToCell = async (params) => {
                     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);
@@ -206,27 +208,6 @@ const _navigateToCell = async (params) => {
                         currCol = ac.columnIndex;
                     }
                 }
-                // Home moves a11y focus within the current row to column 0. If focus row !== target row
-                // (e.g. still on previous row), Home jumps to grid origin and breaks `tr.nth(k)` reads.
-                if (typeof rowIndex === 'number' && currRow === rowIndex) {
-                    await rootLocator.evaluate((el) => {
-                        var _a;
-                        const canvas = el.closest('canvas') || ((_a = el.parentElement) === null || _a === void 0 ? void 0 : _a.querySelector('canvas'));
-                        if (canvas instanceof HTMLCanvasElement) {
-                            canvas.tabIndex = 0;
-                            canvas.focus();
-                        }
-                    });
-                    await page.keyboard.press('Home');
-                    await page.waitForTimeout(120);
-                    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) {
@@ -253,8 +234,8 @@ const _navigateToCell = async (params) => {
                 const settleMs = (Number.isFinite(nav.settleMs) && nav.settleMs >= 0) ? nav.settleMs : computed;
                 await page.waitForTimeout(settleMs);
             }
-            // Wait for active cell to match target: poll getActiveCell or fallback to fixed delay
-            // This is the "Midas Touch" buffer needed for Glide's async accessibility updates.
+            // 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;
@@ -424,7 +405,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         return (await cell.innerText()).trim();
     };
     smart.toJSON = async (options) => {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
+        var _a, _b, _c, _d, _e, _f, _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.
@@ -434,10 +415,84 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 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 ( /* element may have detached during scan */_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 rowLocator.evaluateHandle(el => el.cloneNode(true));
+            const cloneHandle = await cloneTarget.evaluateHandle(el => el.cloneNode(true));
             let snapshot;
             try {
                 snapshot = await cloneHandle.evaluate((row, sel) => {
@@ -491,7 +546,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                     await materializeRow();
                 const result = {};
                 for (const [col, idx] of columnsToProcess) {
-                    const columnOverride = (_a = config.columnOverrides) === null || _a === void 0 ? void 0 : _a[col];
+                    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);
@@ -508,7 +563,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                         result[col] = snapshot.cells[idx].text;
                     }
                 }
-                for (const [name, def] of Object.entries((_b = config.syntheticColumns) !== null && _b !== void 0 ? _b : {})) {
+                for (const [name, def] of Object.entries((_c = config.syntheticColumns) !== null && _c !== void 0 ? _c : {})) {
                     if ((options === null || options === void 0 ? void 0 : options.columns) && !options.columns.includes(name))
                         continue;
                     const snapshotRow = Object.create(smart);
@@ -607,7 +662,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             // 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 columnOverride = (_d = config.columnOverrides) === null || _d === void 0 ? void 0 : _d[col];
             const mapper = columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read;
             // --- Navigation Logic Start ---
             const cell = config.strategies.getCellLocator
@@ -654,13 +709,13 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 });
             }
             // 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;
+            const isCellLoading = (_e = config.strategies.loading) === null || _e === void 0 ? void 0 : _e.isCellLoading;
+            const rawCellTimeout = (_f = config.strategies.loading) === null || _f === void 0 ? void 0 : _f.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 = (_g = (_f = config.strategies.loading) === null || _f === void 0 ? void 0 : _f.onCellLoadingTimeout) !== null && _g !== void 0 ? _g : 'read-as-is';
+            const onCellLoadingTimeout = (_h = (_g = config.strategies.loading) === null || _g === void 0 ? void 0 : _g.onCellLoadingTimeout) !== null && _h !== void 0 ? _h : 'read-as-is';
             if (isCellLoading && await isCellLoading(targetCell, col, smart)) {
                 if (cellLoadingTimeout !== undefined) {
                     (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — waiting up to ${cellLoadingTimeout}ms`);
@@ -699,7 +754,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 result[col] = (text || '').trim();
             }
         }
-        for (const [name, def] of Object.entries((_h = config.syntheticColumns) !== null && _h !== void 0 ? _h : {})) {
+        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);

package/dist/strategies/columns.d.ts

@@ -12,7 +12,9 @@ export interface NavigationPrimitives {
     goHome?: (context: StrategyContext) => Promise<void>;
     /**
      * After vertical moves, run before horizontal steps when the target column index is 0.
-     * Use for horizontally virtualized a11y tables (e.g. Glide) so `td[aria-colindex="1"]` exists again.
+     * Use for horizontally virtualized tables so the first column exists in the DOM again
+     * (e.g. set scrollLeft = 0). If the table needs keyboard `Home` or canvas focus, put that
+     * here — the core orchestrator does not special-case those behaviors.
      * Do not reset vertical scroll here — RDG-style `goHome` is often unsuitable.
      */
     snapFirstColumnIntoView?: (context: StrategyContext) => Promise<void>;
@@ -33,7 +35,8 @@ export interface NavigationPrimitives {
     maxWaitMs?: number;
 }
 /**
- * @deprecated Use NavigationPrimitives instead. This will be removed in a future version.
+ * @deprecated Use NavigationPrimitives (`strategies.navigation`) instead. Removed from
+ * the public `Strategies` namespace in #428; this type remains for transitional typings.
  * Defines the contract for a cell navigation strategy.
  */
 export type CellNavigationStrategy = (context: StrategyContext & {
@@ -46,10 +49,3 @@ export type CellNavigationStrategy = (context: StrategyContext & {
         locator: Locator;
     } | null;
 }) => Promise<void>;
-export declare const CellNavigationStrategies: {
-    /**
-     * Default strategy: Assumes column is accessible or standard scrolling works.
-     * No specific action taken other than what Playwright's default locator handling does.
-     */
-    default: () => Promise<void>;
-};

package/dist/strategies/columns.js

@@ -1,12 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CellNavigationStrategies = void 0;
-exports.CellNavigationStrategies = {
-    /**
-     * Default strategy: Assumes column is accessible or standard scrolling works.
-     * No specific action taken other than what Playwright's default locator handling does.
-     */
-    default: async () => {
-        // No-op
-    }
-};

package/dist/strategies/contentReady.d.ts

@@ -0,0 +1,20 @@
+import type { ContentReadyStrategy } from '../types';
+export type { ContentReadyStrategy };
+export declare const ContentReadyStrategies: {
+    /**
+     * Polls the row's text content until two consecutive reads match.
+     */
+    textStable: (options?: {
+        timeout?: number;
+        interval?: number;
+    }) => ContentReadyStrategy;
+    /**
+     * Uses MutationObserver to wait for DOM mutations on the row's subtree
+     * to settle. Resolves when no mutations occur for `quietPeriod` ms, or
+     * when `timeout` expires.
+     */
+    mutationSettled: (options?: {
+        timeout?: number;
+        quietPeriod?: number;
+    }) => ContentReadyStrategy;
+};