@rickcedwhat/playwright-smart-table 6.1.1 → 6.2.0

package/README.md

@@ -79,6 +79,8 @@ const allActive = await table.findRows({ Status: 'Active' });
 ## Key Features
 
 - 🎯 **Smart Locators** - Find rows by content, not position
+- 🧠 **Fuzzy Matching** - Smart suggestions for typos (e.g., incorrectly typed "Firstname" suggests "First Name" in error messages)
+- ⚡ **Smart Initialization** - Handles loading states and dynamic headers automatically
 - 📄 **Auto-Pagination** - Search across all pages automatically
 - 🔍 **Column-Aware Access** - Access cells by column name
 - 🛠️ **Debug Mode** - Visual debugging with slow motion and logging

package/dist/engine/rowFinder.d.ts

@@ -0,0 +1,26 @@
+import type { Locator, Page } from '@playwright/test';
+import { FinalTableConfig, Selector, SmartRow } from '../types';
+import { FilterEngine } from '../filterEngine';
+import { TableMapper } from './tableMapper';
+import { SmartRowArray } from '../utils/smartRowArray';
+export declare class RowFinder<T = any> {
+    private rootLocator;
+    private config;
+    private filterEngine;
+    private tableMapper;
+    private makeSmartRow;
+    private resolve;
+    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator, filterEngine: FilterEngine, tableMapper: TableMapper, makeSmartRow: (loc: Locator, map: Map<string, number>, index: number) => SmartRow<T>);
+    private log;
+    findRow(filters: Record<string, string | RegExp | number>, options?: {
+        exact?: boolean;
+        maxPages?: number;
+    }): Promise<SmartRow<T>>;
+    findRows<R extends {
+        asJSON?: boolean;
+    }>(filters: Partial<T> | Record<string, string | RegExp | number>, options?: {
+        exact?: boolean;
+        maxPages?: number;
+    } & R): Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRowArray<T>>;
+    private findRowLocator;
+}

package/dist/engine/rowFinder.js

@@ -0,0 +1,161 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RowFinder = void 0;
+const debugUtils_1 = require("../utils/debugUtils");
+const smartRowArray_1 = require("../utils/smartRowArray");
+const validation_1 = require("../strategies/validation");
+class RowFinder {
+    constructor(rootLocator, config, resolve, filterEngine, tableMapper, makeSmartRow) {
+        this.rootLocator = rootLocator;
+        this.config = config;
+        this.filterEngine = filterEngine;
+        this.tableMapper = tableMapper;
+        this.makeSmartRow = makeSmartRow;
+        this.resolve = resolve;
+    }
+    log(msg) {
+        (0, debugUtils_1.logDebug)(this.config, 'verbose', msg);
+    }
+    findRow(filters_1) {
+        return __awaiter(this, arguments, void 0, function* (filters, options = {}) {
+            (0, debugUtils_1.logDebug)(this.config, 'info', 'Searching for row', filters);
+            yield this.tableMapper.getMap();
+            const rowLocator = yield this.findRowLocator(filters, options);
+            if (rowLocator) {
+                (0, debugUtils_1.logDebug)(this.config, 'info', 'Row found');
+                yield (0, debugUtils_1.debugDelay)(this.config, 'findRow');
+                return this.makeSmartRow(rowLocator, yield this.tableMapper.getMap(), 0);
+            }
+            (0, debugUtils_1.logDebug)(this.config, 'error', 'Row not found', filters);
+            yield (0, debugUtils_1.debugDelay)(this.config, 'findRow');
+            const sentinel = this.resolve(this.config.rowSelector, this.rootLocator)
+                .filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
+            return this.makeSmartRow(sentinel, yield this.tableMapper.getMap(), 0);
+        });
+    }
+    findRows(filters, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const map = yield this.tableMapper.getMap();
+            const allRows = [];
+            const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
+            let pageCount = 0;
+            const collectMatches = () => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                let rowLocators = this.resolve(this.config.rowSelector, this.rootLocator);
+                rowLocators = this.filterEngine.applyFilters(rowLocators, filters, map, (_a = options === null || options === void 0 ? void 0 : options.exact) !== null && _a !== void 0 ? _a : false, this.rootLocator.page());
+                const currentRows = yield rowLocators.all();
+                const isRowLoading = (_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isRowLoading;
+                for (let i = 0; i < currentRows.length; i++) {
+                    const smartRow = this.makeSmartRow(currentRows[i], map, i);
+                    if (isRowLoading && (yield isRowLoading(smartRow)))
+                        continue;
+                    allRows.push(smartRow);
+                }
+            });
+            // Scan first page
+            yield collectMatches();
+            // Pagination Loop
+            while (pageCount < effectiveMaxPages && this.config.strategies.pagination) {
+                // Check if pagination needed? findRows assumes we want ALL matches across maxPages.
+                // If explicit maxPages is set, we paginate. If global maxPages is 1 (default), we stop.
+                // Wait, loop condition `pageCount < effectiveMaxPages`. If maxPages=1, 0 < 1 is true.
+                // We paginate AFTER first scan.
+                // If maxPages=1, we should NOT paginate.
+                if (effectiveMaxPages <= 1)
+                    break;
+                const context = {
+                    root: this.rootLocator,
+                    config: this.config,
+                    resolve: this.resolve,
+                    page: this.rootLocator.page()
+                };
+                const paginationResult = yield this.config.strategies.pagination(context);
+                const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
+                if (!didPaginate)
+                    break;
+                pageCount++;
+                yield collectMatches();
+            }
+            if (options === null || options === void 0 ? void 0 : options.asJSON) {
+                return Promise.all(allRows.map(r => r.toJSON()));
+            }
+            return (0, smartRowArray_1.createSmartRowArray)(allRows);
+        });
+    }
+    findRowLocator(filters_1) {
+        return __awaiter(this, arguments, void 0, function* (filters, options = {}) {
+            var _a, _b;
+            const map = yield this.tableMapper.getMap();
+            const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : this.config.maxPages;
+            let currentPage = 1;
+            this.log(`Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
+            while (true) {
+                // Check Loading
+                if ((_b = this.config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isTableLoading) {
+                    const isLoading = yield this.config.strategies.loading.isTableLoading({
+                        root: this.rootLocator,
+                        config: this.config,
+                        page: this.rootLocator.page(),
+                        resolve: this.resolve
+                    });
+                    if (isLoading) {
+                        this.log('Table is loading... waiting');
+                        yield this.rootLocator.page().waitForTimeout(200);
+                        continue;
+                    }
+                }
+                const allRows = this.resolve(this.config.rowSelector, this.rootLocator);
+                const matchedRows = this.filterEngine.applyFilters(allRows, filters, map, options.exact || false, this.rootLocator.page());
+                const count = yield matchedRows.count();
+                this.log(`Page ${currentPage}: Found ${count} matches.`);
+                if (count > 1) {
+                    const sampleData = [];
+                    try {
+                        const firstFewRows = yield matchedRows.all();
+                        const sampleCount = Math.min(firstFewRows.length, 3);
+                        for (let i = 0; i < sampleCount; i++) {
+                            const rowData = yield this.makeSmartRow(firstFewRows[i], map, 0).toJSON();
+                            sampleData.push(JSON.stringify(rowData));
+                        }
+                    }
+                    catch (e) { }
+                    const sampleMsg = sampleData.length > 0 ? `\nSample matching rows:\n${sampleData.map((d, i) => `  ${i + 1}. ${d}`).join('\n')}` : '';
+                    throw new Error(`Ambiguous Row: Found ${count} rows matching ${JSON.stringify(filters)} on page ${currentPage}. ` +
+                        `Expected exactly one match. Try adding more filters to make your query unique.${sampleMsg}`);
+                }
+                if (count === 1)
+                    return matchedRows.first();
+                if (currentPage < effectiveMaxPages) {
+                    this.log(`Page ${currentPage}: Not found. Attempting pagination...`);
+                    const context = {
+                        root: this.rootLocator,
+                        config: this.config,
+                        resolve: this.resolve,
+                        page: this.rootLocator.page()
+                    };
+                    const paginationResult = yield this.config.strategies.pagination(context);
+                    const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
+                    if (didLoadMore) {
+                        currentPage++;
+                        continue;
+                    }
+                    else {
+                        this.log(`Page ${currentPage}: Pagination failed (end of data).`);
+                    }
+                }
+                return null;
+            }
+        });
+    }
+}
+exports.RowFinder = RowFinder;

package/dist/engine/tableMapper.d.ts

@@ -0,0 +1,16 @@
+import type { Locator, Page } from '@playwright/test';
+import { FinalTableConfig, Selector } from '../types';
+export declare class TableMapper {
+    private _headerMap;
+    private config;
+    private rootLocator;
+    private resolve;
+    constructor(rootLocator: Locator, config: FinalTableConfig, resolve: (item: Selector, parent: Locator | Page) => Locator);
+    private log;
+    getMap(timeout?: number): Promise<Map<string, number>>;
+    remapHeaders(): Promise<void>;
+    getMapSync(): Map<string, number> | null;
+    isInitialized(): boolean;
+    clear(): void;
+    private processHeaders;
+}

package/dist/engine/tableMapper.js

@@ -0,0 +1,136 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TableMapper = void 0;
+const headers_1 = require("../strategies/headers");
+const debugUtils_1 = require("../utils/debugUtils");
+class TableMapper {
+    constructor(rootLocator, config, resolve) {
+        this._headerMap = null;
+        this.rootLocator = rootLocator;
+        this.config = config;
+        this.resolve = resolve;
+    }
+    log(msg) {
+        (0, debugUtils_1.logDebug)(this.config, 'verbose', msg);
+    }
+    getMap(timeout) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (this._headerMap)
+                return this._headerMap;
+            this.log('Mapping headers...');
+            const headerTimeout = timeout !== null && timeout !== void 0 ? timeout : 3000;
+            const startTime = Date.now();
+            if (this.config.autoScroll) {
+                try {
+                    yield this.rootLocator.scrollIntoViewIfNeeded({ timeout: 1000 });
+                }
+                catch (e) { }
+            }
+            const headerLoc = this.resolve(this.config.headerSelector, this.rootLocator);
+            const strategy = this.config.strategies.header || headers_1.HeaderStrategies.visible;
+            const context = {
+                root: this.rootLocator,
+                config: this.config,
+                page: this.rootLocator.page(),
+                resolve: this.resolve
+            };
+            let lastError = null;
+            while (Date.now() - startTime < headerTimeout) {
+                // 1. Wait for visibility
+                try {
+                    yield headerLoc.first().waitFor({ state: 'visible', timeout: 200 });
+                }
+                catch (e) {
+                    // Continue to check existing/loading state even if not strictly "visible" yet
+                }
+                // 2. Check Smart Loading State
+                if ((_a = this.config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isHeaderLoading) {
+                    const isStable = !(yield this.config.strategies.loading.isHeaderLoading(context));
+                    if (!isStable) {
+                        this.log('Headers are loading/unstable... waiting');
+                        yield new Promise(r => setTimeout(r, 100));
+                        continue;
+                    }
+                }
+                // 3. Attempt Scan
+                try {
+                    const rawHeaders = yield strategy(context);
+                    const entries = yield this.processHeaders(rawHeaders);
+                    // Success
+                    this._headerMap = new Map(entries);
+                    this.log(`Mapped ${entries.length} columns: ${JSON.stringify(entries.map(e => e[0]))}`);
+                    return this._headerMap;
+                }
+                catch (e) {
+                    lastError = e;
+                    this.log(`Header mapping failed (retrying): ${e.message}`);
+                    yield new Promise(r => setTimeout(r, 100));
+                }
+            }
+            throw lastError || new Error(`Timed out waiting for headers after ${headerTimeout}ms`);
+        });
+    }
+    remapHeaders() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this._headerMap = null;
+            yield this.getMap();
+        });
+    }
+    getMapSync() {
+        return this._headerMap;
+    }
+    isInitialized() {
+        return this._headerMap !== null;
+    }
+    clear() {
+        this._headerMap = null;
+    }
+    processHeaders(rawHeaders) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const seenHeaders = new Set();
+            const entries = [];
+            for (let i = 0; i < rawHeaders.length; i++) {
+                let text = rawHeaders[i].trim() || `__col_${i}`;
+                if (this.config.headerTransformer) {
+                    text = yield this.config.headerTransformer({
+                        text,
+                        index: i,
+                        locator: this.rootLocator.locator(this.config.headerSelector).nth(i),
+                        seenHeaders
+                    });
+                }
+                entries.push([text, i]);
+                seenHeaders.add(text);
+            }
+            // Validation: Check for empty table
+            if (entries.length === 0) {
+                throw new Error(`Initialization Error: No columns found using selector "${this.config.headerSelector}". Check your selector or ensure the table is visible.`);
+            }
+            // Validation: Check for duplicates
+            const seen = new Set();
+            const duplicates = new Set();
+            for (const [name] of entries) {
+                if (seen.has(name)) {
+                    duplicates.add(name);
+                }
+                seen.add(name);
+            }
+            if (duplicates.size > 0) {
+                const dupList = Array.from(duplicates).map(d => `"${d}"`).join(', ');
+                throw new Error(`Initialization Error: Duplicate column names found: ${dupList}. Use 'headerTransformer' to rename duplicate columns.`);
+            }
+            return entries;
+        });
+    }
+}
+exports.TableMapper = TableMapper;

package/dist/strategies/index.d.ts

@@ -50,5 +50,9 @@ export declare const Strategies: {
             hasEmptyCells: () => (row: import("..").SmartRow) => Promise<boolean>;
             never: () => Promise<boolean>;
         };
+        Headers: {
+            stable: (duration?: number) => (context: import("..").TableContext) => Promise<boolean>;
+            never: () => Promise<boolean>;
+        };
     };
 };

package/dist/strategies/loading.d.ts

@@ -45,4 +45,18 @@ export declare const LoadingStrategies: {
          */
         never: () => Promise<boolean>;
     };
+    /**
+     * Strategies for detecting if headers are loading/stable.
+     */
+    Headers: {
+        /**
+         * Checks if the headers are stable (count and text) for a specified duration.
+         * @param duration Duration in ms for headers to remain unchanged to be considered stable (default: 200).
+         */
+        stable: (duration?: number) => (context: TableContext) => Promise<boolean>;
+        /**
+         * Assume headers are never loading (immediate snapshot).
+         */
+        never: () => Promise<boolean>;
+    };
 };

package/dist/strategies/loading.js

@@ -78,5 +78,36 @@ exports.LoadingStrategies = {
          * Assume row is never loading (default).
          */
         never: () => __awaiter(void 0, void 0, void 0, function* () { return false; })
+    },
+    /**
+     * Strategies for detecting if headers are loading/stable.
+     */
+    Headers: {
+        /**
+         * Checks if the headers are stable (count and text) for a specified duration.
+         * @param duration Duration in ms for headers to remain unchanged to be considered stable (default: 200).
+         */
+        stable: (duration = 200) => (context) => __awaiter(void 0, void 0, void 0, function* () {
+            const { config, resolve, root } = context;
+            const getHeaderTexts = () => __awaiter(void 0, void 0, void 0, function* () {
+                const headers = yield resolve(config.headerSelector, root).all();
+                return Promise.all(headers.map(h => h.innerText()));
+            });
+            const initial = yield getHeaderTexts();
+            // Wait for duration
+            yield context.page.waitForTimeout(duration);
+            const current = yield getHeaderTexts();
+            if (initial.length !== current.length)
+                return true; // Count changed, still loading
+            for (let i = 0; i < initial.length; i++) {
+                if (initial[i] !== current[i])
+                    return true; // Content changed, still loading
+            }
+            return false; // Stable
+        }),
+        /**
+         * Assume headers are never loading (immediate snapshot).
+         */
+        never: () => __awaiter(void 0, void 0, void 0, function* () { return false; })
     }
 };

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.js
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext {\n  root: Locator;\n  config: FinalTableConfig;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport type { HeaderStrategy } from './strategies/headers';\nexport type { CellNavigationStrategy } from './strategies/columns';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: string | RegExp | number };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Strategy for navigating to specific cells (row + column) */\n  cellNavigation?: CellNavigationStrategy;\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /** Custom helper to check if a table is fully loaded/ready */\n  isTableLoaded?: (args: TableContext) => Promise<boolean>;\n  /** Custom helper to check if a row is fully loaded/ready */\n  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;\n  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */\n  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;\n  /** Strategy for detecting loading states */\n  loading?: LoadingStrategy;\n}\n\n/**\n * Configuration options for useTable.\n */\nexport interface TableConfig {\n  /** Selector for the table headers */\n  headerSelector?: string;\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n}\n\nexport interface FinalTableConfig extends TableConfig {\n  headerSelector: string;\n  rowSelector: string;\n  cellSelector: string;\n  maxPages: number;\n  autoScroll: boolean;\n  debug?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\n/**\n * Options for generateConfigPrompt\n */\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  /**\n   * Include TypeScript type definitions in the prompt\n   * @default true\n   */\n  includeTypes?: boolean;\n}\n\nexport interface TableResult<T = any> {\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match, max pages, and asJSON\n   */\n  findRows: <R extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * Returns a SmartRowArray which extends Array with a toJSON() helper method.\n   * @param options - Filter options\n   */\n  getRows: (options?: { filter?: Record<string, any>, exact?: boolean }) => Promise<SmartRowArray>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Scans a specific column across all pages and returns the values.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Iterates through paginated table data, calling the callback for each iteration.\n   * Callback return values are automatically appended to allData, which is returned.\n   */\n  iterateThroughTable: <T = any>(\n    callback: (context: {\n      index: number;\n      isFirst: boolean;\n      isLast: boolean;\n      rows: SmartRowArray;\n      allData: T[];\n      table: RestrictedTableResult;\n      batchInfo?: {\n        startIndex: number;\n        endIndex: number;\n        size: number;\n      };\n\n    }) => T | T[] | Promise<T | T[]>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      batchSize?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      beforeFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      afterLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      /**\n       * If true, flattens array results from callback into the main data array.\n       * If false (default), pushes the return value as-is (preserves batching/arrays).\n       */\n      autoFlatten?: boolean;\n    }\n  ) => Promise<T[]>;\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   */\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n}\n\n/**\n * Restricted table result that excludes methods that shouldn't be called during iteration.\n */\nexport type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;\n";
+export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\n/**\n * Debug configuration for development and troubleshooting\n */\nexport type DebugConfig = {\n  /**\n   * Slow down operations for debugging\n   * - number: Apply same delay to all operations (ms)\n   * - object: Granular delays per operation type\n   */\n  slow?: number | {\n    pagination?: number;\n    getCell?: number;\n    findRow?: number;\n    default?: number;\n  };\n  /**\n   * Log level for debug output\n   * - 'verbose': All logs (verbose, info, error)\n   * - 'info': Info and error logs only\n   * - 'error': Error logs only\n   * - 'none': No logs\n   */\n  logLevel?: 'verbose' | 'info' | 'error' | 'none';\n};\n\nexport interface TableContext {\n  root: Locator;\n  config: FinalTableConfig;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport type { HeaderStrategy } from './strategies/headers';\nexport type { CellNavigationStrategy } from './strategies/columns';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: string | RegExp | number };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Strategy to check if the table or rows are loading.\n */\nexport interface LoadingStrategy {\n  isTableLoading?: (context: TableContext) => Promise<boolean>;\n  isRowLoading?: (row: SmartRow) => Promise<boolean>;\n  isHeaderLoading?: (context: TableContext) => Promise<boolean>;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Strategy for navigating to specific cells (row + column) */\n  cellNavigation?: CellNavigationStrategy;\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Strategy for deduplicating rows during iteration/scrolling */\n  dedupe?: DedupeStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n  /** Custom helper to check if a table is fully loaded/ready */\n  isTableLoaded?: (args: TableContext) => Promise<boolean>;\n  /** Custom helper to check if a row is fully loaded/ready */\n  isRowLoaded?: (args: { row: Locator, index: number }) => Promise<boolean>;\n  /** Custom helper to check if a cell is fully loaded/ready (e.g. for editing) */\n  isCellLoaded?: (args: { cell: Locator, column: string, row: Locator }) => Promise<boolean>;\n  /** Strategy for detecting loading states */\n  loading?: LoadingStrategy;\n}\n\n/**\n * Configuration options for useTable.\n */\nexport interface TableConfig {\n  /** Selector for the table headers */\n  headerSelector?: string;\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Debug options for development and troubleshooting */\n  debug?: DebugConfig;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n}\n\nexport interface FinalTableConfig extends TableConfig {\n  headerSelector: string;\n  rowSelector: string;\n  cellSelector: string;\n  maxPages: number;\n  autoScroll: boolean;\n  debug?: TableConfig['debug'];\n  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\n/**\n * Options for generateConfigPrompt\n */\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  /**\n   * Include TypeScript type definitions in the prompt\n   * @default true\n   */\n  includeTypes?: boolean;\n}\n\nexport interface TableResult<T = any> {\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match, max pages, and asJSON\n   */\n  findRows: <R extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRowArray>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * Returns a SmartRowArray which extends Array with a toJSON() helper method.\n   * @param options - Filter options\n   */\n  getRows: (options?: { filter?: Record<string, any>, exact?: boolean }) => Promise<SmartRowArray>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Scans a specific column across all pages and returns the values.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Iterates through paginated table data, calling the callback for each iteration.\n   * Callback return values are automatically appended to allData, which is returned.\n   */\n  iterateThroughTable: <T = any>(\n    callback: (context: {\n      index: number;\n      isFirst: boolean;\n      isLast: boolean;\n      rows: SmartRowArray;\n      allData: T[];\n      table: RestrictedTableResult;\n      batchInfo?: {\n        startIndex: number;\n        endIndex: number;\n        size: number;\n      };\n\n    }) => T | T[] | Promise<T | T[]>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      batchSize?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      beforeFirst?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;\n      afterLast?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;\n      /**\n       * If true, flattens array results from callback into the main data array.\n       * If false (default), pushes the return value as-is (preserves batching/arrays).\n       */\n      autoFlatten?: boolean;\n    }\n  ) => Promise<T[]>;\n\n  /**\n   * Generate an AI-friendly configuration prompt for debugging.\n   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.\n   */\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n}\n\n/**\n * Restricted table result that excludes methods that shouldn't be called during iteration.\n */\nexport type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;\n";

package/dist/typeContext.js

@@ -216,6 +216,7 @@ export interface FilterStrategy {
 export interface LoadingStrategy {
   isTableLoading?: (context: TableContext) => Promise<boolean>;
   isRowLoading?: (row: SmartRow) => Promise<boolean>;
+  isHeaderLoading?: (context: TableContext) => Promise<boolean>;
 }
 
 /**
@@ -366,7 +367,7 @@ export interface TableResult<T = any> {
   findRows: <R extends { asJSON?: boolean }>(
     filters: Record<string, string | RegExp | number>,
     options?: { exact?: boolean, maxPages?: number } & R
-  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRowArray>;
 
   /**
    * Navigates to a specific column using the configured CellNavigationStrategy.
@@ -441,8 +442,8 @@ export interface TableResult<T = any> {
       batchSize?: number;
       getIsFirst?: (context: { index: number }) => boolean;
       getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;
-      beforeFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
-      afterLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
+      beforeFirst?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;
+      afterLast?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;
       /**
        * If true, flattens array results from callback into the main data array.
        * If false (default), pushes the return value as-is (preserves batching/arrays).

package/dist/types.d.ts

@@ -198,6 +198,7 @@ export interface FilterStrategy {
 export interface LoadingStrategy {
     isTableLoading?: (context: TableContext) => Promise<boolean>;
     isRowLoading?: (row: SmartRow) => Promise<boolean>;
+    isHeaderLoading?: (context: TableContext) => Promise<boolean>;
 }
 /**
  * Organized container for all table interaction strategies.
@@ -354,7 +355,7 @@ export interface TableResult<T = any> {
     }>(filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
         maxPages?: number;
-    } & R) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+    } & R) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRowArray>;
     /**
      * Navigates to a specific column using the configured CellNavigationStrategy.
      */
@@ -432,12 +433,12 @@ export interface TableResult<T = any> {
         }) => boolean;
         beforeFirst?: (context: {
             index: number;
-            rows: SmartRow[];
+            rows: SmartRowArray;
             allData: any[];
         }) => void | Promise<void>;
         afterLast?: (context: {
             index: number;
-            rows: SmartRow[];
+            rows: SmartRowArray;
             allData: any[];
         }) => void | Promise<void>;
         /**

package/dist/useTable.d.ts

@@ -34,6 +34,10 @@ export declare const LoadingStrategies: {
         hasEmptyCells: () => (row: SmartRowType) => Promise<boolean>;
         never: () => Promise<boolean>;
     };
+    Headers: {
+        stable: (duration?: number) => (context: TableContext) => Promise<boolean>;
+        never: () => Promise<boolean>;
+    };
 };
 export declare const SortingStrategies: {
     AriaSort: () => import("./types").SortingStrategy;

package/dist/useTable.js

@@ -23,11 +23,12 @@ const columns_1 = require("./strategies/columns");
 Object.defineProperty(exports, "CellNavigationStrategies", { enumerable: true, get: function () { return columns_1.CellNavigationStrategies; } });
 const smartRow_1 = require("./smartRow");
 const filterEngine_1 = require("./filterEngine");
+const tableMapper_1 = require("./engine/tableMapper");
+const rowFinder_1 = require("./engine/rowFinder");
 const resolution_1 = require("./strategies/resolution");
 Object.defineProperty(exports, "ResolutionStrategies", { enumerable: true, get: function () { return resolution_1.ResolutionStrategies; } });
 const strategies_1 = require("./strategies");
 Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
-const validation_1 = require("./strategies/validation");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
 /**
@@ -43,6 +44,9 @@ const useTable = (rootLocator, configOptions = {}) => {
         header: headers_1.HeaderStrategies.visible,
         cellNavigation: columns_1.CellNavigationStrategies.default,
         pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }),
+        loading: {
+            isHeaderLoading: loading_1.LoadingStrategies.Headers.stable(200)
+        }
     };
     const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "thead th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text }) => text, autoScroll: true, onReset: () => __awaiter(void 0, void 0, void 0, function* () { }) }, configOptions), { strategies: Object.assign(Object.assign({}, defaultStrategies), configOptions.strategies) });
     const resolve = (item, parent) => {
@@ -53,16 +57,13 @@ const useTable = (rootLocator, configOptions = {}) => {
         return item;
     };
     // Internal State
-    let _headerMap = null;
     let _hasPaginated = false;
-    let _isInitialized = false;
     // Helpers
     const log = (msg) => {
-        (0, debugUtils_1.logDebug)(config, 'verbose', msg); // Legacy(`🔎 [SmartTable Debug] ${msg}`);
+        (0, debugUtils_1.logDebug)(config, 'verbose', msg);
     };
     const _createColumnError = (colName, map, context) => {
         const availableColumns = Array.from(map.keys());
-        // Use Suggestion Logic from ResolutionStrategy (if we had a fuzzy one, for now manual suggest)
         const lowerCol = colName.toLowerCase();
         const suggestions = availableColumns.filter(col => col.toLowerCase().includes(lowerCol) ||
             lowerCol.includes(col.toLowerCase()) ||
@@ -80,138 +81,16 @@ const useTable = (rootLocator, configOptions = {}) => {
         const contextMsg = context ? ` (${context})` : '';
         return new Error(`Column "${colName}" not found${contextMsg}${suggestion}`);
     };
-    const _getMap = (timeout) => __awaiter(void 0, void 0, void 0, function* () {
-        if (_headerMap)
-            return _headerMap;
-        log('Mapping headers...');
-        const headerTimeout = timeout !== null && timeout !== void 0 ? timeout : 3000;
-        if (config.autoScroll) {
-            try {
-                yield rootLocator.scrollIntoViewIfNeeded({ timeout: 1000 });
-            }
-            catch (e) { }
-        }
-        const headerLoc = resolve(config.headerSelector, rootLocator);
-        try {
-            yield headerLoc.first().waitFor({ state: 'visible', timeout: headerTimeout });
-        }
-        catch (e) { /* Ignore hydration */ }
-        const strategy = config.strategies.header || headers_1.HeaderStrategies.visible;
-        const context = {
-            root: rootLocator,
-            config: config,
-            page: rootLocator.page(),
-            resolve: resolve
-        };
-        const rawHeaders = yield strategy(context);
-        const seenHeaders = new Set();
-        const entries = [];
-        for (let i = 0; i < rawHeaders.length; i++) {
-            let text = rawHeaders[i].trim() || `__col_${i}`;
-            if (config.headerTransformer) {
-                text = yield config.headerTransformer({
-                    text,
-                    index: i,
-                    locator: rootLocator.locator(config.headerSelector).nth(i),
-                    seenHeaders
-                });
-            }
-            entries.push([text, i]);
-            seenHeaders.add(text);
-        }
-        // Validation: Check for empty table
-        if (entries.length === 0) {
-            throw new Error(`Initialization Error: No columns found using selector "${config.headerSelector}". Check your selector or ensure the table is visible.`);
-        }
-        // Validation: Check for duplicates
-        const seen = new Set();
-        const duplicates = new Set();
-        for (const [name] of entries) {
-            if (seen.has(name)) {
-                duplicates.add(name);
-            }
-            seen.add(name);
-        }
-        if (duplicates.size > 0) {
-            const dupList = Array.from(duplicates).map(d => `"${d}"`).join(', ');
-            throw new Error(`Initialization Error: Duplicate column names found: ${dupList}. Use 'headerTransformer' to rename duplicate columns.`);
-        }
-        _headerMap = new Map(entries);
-        log(`Mapped ${entries.length} columns: ${JSON.stringify(entries.map(e => e[0]))}`);
-        return _headerMap;
-    });
+    // Engines
+    const filterEngine = new filterEngine_1.FilterEngine(config, resolve);
+    const tableMapper = new tableMapper_1.TableMapper(rootLocator, config, resolve);
     // Placeholder for the final table object
     let finalTable = null;
-    const filterEngine = new filterEngine_1.FilterEngine(config, resolve);
     // Helper factory
     const _makeSmart = (rowLocator, map, rowIndex) => {
-        // Use the wrapped SmartRow logic
         return (0, smartRow_1.createSmartRow)(rowLocator, map, rowIndex, config, rootLocator, resolve, finalTable);
     };
-    const _findRowLocator = (filters_1, ...args_1) => __awaiter(void 0, [filters_1, ...args_1], void 0, function* (filters, options = {}) {
-        var _a, _b;
-        const map = yield _getMap();
-        const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
-        let currentPage = 1;
-        log(`Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
-        while (true) {
-            // Check for table loading
-            if ((_b = config.strategies.loading) === null || _b === void 0 ? void 0 : _b.isTableLoading) {
-                const isLoading = yield config.strategies.loading.isTableLoading({ root: rootLocator, config, page: rootLocator.page(), resolve });
-                if (isLoading) {
-                    log('Table is loading... waiting');
-                    yield rootLocator.page().waitForTimeout(200);
-                    continue;
-                }
-            }
-            const allRows = resolve(config.rowSelector, rootLocator);
-            // Use FilterEngine
-            const matchedRows = filterEngine.applyFilters(allRows, filters, map, options.exact || false, rootLocator.page());
-            const count = yield matchedRows.count();
-            log(`Page ${currentPage}: Found ${count} matches.`);
-            if (count > 1) {
-                // Sample data logic (simplified for refactor, kept inline or moved to util if needed)
-                const sampleData = [];
-                try {
-                    const firstFewRows = yield matchedRows.all();
-                    const sampleCount = Math.min(firstFewRows.length, 3);
-                    for (let i = 0; i < sampleCount; i++) {
-                        const rowData = yield _makeSmart(firstFewRows[i], map).toJSON();
-                        sampleData.push(JSON.stringify(rowData));
-                    }
-                }
-                catch (e) { }
-                const sampleMsg = sampleData.length > 0 ? `\nSample matching rows:\n${sampleData.map((d, i) => `  ${i + 1}. ${d}`).join('\n')}` : '';
-                throw new Error(`Ambiguous Row: Found ${count} rows matching ${JSON.stringify(filters)} on page ${currentPage}. ` +
-                    `Expected exactly one match. Try adding more filters to make your query unique.${sampleMsg}`);
-            }
-            if (count === 1)
-                return matchedRows.first();
-            if (currentPage < effectiveMaxPages) {
-                log(`Page ${currentPage}: Not found. Attempting pagination...`);
-                const context = {
-                    root: rootLocator,
-                    config: config,
-                    page: rootLocator.page(),
-                    resolve: resolve
-                };
-                const paginationResult = yield config.strategies.pagination(context);
-                const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
-                if (didLoadMore) {
-                    _hasPaginated = true;
-                    currentPage++;
-                    continue;
-                }
-                else {
-                    log(`Page ${currentPage}: Pagination failed (end of data).`);
-                }
-            }
-            if (_hasPaginated) {
-                console.warn(`⚠️ [SmartTable] Row not found. The table has been paginated (Current Page: ${currentPage}). You may need to call 'await table.reset()' if the target row is on a previous page.`);
-            }
-            return null;
-        }
-    });
+    const rowFinder = new rowFinder_1.RowFinder(rootLocator, config, resolve, filterEngine, tableMapper, _makeSmart);
     const _getCleanHtml = (loc) => __awaiter(void 0, void 0, void 0, function* () {
         return loc.evaluate((el) => {
             const clone = el.cloneNode(true);
@@ -247,28 +126,21 @@ const useTable = (rootLocator, configOptions = {}) => {
         console.log(finalPrompt);
     });
     const _ensureInitialized = () => __awaiter(void 0, void 0, void 0, function* () {
-        if (!_isInitialized) {
-            yield _getMap();
-            _isInitialized = true;
-        }
+        yield tableMapper.getMap();
     });
     const result = {
         init: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            if (_isInitialized && _headerMap)
+            if (tableMapper.isInitialized())
                 return result;
             (0, debugUtils_1.warnIfDebugInCI)(config);
             (0, debugUtils_1.logDebug)(config, 'info', 'Initializing table');
-            yield _getMap(options === null || options === void 0 ? void 0 : options.timeout);
-            _isInitialized = true;
-            if (_headerMap) {
-                (0, debugUtils_1.logDebug)(config, 'info', `Table initialized with ${_headerMap.size} columns`, Array.from(_headerMap.keys()));
-                // Trace event removed - redundant with debug logging
-            }
+            const map = yield tableMapper.getMap(options === null || options === void 0 ? void 0 : options.timeout);
+            (0, debugUtils_1.logDebug)(config, 'info', `Table initialized with ${map.size} columns`, Array.from(map.keys()));
             yield (0, debugUtils_1.debugDelay)(config, 'default');
             return result;
         }),
         scrollToColumn: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
-            const map = yield _getMap();
+            const map = yield tableMapper.getMap();
             const idx = map.get(columnName);
             if (idx === undefined)
                 throw _createColumnError(columnName, map);
@@ -282,14 +154,14 @@ const useTable = (rootLocator, configOptions = {}) => {
             });
         }),
         getHeaders: () => __awaiter(void 0, void 0, void 0, function* () {
-            yield _ensureInitialized();
-            return Array.from(_headerMap.keys());
+            const map = yield tableMapper.getMap();
+            return Array.from(map.keys());
         }),
         getHeaderCell: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
-            yield _ensureInitialized();
-            const idx = _headerMap.get(columnName);
+            const map = yield tableMapper.getMap();
+            const idx = map.get(columnName);
             if (idx === undefined)
-                throw _createColumnError(columnName, _headerMap, 'header cell');
+                throw _createColumnError(columnName, map, 'header cell');
             return resolve(config.headerSelector, rootLocator).nth(idx);
         }),
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
@@ -297,22 +169,20 @@ const useTable = (rootLocator, configOptions = {}) => {
             const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
             yield config.onReset(context);
             _hasPaginated = false;
-            _headerMap = null;
-            _isInitialized = false;
+            tableMapper.clear();
             log("Table reset complete.");
         }),
         revalidate: () => __awaiter(void 0, void 0, void 0, function* () {
             log("Revalidating table structure...");
-            _headerMap = null; // Clear the map to force re-scanning
-            yield _getMap(); // Re-scan headers
+            yield tableMapper.remapHeaders();
             log("Table revalidated.");
         }),
         getColumnValues: (column, options) => __awaiter(void 0, void 0, void 0, function* () {
             var _a, _b;
-            yield _ensureInitialized();
-            const colIdx = _headerMap.get(column);
+            const map = yield tableMapper.getMap();
+            const colIdx = map.get(column);
             if (colIdx === undefined)
-                throw _createColumnError(column, _headerMap);
+                throw _createColumnError(column, map);
             const mapper = (_a = options === null || options === void 0 ? void 0 : options.mapper) !== null && _a !== void 0 ? _a : ((c) => c.innerText());
             const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages;
             let currentPage = 1;
@@ -339,103 +209,33 @@ const useTable = (rootLocator, configOptions = {}) => {
             return results;
         }),
         getRow: (filters, options = { exact: false }) => {
-            if (!_isInitialized || !_headerMap)
+            const map = tableMapper.getMapSync();
+            if (!map)
                 throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             const allRows = resolve(config.rowSelector, rootLocator);
-            const matchedRows = filterEngine.applyFilters(allRows, filters, _headerMap, options.exact || false, rootLocator.page());
+            const matchedRows = filterEngine.applyFilters(allRows, filters, map, options.exact || false, rootLocator.page());
             const rowLocator = matchedRows.first();
-            return _makeSmart(rowLocator, _headerMap, 0); // fallback index 0
+            return _makeSmart(rowLocator, map, 0); // fallback index 0
         },
         getRowByIndex: (index, options = {}) => {
-            if (!_isInitialized || !_headerMap)
+            const map = tableMapper.getMapSync();
+            if (!map)
                 throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(index);
-            return _makeSmart(rowLocator, _headerMap, index);
+            return _makeSmart(rowLocator, map, index);
         },
         findRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
-            (0, debugUtils_1.logDebug)(config, 'info', 'Searching for row', filters);
-            yield _ensureInitialized();
-            let row = yield _findRowLocator(filters, options);
-            if (row) {
-                (0, debugUtils_1.logDebug)(config, 'info', 'Row found');
-                yield (0, debugUtils_1.debugDelay)(config, 'findRow');
-                return _makeSmart(row, _headerMap, 0);
-            }
-            (0, debugUtils_1.logDebug)(config, 'error', 'Row not found', filters);
-            yield (0, debugUtils_1.debugDelay)(config, 'findRow');
-            // Return sentinel row
-            row = resolve(config.rowSelector, rootLocator).filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
-            return _makeSmart(row, _headerMap, 0);
+            return rowFinder.findRow(filters, options);
         }),
         getRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a;
-            yield _ensureInitialized();
-            let rowLocators = resolve(config.rowSelector, rootLocator);
-            if (options === null || options === void 0 ? void 0 : options.filter) {
-                rowLocators = filterEngine.applyFilters(rowLocators, options.filter, _headerMap, options.exact || false, rootLocator.page());
-            }
-            const allRowLocs = yield rowLocators.all();
-            const smartRows = [];
-            const isRowLoading = (_a = config.strategies.loading) === null || _a === void 0 ? void 0 : _a.isRowLoading;
-            for (let i = 0; i < allRowLocs.length; i++) {
-                const smartRow = _makeSmart(allRowLocs[i], _headerMap, i);
-                if (isRowLoading) {
-                    const loading = yield isRowLoading(smartRow);
-                    if (loading)
-                        continue;
-                }
-                smartRows.push(smartRow);
-            }
-            return (0, smartRowArray_1.createSmartRowArray)(smartRows);
+            console.warn('DEPRECATED: table.getRows() is deprecated and will be removed in a future version. Use table.findRows() instead.');
+            return rowFinder.findRows((options === null || options === void 0 ? void 0 : options.filter) || {}, Object.assign(Object.assign({}, options), { maxPages: 1 }));
         }),
         findRows: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
-            yield _ensureInitialized();
-            const allRows = [];
-            const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
-            let pageCount = 0;
-            // Collect rows from current page
-            let rowLocators = resolve(config.rowSelector, rootLocator);
-            rowLocators = filterEngine.applyFilters(rowLocators, filters, _headerMap, (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false, rootLocator.page());
-            let currentRows = yield rowLocators.all();
-            const isRowLoading = (_d = config.strategies.loading) === null || _d === void 0 ? void 0 : _d.isRowLoading;
-            for (let i = 0; i < currentRows.length; i++) {
-                const smartRow = _makeSmart(currentRows[i], _headerMap, i);
-                if (isRowLoading && (yield isRowLoading(smartRow)))
-                    continue;
-                allRows.push(smartRow);
-            }
-            // Paginate and collect more rows
-            while (pageCount < effectiveMaxPages && config.strategies.pagination) {
-                const paginationResult = yield config.strategies.pagination({
-                    root: rootLocator,
-                    config,
-                    resolve,
-                    page: rootLocator.page()
-                });
-                const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
-                if (!didPaginate)
-                    break;
-                pageCount++;
-                _hasPaginated = true;
-                // Collect rows from new page
-                rowLocators = resolve(config.rowSelector, rootLocator);
-                rowLocators = filterEngine.applyFilters(rowLocators, filters, _headerMap, (_e = options === null || options === void 0 ? void 0 : options.exact) !== null && _e !== void 0 ? _e : false, rootLocator.page());
-                const newRows = yield rowLocators.all();
-                for (let i = 0; i < newRows.length; i++) {
-                    const smartRow = _makeSmart(newRows[i], _headerMap, i);
-                    if (isRowLoading && (yield isRowLoading(smartRow)))
-                        continue;
-                    allRows.push(smartRow);
-                }
-            }
-            if (options === null || options === void 0 ? void 0 : options.asJSON) {
-                return Promise.all(allRows.map(r => r.toJSON()));
-            }
-            return allRows;
+            return rowFinder.findRows(filters, options);
         }),
         isInitialized: () => {
-            return _isInitialized;
+            return tableMapper.isInitialized();
         },
         sorting: {
             apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
@@ -463,6 +263,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 throw new Error('No pagination strategy provided.');
             yield result.reset();
             yield result.init();
+            const map = tableMapper.getMapSync();
             const restrictedTable = {
                 init: result.init,
                 getHeaders: result.getHeaders,
@@ -497,7 +298,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 const smartRowsArray = [];
                 const isRowLoading = (_f = config.strategies.loading) === null || _f === void 0 ? void 0 : _f.isRowLoading;
                 for (let i = 0; i < rowLocators.length; i++) {
-                    const smartRow = _makeSmart(rowLocators[i], _headerMap, i);
+                    const smartRow = _makeSmart(rowLocators[i], map, i);
                     if (isRowLoading && (yield isRowLoading(smartRow)))
                         continue;
                     smartRowsArray.push(smartRow);
@@ -533,7 +334,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     let isLast = getIsLast({ index: callbackIndex, paginationResult });
                     const isLastDueToMax = index === effectiveMaxIterations - 1;
                     if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
-                        yield options.beforeFirst({ index: callbackIndex, rows: callbackRows, allData });
+                        yield options.beforeFirst({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(callbackRows), allData });
                     }
                     const batchInfo = isBatching ? {
                         startIndex: batchStartIndex,
@@ -565,7 +366,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         finalIsLast = getIsLast({ index: callbackIndex, paginationResult }) || !paginationResult;
                     }
                     if (finalIsLast && (options === null || options === void 0 ? void 0 : options.afterLast)) {
-                        yield options.afterLast({ index: callbackIndex, rows: callbackRows, allData });
+                        yield options.afterLast({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(callbackRows), allData });
                     }
                     if (finalIsLast || !paginationResult) {
                         log(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
@@ -589,7 +390,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         const isFirst = getIsFirst({ index: callbackIndex });
                         const isLast = true;
                         if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
-                            yield options.beforeFirst({ index: callbackIndex, rows: batchRows, allData });
+                            yield options.beforeFirst({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(batchRows), allData });
                         }
                         const batchInfo = {
                             startIndex: batchStartIndex,
@@ -612,7 +413,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                             allData.push(returnValue);
                         }
                         if (options === null || options === void 0 ? void 0 : options.afterLast) {
-                            yield options.afterLast({ index: callbackIndex, rows: batchRows, allData });
+                            yield options.afterLast({ index: callbackIndex, rows: (0, smartRowArray_1.createSmartRowArray)(batchRows), allData });
                         }
                         log(`Pagination failed mid-batch (index: ${index})`);
                         break;

package/dist/utils/stringUtils.js

@@ -18,11 +18,19 @@ function levenshteinDistance(a, b) {
     }
     for (let i = 1; i <= b.length; i++) {
         for (let j = 1; j <= a.length; j++) {
-            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+            const charB = b.charAt(i - 1);
+            const charA = a.charAt(j - 1);
+            if (charB === charA) {
+                // Exact match
                 matrix[i][j] = matrix[i - 1][j - 1];
             }
             else {
-                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                let cost = 1;
+                // If characters match ignoring case, cost is only 0.1 (almost identical)
+                if (charB.toLowerCase() === charA.toLowerCase()) {
+                    cost = 0.1;
+                }
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + cost, // substitution
                 matrix[i][j - 1] + 1, // insertion
                 matrix[i - 1][j] + 1 // deletion
                 );
@@ -36,7 +44,8 @@ function levenshteinDistance(a, b) {
  * 1 = identical, 0 = completely different
  */
 function stringSimilarity(a, b) {
-    const distance = levenshteinDistance(a.toLowerCase(), b.toLowerCase());
+    // We do NOT modify case here anymore, because levenshteinDistance now handles case weighting
+    const distance = levenshteinDistance(a, b);
     const maxLen = Math.max(a.length, b.length);
     return maxLen === 0 ? 1 : 1 - (distance / maxLen);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.1.1",
+  "version": "6.2.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
@@ -22,7 +22,10 @@
     "docs:build": "vitepress build docs",
     "build": "npm run generate-types && npm run generate-docs && npm run generate-all-api-docs && npm run update-all-api-signatures && tsc",
     "prepublishOnly": "npm run build",
-    "test": "npx playwright test",
+    "test": "npm run test:unit && npx playwright test",
+    "test:unit": "vitest run --reporter=verbose --reporter=html",
+    "test:unit:ui": "vitest --ui",
+    "test:e2e": "npx playwright test",
     "test:compatibility": "npx playwright test compatibility",
     "prepare": "husky install"
   },
@@ -38,9 +41,11 @@
   "devDependencies": {
     "@playwright/test": "^1.49.1",
     "@types/node": "^22.10.5",
+    "@vitest/ui": "^4.0.18",
+    "happy-dom": "^20.6.1",
     "husky": "^9.1.7",
     "typescript": "^5.7.2",
-    "vitepress": "^1.6.4"
-  },
-  "dependencies": {}
+    "vitepress": "^1.6.4",
+    "vitest": "^4.0.18"
+  }
 }