@rickcedwhat/playwright-smart-table 6.20.1 → 6.21.0-next.3ab7a18

package/dist/smartRow.js

@@ -1,18 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const test_1 = require("@playwright/test");
 const rowResolution_1 = require("./engine/rowResolution");
 const fill_1 = require("./strategies/fill");
 const stringUtils_1 = require("./utils/stringUtils");
 const debugUtils_1 = require("./utils/debugUtils");
 const paginationPath_1 = require("./utils/paginationPath");
 const sentinel_1 = require("./utils/sentinel");
+const pageIndex_1 = require("./utils/pageIndex");
 /**
  * Internal helper to navigate to a cell with active cell optimization.
  * Uses `strategies.navigation` primitives (goUp/goDown/goLeft/goRight, optional snap/seek/goHome).
  * Returns the target cell locator after navigation.
  */
 const _navigateToCell = async (params) => {
-    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier } = params;
+    const { config, rootLocator, page, resolve, getHeaders, column, index, rowLocator, rowIndex, barrier, allowMissingCell } = params;
     const rowLabel = typeof rowIndex === 'number' ? `row ${rowIndex}` : 'row ?';
     (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: resolving column "${column}" (colIndex ${index}), ${rowLabel}`);
     // Get active cell if strategy is available
@@ -65,7 +67,18 @@ const _navigateToCell = async (params) => {
                     ? await viewport.getVisibleRowRange(context)
                     : null;
                 const rowVisible = !rowRange || (rowIndex >= rowRange.first && rowIndex <= rowRange.last);
-                if (rowVisible && await targetReached()) {
+                let cellAttached = rowVisible && await targetReached();
+                if (rowVisible && !cellAttached) {
+                    try {
+                        await getCellLocator().waitFor({ state: 'attached', timeout: 500 });
+                        cellAttached = true;
+                    }
+                    catch (error) {
+                        if (!(error instanceof test_1.errors.TimeoutError))
+                            throw error;
+                    }
+                }
+                if (cellAttached) {
                     (0, debugUtils_1.logDebug)(config, 'verbose', `_navigateToCell: col ${index} in visible range [${knownColRange.first}-${knownColRange.last}], reading directly`);
                     // Check in to the barrier without a moveAction — peers that need the scroll
                     // still supply their own action and will trigger it when all rows arrive.
@@ -124,6 +137,8 @@ const _navigateToCell = async (params) => {
         }
         // Cell still not accessible — fall through to navigation primitives if configured.
         if (!config.strategies.navigation) {
+            if (allowMissingCell)
+                return getCellLocator();
             const colRange = viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
             const rowRange = viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
             let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex}.\n`;
@@ -144,15 +159,17 @@ const _navigateToCell = async (params) => {
     // Use navigation primitives if available
     if (config.strategies.navigation) {
         const nav = config.strategies.navigation;
-        if (typeof rowIndex !== 'number') {
-            throw new Error('Row index is required for navigation');
-        }
         if (await targetReached()) {
             // Already there. If we have a barrier, check-in to stay in lock-step.
             if (barrier)
                 await barrier.sync(index);
             return getCellLocator();
         }
+        if (typeof rowIndex !== 'number') {
+            if (allowMissingCell)
+                return getCellLocator();
+            throw new Error('Row index is required for navigation');
+        }
         // If getActiveCell is present but returns null (no focus), and cell is in DOM,
         // try to focus it once before entering navigation loop.
         if (config.strategies.getActiveCell) {
@@ -196,6 +213,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 +225,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 +251,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;
@@ -290,6 +288,8 @@ const _navigateToCell = async (params) => {
         const finalCell = getCellLocator();
         if (await finalCell.count() > 0)
             return finalCell;
+        if (allowMissingCell)
+            return finalCell;
         const colRange = viewport && viewport.getVisibleColumnRange ? await viewport.getVisibleColumnRange(context) : null;
         const rowRange = viewport && viewport.getVisibleRowRange ? await viewport.getVisibleRowRange(context) : null;
         let errMsg = `SmartTable: could not reach cell for column "${column}" (colIndex ${index}) at row ${rowIndex} after exhausting navigation strategies. Ensure navigation primitives are correctly implemented.\n`;
@@ -313,7 +313,7 @@ const _navigateToCell = async (params) => {
  * @internal Internal factory for creating SmartRow objects.
  * Not part of the public package surface; tests and consumers should use public APIs.
  */
-const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex, barrier) => {
+const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve, table, tablePageIndex, barrier, renderWindowPosition = false) => {
     const smart = rowLocator;
     // Attach State
     smart.rowIndex = rowIndex;
@@ -406,12 +406,22 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, [...map.keys(), ...Object.keys((_b = config.syntheticColumns) !== null && _b !== void 0 ? _b : {})]));
         }
         const columnOverride = (_c = config.columnOverrides) === null || _c === void 0 ? void 0 : _c[colName];
-        const cell = config.strategies.getCellLocator
-            ? config.strategies.getCellLocator({
-                row: rowLocator, root: rootLocator, columnName: colName,
-                columnIndex: idx, rowIndex, page: rootLocator.page(), config,
-            })
-            : resolve(config.cellSelector, rowLocator).nth(idx);
+        const page = rootLocator.page();
+        // Same nav pipeline as toJSON / getCell().bringIntoView() (#430) so virtualized
+        // off-screen columns don't return empty/stale text.
+        const cell = await _navigateToCell({
+            config,
+            rootLocator,
+            page,
+            resolve,
+            getHeaders: table === null || table === void 0 ? void 0 : table.getHeaders,
+            column: colName,
+            index: idx,
+            rowLocator,
+            rowIndex,
+            barrier: smart._barrier,
+            allowMissingCell: !!(columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read),
+        });
         if (columnOverride === null || columnOverride === void 0 ? void 0 : columnOverride.read) {
             const getCell = (name) => {
                 const ci = map.get(name);
@@ -424,7 +434,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 +444,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 +575,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 +592,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 +691,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
@@ -634,7 +718,8 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 index: idx,
                 rowLocator: stableRow,
                 rowIndex,
-                barrier: smart._barrier
+                barrier: smart._barrier,
+                allowMissingCell: !!mapper,
             });
             if (navigatedCell) {
                 targetCell = navigatedCell;
@@ -654,15 +739,29 @@ 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';
-            if (isCellLoading && await isCellLoading(targetCell, col, smart)) {
-                if (cellLoadingTimeout !== undefined) {
+            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) {
+                let loading = await isCellLoading(targetCell, col, smart);
+                // First-paint race: the cell node can attach a tick before the loading
+                // indicator mounts. A single false-negative then reads "" and skips
+                // onCellLoadingTimeout. Only grace when the cell still looks empty.
+                if (!loading && cellLoadingTimeout !== undefined && cellLoadingTimeout > 0) {
+                    const peek = await targetCell.evaluate((el) => (el.textContent || '').trim()).catch(() => '');
+                    if (peek === '') {
+                        const graceDeadline = Date.now() + Math.min(250, cellLoadingTimeout);
+                        while (!loading && Date.now() < graceDeadline) {
+                            await page.waitForTimeout(25);
+                            loading = await isCellLoading(targetCell, col, smart);
+                        }
+                    }
+                }
+                if (loading && cellLoadingTimeout !== undefined) {
                     (0, debugUtils_1.logDebug)(config, 'verbose', `toJSON: cell "${col}" — waiting up to ${cellLoadingTimeout}ms`);
                     const deadline = Date.now() + cellLoadingTimeout;
                     let cellResolved = !(await isCellLoading(targetCell, col, smart)); // immediate check (handles timeout=0)
@@ -699,7 +798,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);
@@ -775,6 +874,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         (0, debugUtils_1.logDebug)(config, 'info', 'Row fill complete');
     };
     smart.bringIntoView = async () => {
+        var _a;
         if (rowIndex === undefined) {
             (0, debugUtils_1.logDebug)(config, 'info', 'bringIntoView called on a row with unknown rowIndex (e.g. from getRow()). ' +
                 'Page navigation and scrolling will proceed, but virtual-scroll keyboard navigation will be skipped. ' +
@@ -786,7 +886,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
             const primitives = config.strategies.pagination;
             const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
             const getCurrent = () => parentTable.currentPageIndex;
-            const setCurrent = (n) => { parentTable.currentPageIndex = n; };
+            const setCurrent = (n) => { (0, pageIndex_1.setCurrentPageIndex)(parentTable, n); };
             if (primitives.goToPage) {
                 (0, debugUtils_1.logDebug)(config, 'info', `bringIntoView: Navigating to page ${tablePageIndex} (goToPage retry loop)`);
                 await (0, paginationPath_1.executeNavigationWithGoToPageRetry)(tablePageIndex, primitives, context, getCurrent, setCurrent);
@@ -811,7 +911,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                         if (!ok)
                             throw new Error(`bringIntoView: goNext failed before reaching page ${tablePageIndex}.`);
                     }
-                    parentTable.currentPageIndex = tablePageIndex;
+                    (0, pageIndex_1.setCurrentPageIndex)(parentTable, tablePageIndex);
                 }
                 else {
                     (0, debugUtils_1.logDebug)(config, 'error', `Cannot bring row on page ${tablePageIndex} into view. No backwards pagination strategies (goToPage, goPrevious, goPreviousBulk, or goToFirst+goNext) provided.`);
@@ -821,8 +921,20 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         }
         // Delay after pagination/finding before scrolling
         await (0, debugUtils_1.debugDelay)(config, 'findRow');
-        // Scroll row into view using Playwright's built-in method
-        await rowLocator.scrollIntoViewIfNeeded();
+        // Prefer viewport.scrollToRow when configured (#430). scrollIntoViewIfNeeded adjusts
+        // both axes and can evict sibling rows on recycling virtualizers.
+        const viewport = config.strategies.viewport;
+        const logicalRowIndex = (viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow) && renderWindowPosition
+            ? (_a = (await (0, rowResolution_1.resolveLogicalRowIndex)(rowLocator, config, () => undefined))) === null || _a === void 0 ? void 0 : _a.index
+            : rowIndex;
+        if ((viewport === null || viewport === void 0 ? void 0 : viewport.scrollToRow) && typeof logicalRowIndex === 'number') {
+            const page = rootLocator.page();
+            (0, debugUtils_1.logDebug)(config, 'verbose', `bringIntoView: viewport.scrollToRow(${logicalRowIndex})`);
+            await viewport.scrollToRow({ root: rootLocator, config, page, resolve, getHeaders: parentTable === null || parentTable === void 0 ? void 0 : parentTable.getHeaders }, logicalRowIndex);
+        }
+        else {
+            await rowLocator.scrollIntoViewIfNeeded();
+        }
     };
     return 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;
+};

package/dist/strategies/contentReady.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentReadyStrategies = void 0;
+exports.ContentReadyStrategies = {
+    /**
+     * Polls the row's text content until two consecutive reads match.
+     */
+    textStable: (options = {}) => {
+        var _a, _b;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : 500;
+        const interval = (_b = options.interval) !== null && _b !== void 0 ? _b : 50;
+        return async (row, page) => {
+            const deadline = Date.now() + timeout;
+            const remaining = () => Math.max(0, deadline - Date.now());
+            let prev = await row.innerText({ timeout: remaining() || timeout });
+            while (remaining() > 0) {
+                await page.waitForTimeout(Math.min(interval, remaining()));
+                if (remaining() <= 0)
+                    break;
+                const cur = await row.innerText({ timeout: remaining() });
+                if (cur === prev)
+                    return;
+                prev = cur;
+            }
+        };
+    },
+    /**
+     * 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 = {}) => {
+        var _a, _b;
+        const timeout = (_a = options.timeout) !== null && _a !== void 0 ? _a : 500;
+        const quietPeriod = (_b = options.quietPeriod) !== null && _b !== void 0 ? _b : 100;
+        return async (row) => {
+            await row.evaluate((el, opts) => {
+                return new Promise((resolve) => {
+                    let quietTimer;
+                    let deadlineTimer;
+                    const done = () => {
+                        clearTimeout(quietTimer);
+                        clearTimeout(deadlineTimer);
+                        observer.disconnect();
+                        resolve();
+                    };
+                    const observer = new MutationObserver(() => {
+                        clearTimeout(quietTimer);
+                        quietTimer = setTimeout(done, opts.quietPeriod);
+                    });
+                    observer.observe(el, {
+                        childList: true,
+                        subtree: true,
+                        characterData: true,
+                    });
+                    quietTimer = setTimeout(done, opts.quietPeriod);
+                    deadlineTimer = setTimeout(done, opts.timeout);
+                });
+            }, { timeout, quietPeriod });
+        };
+    },
+};

package/dist/strategies/filter.d.ts

@@ -2,12 +2,8 @@ import type { FilterStrategy } from '../types';
 /**
  * Example filter strategies.
  * - default: small convenience wrapper that mirrors the engine's default behavior.
- * - spy(factory): returns a strategy that marks `calledRef.called = true` when invoked.
  */
 export declare const FilterStrategies: {
     default: FilterStrategy;
-    spy: (calledRef?: {
-        called?: boolean;
-    }) => FilterStrategy;
 };
 export type { FilterStrategy } from '../types';

package/dist/strategies/filter.js

@@ -4,7 +4,6 @@ exports.FilterStrategies = void 0;
 /**
  * Example filter strategies.
  * - default: small convenience wrapper that mirrors the engine's default behavior.
- * - spy(factory): returns a strategy that marks `calledRef.called = true` when invoked.
  */
 exports.FilterStrategies = {
     default: {
@@ -20,19 +19,4 @@ exports.FilterStrategies = {
             return rows.filter({ has: targetCell.getByText(textVal, { exact: true }) });
         }
     },
-    spy: (calledRef = {}) => ({
-        apply({ rows, filter, colIndex, tableContext }) {
-            calledRef.called = true;
-            // Delegate to default behaviour for actual filtering
-            const page = tableContext.page;
-            const resolve = tableContext.resolve;
-            const cellTemplate = resolve(tableContext.config.cellSelector, page);
-            const targetCell = cellTemplate.nth(colIndex);
-            if (typeof filter.value === 'function') {
-                return rows.filter({ has: filter.value(targetCell) });
-            }
-            const textVal = typeof filter.value === 'number' ? String(filter.value) : filter.value;
-            return rows.filter({ has: targetCell.getByText(textVal, { exact: true }) });
-        }
-    }),
 };

package/dist/strategies/headers.d.ts

@@ -13,6 +13,11 @@ export declare const HeaderStrategies: {
     /**
      * Physically scrolls the table horizontally to force virtualized columns to mount,
      * collecting their names along the way.
+     *
+     * **Requires `selector`** — the CSS selector for the horizontal scroll container
+     * (e.g. `.dvn-scroller` for Glide, `.rdg-viewport` for RDG). Framework class names
+     * belong in presets / your config, not in this generic factory. Without `selector`,
+     * only currently visible headers are returned (no scrolling).
      */
     horizontalScroll: (options?: {
         limit?: number;

package/dist/strategies/headers.js

@@ -22,6 +22,11 @@ exports.HeaderStrategies = {
     /**
      * Physically scrolls the table horizontally to force virtualized columns to mount,
      * collecting their names along the way.
+     *
+     * **Requires `selector`** — the CSS selector for the horizontal scroll container
+     * (e.g. `.dvn-scroller` for Glide, `.rdg-viewport` for RDG). Framework class names
+     * belong in presets / your config, not in this generic factory. Without `selector`,
+     * only currently visible headers are returned (no scrolling).
      */
     horizontalScroll: (options) => {
         return async (context) => {
@@ -37,19 +42,22 @@ exports.HeaderStrategies = {
             };
             let currentHeaders = await getVisible();
             currentHeaders.forEach(h => collectedHeaders.add(h));
-            const scrollerHandle = await root.evaluateHandle((el, selector) => {
-                if (selector && el.matches(selector))
+            const selector = options === null || options === void 0 ? void 0 : options.selector;
+            if (!selector) {
+                (0, debugUtils_1.logDebug)(config, 'info', 'HeaderStrategies.horizontalScroll: no selector provided — returning visible headers only. Pass { selector } for the scroll container (e.g. ".dvn-scroller").');
+                return Array.from(collectedHeaders);
+            }
+            const scrollerHandle = await root.evaluateHandle((el, sel) => {
+                if (el.matches(sel))
                     return el;
-                // Try finding common scrollable containers or fallback to root
-                const effectiveSelector = selector || '.dvn-scroller, .rdg-viewport, [role="grid"]';
-                const ancestor = el.closest(effectiveSelector);
+                const ancestor = el.closest(sel);
                 if (ancestor)
                     return ancestor;
-                const child = el.querySelector(effectiveSelector);
+                const child = el.querySelector(sel);
                 if (child)
                     return child;
-                return el;
-            }, options === null || options === void 0 ? void 0 : options.selector);
+                return null;
+            }, selector);
             const isScrollerFound = await scrollerHandle.evaluate(el => !!el);
             if (isScrollerFound) {
                 await scrollerHandle.evaluate(el => el.scrollLeft = 0);
@@ -71,7 +79,7 @@ exports.HeaderStrategies = {
                 }
             }
             else {
-                (0, debugUtils_1.logDebug)(config, 'info', "HeaderStrategies.horizontalScroll: Could not find scroller. Returning visible headers.");
+                (0, debugUtils_1.logDebug)(config, 'info', `HeaderStrategies.horizontalScroll: Could not find scroller matching "${selector}". Returning visible headers.`);
             }
             if (isScrollerFound) {
                 await scrollerHandle.evaluate(el => el.scrollLeft = 0);