@rickcedwhat/playwright-smart-table 6.24.0 → 6.25.0-next.3dfcc94

package/dist/typeContext.js

@@ -1,1133 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TYPE_CONTEXT = void 0;
-/**
- * 🤖 AUTO-GENERATED FILE. DO NOT EDIT.
- * This file is generated by scripts/embed-types.mjs
- * It contains the raw text of types.ts to provide context for LLM prompts.
- */
-exports.TYPE_CONTEXT = `
-/**
- * Selector used by strategies (e.g. pagination buttons, spinners): a CSS string resolved
- * relative to the parent, or a function that receives the parent and returns a Locator.
- * @example
- * nextButton: 'button.next'
- * nextButton: (root) => root.getByRole('button', { name: 'Next' })
- */
-export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
-
-/**
- * Selector for \`headerSelector\`, \`rowSelector\`, and \`cellSelector\`: a CSS string resolved
- * relative to the parent, or a function that receives the parent Locator (the table root for
- * headers/rows, the row for cells) and returns a Locator.
- *
- * Some features evaluate selectors in the browser and need a CSS string. Given a function,
- * the \`dataAttribute\` viewport strategy warns once and skips the step that needs the string.
- * The MUI DataGrid viewport instead uses \`[data-rowindex]\` for row scrolling and ranges,
- * and \`.MuiDataGrid-columnHeader\` for header scrolling. Its overscan filtering warns and
- * includes every mounted row because it needs the configured row selector.
- * @example
- * rowSelector: 'tbody tr'
- * rowSelector: (root) => root.getByRole('row').filter({ has: root.getByRole('cell') })
- * // Headers rendered as a separate table outside the root:
- * headerSelector: (root) => root.page().locator('#header-table th')
- */
-export type TableSelector = string | ((parent: Locator) => Locator);
-
-/**
- * Return type for \`resolveRowIndex\`. A plain number gives the logical index only;
- * \`{ index, selector }\` additionally provides a CSS selector the library uses to
- * build a self-healing row locator that survives virtual-scroll DOM recycling.
- */
-export type RowIndexResult = number | { index: number; selector: string };
-
-/**
- * Value used to filter rows.
- * - string/number/RegExp: filter by text content of the cell.
- * - function: filter by custom locator logic within the cell.
- * @example
- * // Text filter
- * { Name: 'John' }
- * 
- * // Custom locator filter (e.g. checkbox is checked)
- * { Status: (cell) => cell.locator('input:checked') }
- */
-export type FilterValue = string | RegExp | number | ((cell: Locator) => Locator);
-
-/**
- * Function to get a cell locator given row, column info.
- * Replaces the old cellResolver.
- */
-export type GetCellLocatorFn = (args: {
-  row: Locator;
-  /** The root locator passed to useTable(). Useful for re-querying stale row locators. */
-  root: Locator;
-  columnName: string;
-  columnIndex: number;
-  rowIndex?: number;
-  page: Page;
-  config: FinalTableConfig<any>;
-}) => Locator;
-
-/**
- * Hook called before each cell value is read in \`toJSON\` (and \`columnOverrides.read\`).
- *
- * Use this to scroll off-screen columns into view in **horizontally** virtualized tables,
- * wait for lazy-rendered content (popovers, tooltips, async cell renderers), or perform
- * any other pre-read setup that doesn't involve Y-axis scrolling.
- *
- * ---
- *
- * **⚠️ Y-scroll footgun — do NOT call \`scrollIntoViewIfNeeded()\` on row-virtualized grids.**
- *
- * \`scrollIntoViewIfNeeded\` adjusts *both* scroll axes. On grids that recycle DOM nodes
- * based on the Y position (MUI DataGrid, AG Grid, react-window, etc.) calling it will
- * shift the viewport vertically, unmounting the row you are currently reading and
- * silently returning stale or empty cell values for the remainder of the row.
- *
- * Safe uses:
- * - Column-only (X-axis) virtualization where rows are always in the DOM.
- * - Calling \`scrollIntoViewIfNeeded\` on the **header cell** only, when that header is
- *   guaranteed not to trigger a Y-scroll (e.g. sticky header grids).
- *
- * For grids with **both** row and column virtualization, use the \`viewport\` strategy
- * instead — it drives explicit \`scrollToRow\` / \`scrollToColumn\` calls and is aware of
- * the virtualization lifecycle.
- *
- * @example
- * // Safe: column-only horizontal virtualization (rows always in DOM)
- * strategies: {
- *   beforeCellRead: async ({ columnName, getHeaderCell }) => {
- *     const header = await getHeaderCell(columnName);
- *     await header.scrollIntoViewIfNeeded(); // only scrolls X — rows stay mounted
- *   }
- * }
- *
- * @example
- * // Safe: wait for a lazy-rendered popover/tooltip before reading its text
- * strategies: {
- *   beforeCellRead: async ({ cell }) => {
- *     await cell.hover();
- *     await cell.page().waitForSelector('.cell-tooltip', { state: 'visible' });
- *   }
- * }
- */
-export type BeforeCellReadFn = (args: {
-  /** The resolved cell locator */
-  cell: Locator;
-  columnName: string;
-  columnIndex: number;
-  row: Locator;
-  page: Page;
-  root: Locator;
-  /** Resolves a column name to its header cell locator */
-  getHeaderCell: (columnName: string) => Promise<Locator>;
-}) => Promise<void>;
-
-/**
- * Function to get the currently active/focused cell.
- * Returns null if no cell is active.
- */
-export type GetActiveCellFn = (args: TableContext) => Promise<{
-  rowIndex: number;
-  columnIndex: number;
-  columnName?: string;
-  locator: Locator;
-} | null>;
-
-/**
- * Viewport oracle strategies for virtualized tables.
- *
- * These tell the library *what is currently in the DOM* rather than *how to move*.
- * When present, the cell-reading engine uses them to jump directly to a target
- * row/column instead of stepping blindly with navigation primitives.
- *
- * This is the primary fix for the 2D scroll hazard: scrolling right to bring a
- * column into view can knock rows out of the vertical viewport (and vice versa).
- * With \`getVisibleRowRange\` the engine detects this and calls \`scrollToRow\` to
- * restore the row before reading — eliminating the hazard without polling loops.
- *
- * All members are optional. Supply whichever the underlying grid exposes:
- * - Range oracles alone enable hazard detection with graceful fallback to navigation primitives.
- * - Scroll primitives alone enable direct jumps without range awareness.
- * - Both together give the most reliable, fastest path.
- *
- * @example
- * // MUI DataGrid via apiRef
- * strategies: {
- *   viewport: {
- *     getVisibleRowRange: async ({ root }) =>
- *       root.evaluate(el => {
- *         const api = (el as any).__muiDataGrid__;
- *         return { first: api.getFirstVisibleRow(), last: api.getLastVisibleRow() };
- *       }),
- *     scrollToRow: async ({ root }, rowIndex) =>
- *       root.evaluate((el, idx) =>
- *         (el as any).__muiDataGrid__.scrollToIndexes({ rowIndex: idx }), rowIndex),
- *     scrollToColumn: async ({ root }, colIndex) =>
- *       root.evaluate((el, idx) =>
- *         (el as any).__muiDataGrid__.scrollToIndexes({ colIndex: idx }), colIndex),
- *   }
- * }
- *
- * @example
- * // aria-rowindex / aria-colindex DOM fallback (works without internal API access)
- * strategies: {
- *   viewport: {
- *     getVisibleRowRange: async ({ root }) =>
- *       root.evaluate(el => {
- *         const rows = [...el.querySelectorAll('[role="row"][aria-rowindex]')];
- *         const idxs = rows.map(r => Number(r.getAttribute('aria-rowindex')) - 1);
- *         return { first: Math.min(...idxs), last: Math.max(...idxs) };
- *       }),
- *   }
- * }
- */
-export interface ViewportStrategy {
-  /**
-   * Returns the 0-based index range of rows currently rendered in the DOM.
-   * Used to detect when a target row has been scrolled out of view and needs recovery.
-   */
-  getVisibleRowRange?: (context: TableContext) => Promise<{ first: number; last: number }>;
-
-  /**
-   * Returns the DOM positions (0-based, document order — indices into the resolved
-   * \`rowSelector\` set) of rows currently within the scroll container's visible bounds.
-   * Unlike \`getVisibleRowRange\` (a logical min/max), this identifies the exact rows, so
-   * \`map\`/\`forEach\`/\`filter\` can skip overscan rows during collection (see #353 / #357).
-   * Geometry-based and inclusive (any overlap counts as visible). When the container can't
-   * be measured, return all positions so no rows are filtered.
-   */
-  getVisibleRowIndices?: (context: TableContext) => Promise<number[]>;
-
-  /**
-   * Returns the 0-based index range of columns currently rendered in the DOM.
-   * Used to detect when a target column is not yet mounted before reading.
-   */
-  getVisibleColumnRange?: (context: TableContext) => Promise<{ first: number; last: number }>;
-
-  /**
-   * Scrolls or jumps directly to make a row visible by 0-based index.
-   * Replaces blind goDown()/goUp() step loops for grids that expose a scroll API.
-   */
-  scrollToRow?: (context: TableContext, rowIndex: number) => Promise<void>;
-
-  /**
-   * Scrolls or jumps directly to make a column visible by 0-based index.
-   * Replaces blind goRight()/goLeft() step loops for grids that expose a scroll API.
-   */
-  scrollToColumn?: (context: TableContext, colIndex: number) => Promise<void>;
-
-  /**
-   * When true, disables the automatic memoization of getVisibleColumnRange and
-   * getVisibleRowRange results. By default the library caches each range value and
-   * invalidates it after the corresponding scroll call, eliminating redundant DOM
-   * evaluate() round-trips between scrolls.
-   */
-  disableCache?: boolean;
-}
-
-
-/**
- * SmartCell - A Playwright Locator with table-aware methods for single-cell operations.
- * 
- * Extends all standard Locator methods (click, isVisible, etc.).
- */
-export type SmartCell = Locator & {
-  /**
-   * Scrolls/paginates to bring this specific cell into view using the configured strategies.
-   * Useful when the grid is horizontally virtualized and the column must be scrolled
-   * into view before it can be interacted with or read.
-   */
-  bringIntoView(): Promise<void>;
-};
-
-
-/**
- * SmartRow - A Playwright Locator with table-aware methods.
- * 
- * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.
- * 
- * @example
- * const row = table.getRow({ Name: 'John Doe' });
- * await row.click(); // Standard Locator method
- * const email = row.getCell('Email'); // Table-aware method
- * const data = await row.toJSON(); // Extract all row data
- * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields
- */
-export type SmartRow<T = any> = Locator & {
-  /** Optional row index (0-based) if known */
-  rowIndex?: number;
-
-  /** Optional page index this row was found on (0-based) */
-  tablePageIndex?: number;
-
-  /** Reference to the parent TableResult */
-  table: TableResult<T>;
-
-  /**
-   * Get a cell locator by column name.
-   * @param column - Column name (case-sensitive)
-   * @returns SmartCell (Locator + bringIntoView)
-   * @example
-   * const emailCell = row.getCell('Email');
-   * await emailCell.bringIntoView();
-   * await expect(emailCell).toHaveText('john@example.com');
-   */
-  getCell(column: string): SmartCell;
-
-  /**
-   * Extract all cell data as a key-value object.
-   * @param options - Optional configuration
-   * @param options.columns - Specific columns to extract (extracts all if not specified)
-   * @returns Promise resolving to row data
-   * @example
-   * const data = await row.toJSON();
-   * // { Name: 'John', Email: 'john@example.com', ... }
-   * 
-   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
-   * // { Name: 'John', Email: 'john@example.com' }
-   *
-   * // Atomic: snapshot all cell values in a single evaluate — zero inter-column stagger.
-   * // Requires cellSelector to be a CSS string (not a function).
-   * // Column overrides ARE supported (run against a frozen off-screen reconstruction).
-   * // Uses textContent (not layout-dependent innerText) for non-override columns.
-   * const coherent = await row.toJSON({ atomic: true });
-   */
-  toJSON(options?: { columns?: string[]; atomic?: boolean }): Promise<T>;
-
-  /**
-   * Scrolls/paginates to bring this row into view.
-   * Works when row position metadata is known (e.g., from getRowByIndex, findRow,
-   * findRows, filter, or async iteration).
-   *
-   * Prefers \`strategies.viewport.scrollToRow\` when configured; otherwise falls back to
-   * Playwright \`scrollIntoViewIfNeeded()\`.
-   * @throws Error if row position metadata is unknown
-   */
-  bringIntoView(): Promise<void>;
-
-  /**
-   * Intelligently fills form fields in the row.
-   * Automatically detects input types (text, select, checkbox, contenteditable).
-   * 
-   * @param data - Column-value pairs to fill
-   * @param options - Optional configuration
-   * @param options.inputMappers - Custom input selectors per column
-   * @example
-   * // Auto-detection
-   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });
-   * 
-   * // Custom input mappers
-   * await row.smartFill(
-   *   { Name: 'John' },
-   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }
-   * );
-   */
-  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
-
-  /**
-   * Get the resolved value of any column — real, override, or synthetic.
-   *
-   * When \`strategies.viewport\` or \`strategies.navigation\` is configured, runs the same
-   * cell-navigation pipeline as \`toJSON\` / \`getCell().bringIntoView()\` so off-screen
-   * virtualized cells are mounted before reading. Without those strategies, reads the
-   * current DOM cell (Playwright auto-wait).
-   *
-   * @param column - Column name (case-sensitive)
-   * @returns The column value as a string
-   */
-  getValue(column: string): Promise<string>;
-
-  /**
-   * Returns whether the row exists in the DOM (i.e. is not a sentinel row).
-   */
-  wasFound(): boolean;
-};
-
-export type StrategyContext = TableContext & {
-  rowLocator?: Locator;
-  rowIndex?: number;
-};
-
-/**
- * Defines the contract for a sorting strategy.
- */
-export interface SortingStrategy {
-  /**
-   * Performs the sort action on a column.
-   */
-  doSort(options: {
-    columnName: string;
-    direction: 'asc' | 'desc';
-    context: StrategyContext;
-  }): Promise<void>;
-
-  /**
-   * Retrieves the current sort state of a column.
-   */
-  getSortState(options: {
-    columnName: string;
-    context: StrategyContext;
-  }): Promise<'asc' | 'desc' | 'none'>;
-}
-
-/**
- * Debug configuration for development and troubleshooting
- */
-export type DebugConfig = {
-  /**
-   * Slow down operations for debugging
-   * - number: Apply same delay to all operations (ms)
-   * - object: Granular delays per operation type
-   */
-  slow?: number | {
-    pagination?: number;
-    getCell?: number;
-    findRow?: number;
-    default?: number;
-  };
-  /**
-   * Log level for debug output
-   * - 'verbose': All logs (verbose, info, error)
-   * - 'info': Info and error logs only
-   * - 'error': Error logs only
-   * - 'none': No logs
-   */
-  logLevel?: 'verbose' | 'info' | 'error' | 'none';
-};
-
-export interface TableContext<T = any> {
-  root: Locator;
-  config: FinalTableConfig<T>;
-  page: Page;
-  resolve: (selector: Selector, parent: Locator | Page) => Locator;
-  /** Resolves a column name to its header cell locator. Available after table is initialized. */
-  getHeaderCell?: (columnName: string) => Promise<Locator>;
-  /** Returns all column names in order. Available after table is initialized. */
-  getHeaders?: () => Promise<string[]>;
-  /** Scrolls the table horizontally to bring the given column's header into view. */
-  scrollToColumn?: (columnName: string) => Promise<void>;
-}
-
-export interface PaginationPrimitives {
-  /** Classic "Next Page" or "Scroll Down" */
-  goNext?: (context: TableContext) => Promise<boolean>;
-
-  /** Classic "Previous Page" or "Scroll Up" */
-  goPrevious?: (context: TableContext) => Promise<boolean>;
-
-  /** Bulk skip forward multiple pages at once. Returns number of pages skipped. */
-  goNextBulk?: (context: TableContext) => Promise<boolean | number>;
-
-  /** Bulk skip backward multiple pages at once. Returns number of pages skipped. */
-  goPreviousBulk?: (context: TableContext) => Promise<boolean | number>;
-
-  /** Jump to first page / scroll to top */
-  goToFirst?: (context: TableContext) => Promise<boolean>;
-
-  /** Jump to last page / scroll to bottom */
-  goToLast?: (context: TableContext) => Promise<boolean>;
-
-  /**
-   * Fetch the total number of pages currently available.
-   * Can be used to optimize pagination paths (e.g. jumping to last page and going backwards).
-   */
-  getTotalPages?: (context: TableContext) => Promise<number | null>;
-
-  /**
-   * Jump to specific page index (0-indexed).
-   * Can be full-range (e.g. page number input: any page works) or windowed (e.g. only visible links 6–14).
-   * Return false when the page is not reachable in the current UI; the library will step toward the target (goNextBulk/goNext or goPreviousBulk/goPrevious) and retry goToPage until it succeeds.
-   */
-  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
-
-  /** How many pages one goNextBulk() advances. Used by navigation path planner for optimal bringIntoView. */
-  nextBulkPages?: number;
-
-  /** How many pages one goPreviousBulk() goes back. Used by navigation path planner for optimal bringIntoView. */
-  previousBulkPages?: number;
-
-  /**
-   * Called once during init() to sync the library's page counter with the actual DOM state.
-   * Use when a table may open on a page other than the first (e.g. a deep-linked URL that
-   * lands on page 5). Returns a 0-indexed page number.
-   * @example
-   * detectCurrentPage: async (root) => {
-   *   const text = await root.locator('[aria-current="page"]').textContent();
-   *   return parseInt(text ?? '1') - 1;
-   * }
-   */
-  detectCurrentPage?: (root: import('@playwright/test').Locator) => number | Promise<number>;
-}
-
-export type PaginationStrategy = PaginationPrimitives;
-
-export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
-
-export type ContentReadyStrategy = (row: Locator, page: Page) => Promise<void>;
-
-
-
-export type FillStrategy = (options: {
-  row: SmartRow;
-  columnName: string;
-  value: any;
-  index: number;
-  page: Page;
-  rootLocator: Locator;
-  config: FinalTableConfig<any>;
-  table: TableResult; // The parent table instance
-  fillOptions?: FillOptions;
-}) => Promise<void>;
-
-/** Context passed as the second argument to {@link ColumnOverride.read}. */
-export interface ColumnOverrideReadContext {
-  /**
-   * The parent row. Use for multi-cell or row-derived values — e.g. a synthetic column
-   * that reads an \`a[href]\` or a \`data-*\` attribute from the row rather than a cell:
-   * \`read: (_cell, { row }) => row.evaluate(el => el.querySelector('a')?.href)\`.
-   */
-  row: SmartRow;
-  /** The column being read. */
-  columnName: string;
-  /** The column's 0-based index in the resolved header map. */
-  columnIndex: number;
-  /**
-   * Get a Locator for another cell in the same row by column name.
-   * Returns raw cell Locators, not override-processed values.
-   *
-   * In atomic mode, the Locator points at the frozen reconstructed cell — coherent with
-   * every other cell from the same snapshot. In non-atomic mode, it points at the live cell.
-   *
-   * @example
-   * read: async (_cell, { getCell }) => {
-   *   const name = (await getCell('Name').innerText()).trim();
-   *   const href = await getCell('Name').locator('a').getAttribute('href') || '';
-   *   return \`\${name} | \${href}\`;
-   * }
-   */
-  getCell: (columnName: string) => Locator;
-}
-
-export interface SyntheticColumnDef<T = any> {
-  compute: (row: SmartRow<T>) => Promise<string | number> | string | number;
-}
-
-export interface ColumnOverride<TValue = any> {
-  /**
-   * How to extract the value from the cell.
-   * The second \`context\` argument provides the parent \`row\` (for multi-cell or row-derived
-   * values), plus \`columnName\` and \`columnIndex\`. Backwards-compatible: existing
-   * single-argument \`read(cell)\` implementations keep working.
-   */
-  read?: (cell: Locator, context: ColumnOverrideReadContext) => Promise<TValue> | TValue;
-
-  /** 
-   * How to fill the cell with a new value. (Replaces smartFill default logic)
-   * Provides the current value (via \`read\`) if a \`write\` wants to check state first.
-   */
-  write?: (params: {
-    cell: Locator;
-    targetValue: TValue;
-    currentValue?: TValue;
-    row: SmartRow<any>;
-  }) => Promise<void>;
-}
-
-export type { HeaderStrategy } from './strategies/headers';
-export type { NavigationPrimitives, CellNavigationStrategy } from './strategies/columns';
-
-/**
- * Strategy to resolve column names (string or regex) to their index.
- */
-// fallow-ignore-next-line unused-type
-export type { ColumnResolutionStrategy } from './strategies/resolution';
-
-/**
- * Strategy to filter rows based on criteria. Applied when using getRow/findRow/findRows with filters.
- * The default engine handles string, RegExp, number, and function (cell) => Locator filters.
- */
-export interface FilterStrategy {
-  apply(options: {
-    rows: Locator;
-    filter: { column: string, value: FilterValue };
-    colIndex: number;
-    tableContext: TableContext;
-  }): Locator;
-}
-
-/**
- * Strategy to check if the table or rows are loading. Used after pagination/sort to wait for content.
- * E.g. isHeaderLoading for init stability; isTableLoading after sort/pagination.
- */
-export interface LoadingStrategy {
-  isTableLoading?: (context: TableContext) => Promise<boolean>;
-  isRowLoading?: (row: SmartRow) => Promise<boolean>;
-  isHeaderLoading?: (context: TableContext) => Promise<boolean>;
-
-  /**
-   * How long (ms) to wait for a loading row to resolve before applying onRowLoadingTimeout.
-   * Honored by findRows AND by map/forEach/filter, where the wait runs before the dedupe
-   * strategy so content-based dedupe keys see the row's final loaded state.
-   * When not set (backward-compatible behavior): findRows skips loading rows immediately;
-   * map/forEach/filter process them as-is.
-   */
-  rowLoadingTimeout?: number;
-
-  /**
-   * What to do when a row is still loading after rowLoadingTimeout ms.
-   * - 'skip': drop the row from results (matches legacy skip behavior)
-   * - 'read-as-is': include the row even though it's still loading (default)
-   * - 'throw': throw an error with row index and timeout info
-   * Defaults to 'read-as-is' when rowLoadingTimeout is set.
-   */
-  onRowLoadingTimeout?: 'skip' | 'read-as-is' | 'throw';
-
-  /**
-   * Predicate called before reading each cell. Return true if the cell is still loading.
-   * When cellLoadingTimeout is also set, the engine waits up to that many ms for the
-   * cell to resolve before applying onCellLoadingTimeout.
-   */
-  isCellLoading?: (cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<boolean>;
-
-  /**
-   * How long (ms) to wait for a loading cell to resolve before applying onCellLoadingTimeout.
-   * When not set and isCellLoading returns true, the cell is read as-is immediately.
-   */
-  cellLoadingTimeout?: number;
-
-  /**
-   * What to do when a cell is still loading after cellLoadingTimeout ms.
-   * - 'skip': use empty string for this cell value
-   * - 'read-as-is': read the cell content even though it's still loading (default)
-   * - 'throw': throw an error with column name, row index and timeout info
-   * - callback: called with (cell, columnName, row); its return value becomes the cell's string value
-   * Defaults to 'read-as-is' when cellLoadingTimeout is set.
-   */
-  onCellLoadingTimeout?:
-    | 'skip'
-    | 'read-as-is'
-    | 'throw'
-    | ((cell: import('@playwright/test').Locator, columnName: string, row: SmartRow) => Promise<string>);
-
-  /**
-   * Max ms to wait while \`isTableLoading\` returns true (countRows, findRow(s),
-   * page-ready gates, and sort when \`sortStabilizationTimeout\` is unset).
-   * @default 10000
-   */
-  loadingTimeout?: number;
-
-  /** Max ms to wait for sort stabilization when isTableLoading is set. Overrides \`loadingTimeout\` for sort only. @default 10000 */
-  sortStabilizationTimeout?: number;
-  /** Polling interval (ms) while waiting for sort / table-ready stabilization. @default 100 (sort) / 200 (table-ready) */
-  sortStabilizationPollInterval?: number;
-  /** Fallback delay (ms) after sort when no isTableLoading is configured. @default 200 */
-  sortStabilizationFallbackDelay?: number;
-}
-
-/**
- * Organized container for all table interaction strategies.
- */
-export interface TableStrategies {
-  /** Strategy for discovering/scanning headers */
-  header?: HeaderStrategy;
-  /** Primitive navigation functions (goUp, goDown, goLeft, goRight, goHome) */
-  navigation?: NavigationPrimitives;
-
-  /** Strategy for filling form inputs */
-  fill?: FillStrategy;
-  /** Strategy for paginating through data */
-  pagination?: PaginationStrategy;
-  /** Strategy for sorting columns */
-  sorting?: SortingStrategy;
-  /** Strategy for deduplicating rows during iteration/scrolling */
-  dedupe?: DedupeStrategy;
-  /** Function to get a cell locator */
-  getCellLocator?: GetCellLocatorFn;
-  /** Function to get the currently active/focused cell */
-  getActiveCell?: GetActiveCellFn;
-  /**
-   * Strategy for filtering rows. If present, FilterEngine will delegate filter application
-   * to this pluggable strategy.
-   */
-  filter?: FilterStrategy;
-  /**
-   * Hook called before each cell value is read in toJSON and columnOverrides.read.
-   * Fires for both the default innerText extraction and custom read mappers.
-   * Useful for scrolling off-screen columns into view in horizontally virtualized tables.
-   */
-  beforeCellRead?: BeforeCellReadFn;
-  /**
-   * Strategy for detecting loading states. Use this for table-, row-, and header-level readiness.
-   * E.g. after sort/pagination, the engine uses loading.isTableLoading when present.
-   */
-  loading?: LoadingStrategy;
-
-  /**
-   * Resolve the stable data-model index for a row locator.
-   *
-   * Called by \`findRow\` / \`findRows\` to convert a DOM row into the index used for
-   * virtual-scroll positioning. Useful for grids where DOM position resets to 0 on
-   * each page while the grid itself maintains a monotone counter (e.g. MUI DataGrid's
-   * \`data-rowindex\` attribute).
-   *
-   * Return \`undefined\` to fall back to DOM position.
-   *
-   * When the index maps to a DOM attribute, return \`{ index, selector }\` instead of
-   * a plain number. The library uses the CSS selector to build a **self-healing row
-   * locator** that re-queries the DOM on every action — surviving virtual-scroll
-   * recycling for \`getCell\`, \`smartFill\`, and \`toJSON\` without manual re-pinning.
-   *
-   * @example
-   * // MUI DataGrid: self-healing via data-rowindex attribute
-   * resolveRowIndex: async (row) => {
-   *   const v = await row.getAttribute('data-rowindex').catch(() => null);
-   *   if (v === null || isNaN(Number(v))) return undefined;
-   *   return { index: Number(v), selector: \`[data-rowindex="\${v}"]\` };
-   * }
-   */
-  resolveRowIndex?: (row: Locator) => Promise<RowIndexResult | undefined>;
-
-  /**
-   * Waits until a row's content has stabilized before cloning in
-   * \`toJSON({ atomic: true })\`. Needed for recycling virtualizers where the
-   * framework updates element positions synchronously but renders cell content
-   * asynchronously (e.g. react-window, react-virtuoso with React concurrent mode).
-   *
-   * Without this, the clone captures stale content from the previous occupant of the
-   * DOM slot — the element is at the correct position but React hasn't re-rendered yet.
-   *
-   * Use \`Strategies.ContentReady.textStable()\` for the built-in text-polling strategy.
-   *
-   * @example
-   * strategies: {
-   *   contentReady: Strategies.ContentReady.textStable({ timeout: 500 }),
-   * }
-   */
-  contentReady?: ContentReadyStrategy;
-
-  /**
-   * Viewport oracle strategies for 2D virtualized tables (e.g. MUI DataGrid, AG Grid,
-   * Braintrust-style grids where both rows and columns are virtualized simultaneously).
-   *
-   * When present, the cell-reading engine uses these to jump directly to the target
-   * row/column and to detect the 2D scroll hazard (scrolling to reveal a column can
-   * knock rows out of the vertical viewport, and vice versa).
-   *
-   * Completely optional and additive — existing \`navigation\` primitives remain the fallback.
-   */
-  viewport?: ViewportStrategy;
-}
-
-
-export interface TableConfig<T = any> {
-  /**
-   * Selector for the header cells, relative to the table root. Default \`'thead th'\`.
-   * Use a function to reach headers outside the root, e.g.
-   * \`(root) => root.page().locator('#header-table th')\`.
-   */
-  headerSelector?: TableSelector;
-  /** Selector for the rows, relative to the table root. Default \`'tbody tr'\`. */
-  rowSelector?: TableSelector;
-  /** Selector for the cells, relative to a row. Default \`'td'\`. */
-  cellSelector?: TableSelector;
-  /**
-   * Number of pages to scan for verification / iteration.
-   * Defaults to \`1\` — set explicitly (e.g. \`maxPages: 5\`) when using a pagination
-   * strategy, or you will never leave page 1. Init logs a warning when pagination
-   * is configured and this is still \`1\`.
-   */
-  maxPages?: number;
-  /**
-   * Default concurrency strategy for iteration methods.
-   * Can be overridden by the options passed to forEach, map, or filter.
-   * Defaults to sequential when unset (safer for UI interactions).
-   */
-  concurrency?: RowIterationMode;
-  /** Hook to rename columns dynamically */
-  headerTransformer?: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;
-  /** Automatically scroll to table on init */
-  autoScroll?: boolean;
-  /** Debug options for development and troubleshooting */
-  debug?: DebugConfig;
-  /** Hook called after reset completes (after goToFirst, cache clear, and autoInit). */
-  onReset?: (context: TableContext) => Promise<void>;
-  /** All interaction strategies */
-  strategies?: TableStrategies;
-
-  /**
-   * Unified interface for reading and writing data to specific columns.
-   * Overrides both default extraction (toJSON) and filling (smartFill) logic.
-   */
-  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
-
-  /**
-   * Computed columns with no DOM presence. Each key becomes a virtual column name
-   * available in \`toJSON()\`, \`getValue()\`, and \`findRow()\`/\`findRows()\` filters.
-   * The \`compute\` function receives the full SmartRow and must only read real or
-   * override columns (no chaining between synthetics).
-   */
-  syntheticColumns?: Record<string, SyntheticColumnDef<T>>;
-
-  /**
-   * Locator for an empty-state element that replaces the table when there are no results.
-   * If header resolution fails during init() and this locator is visible, init() succeeds
-   * and isEmpty() returns true. All row operations still throw normally.
-   */
-  emptyState?: Locator;
-}
-
-/**
- * @internal Resolved config after defaults are applied. Prefer {@link TableConfig} in public code.
- */
-export interface FinalTableConfig<T = any> extends TableConfig<T> {
-  headerSelector: TableSelector;
-  rowSelector: TableSelector;
-  cellSelector: TableSelector;
-  maxPages: number;
-  autoScroll: boolean;
-  concurrency?: RowIterationMode;
-  debug?: TableConfig['debug'];
-  headerTransformer: (args: { text: string, index: number, locator: Locator, seenHeaders: Set<string> }) => string | Promise<string>;
-  onReset: (context: TableContext) => Promise<void>;
-  strategies: TableStrategies;
-}
-
-
-export interface FillOptions {
-  /**
-   * Custom input mappers for specific columns.
-   * Maps column names to functions that return the input locator for that cell.
-   */
-  inputMappers?: Record<string, (cell: Locator) => Locator>;
-}
-
-
-
-/** Callback context passed to forEach, map, and filter. */
-export type RowIterationContext<T = any> = {
-  row: SmartRow<T>;
-  /**
-   * The row's logical/data-model index. When a \`resolveRowIndex\` strategy is configured
-   * (e.g. MUI DataGrid's \`data-rowindex\`) this is the grid's true row index; otherwise it
-   * equals \`index\`. Use this for \`row.bringIntoView()\` and position math on virtualized
-   * tables — it is stable across scrolling/dedupe, unlike the visit-order \`index\`.
-   */
-  rowIndex: number;
-  /**
-   * 0-based enumeration counter — the order this row was visited (contiguous within the run).
-   * Not a DOM position or grid identity. Use \`rowIndex\` for the row's data-model index.
-   */
-  index: number;
-  /** 0-based page index — which page this row was collected from. */
-  pageIndex: number;
-  stop: () => void;
-};
-
-/** Concurrency modes for row iteration. */
-export type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';
-
-/** Shared options for forEach, map, and filter. */
-export type RowIterationOptions = {
-  /** Maximum number of pages to iterate. Defaults to config.maxPages. */
-  maxPages?: number;
-  /**
-   * Concurrency strategy for iteration.
-   * - 'parallel': Full parallel execution of both navigation and actions.
-   * - 'synchronized': Parallel navigation (lock-step) with serial actions.
-   * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.
-   * @default config.concurrency, then 'sequential'
-   */
-  concurrency?: RowIterationMode;
-  /**
-   * Deduplication strategy. Use when rows may repeat across iterations
-   * (e.g. infinite scroll tables). Returns a unique key per row.
-   */
-  dedupe?: DedupeStrategy;
-  /**
-   * When true, use goNextBulk (if present) to advance pages during iteration.
-   * @default false — uses goNext for one-page-at-a-time advancement
-   */
-  useBulkPagination?: boolean;
-};
-
-/**
- * Result of {@link useTable}. Implements \`AsyncIterable\` — \`for await (const { row } of table)\`
- * uses the same page-walk as \`map\` / \`forEach\` (\`scanPages\` + runMap): overscan, loading,
- * dedupe, and EOF final scan (#427).
- */
-export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number; index: number; pageIndex: number }> {
-  /**
-   * Current DOM page index (0-based). Automatically maintained during pagination
-   * and \`bringIntoView\`. Treat as **read-only** — assigning manually can desync
-   * the path planner. Manual writes log a warning; prefer \`reset()\` / library
-   * navigation. Writable access may become read-only in v7.
-   */
-  currentPageIndex: number;
-
-  /**
-   * Initializes the table by resolving headers. Must be called before using sync methods.
-   * @param options Optional timeout for header resolution (default: 3000ms)
-   */
-  init(options?: { timeout?: number }): Promise<TableResult<T>>;
-
-  /**
-   * SYNC: Checks if the table has been initialized.
-   * @returns true if init() has been called and completed, false otherwise
-   */
-  isInitialized(): boolean;
-
-  /**
-   * SYNC: Returns true if init() resolved via the emptyState path — the table's
-   * empty-state locator was visible when header resolution failed.
-   * Row operations still throw normally; use this to branch before calling them.
-   */
-  isEmpty(): boolean;
-
-  getHeaders: () => Promise<string[]>;
-  getHeaderCell: (columnName: string) => Promise<Locator>;
-
-  /**
-   * Finds a row by filters on the current page only. Returns immediately (sync).
-   * Throws error if table is not initialized.
-   * @note The sync path cannot compute a real \`rowIndex\`, so the returned SmartRow's
-   * \`rowIndex\` is \`undefined\` (virtual-scroll positioning via \`bringIntoView()\` is limited).
-   * Use \`findRow()\` (async) when you need a row with an accurate \`rowIndex\`.
-   * @note Cannot filter by \`syntheticColumns\` or \`columnOverrides.read\` keys — those need
-   * async evaluation via \`findRow()\` / \`findRows()\`. DOM filters use \`strategies.getCellLocator\`
-   * when configured (column-virtualized grids), otherwise \`cellSelector\` + column index.
-   */
-  getRow: (
-    filters: Record<string, FilterValue>,
-    options?: { exact?: boolean }
-  ) => SmartRow<T>;
-
-  /**
-   * Gets a row by its 0-based position in the currently-rendered DOM (sync, no scroll).
-   * Throws if the table is not initialized.
-   *
-   * For button-paginated tables this is the i-th row on the current page. For virtualized
-   * tables the render window shifts as you scroll, so \`getRowByIndex(i)\` returns whatever
-   * row currently sits at DOM position \`i\` — NOT the logical/absolute row \`i\` in the dataset
-   * once the list has scrolled. For the row with a specific logical/data-model index on a
-   * virtualized table, use the async \`findRowByIndex(i)\` instead (it scrolls to the row);
-   * to iterate by logical identity, use \`map\` / \`findRows\` (with a \`dedupe\` strategy).
-   *
-   * Resolution is lazy: an out-of-range index yields a SmartRow whose operations fail when
-   * it is used, rather than throwing here.
-   *
-   * @param index 0-based position within the current render window
-   */
-  getRowByIndex: (
-    index: number
-  ) => SmartRow<T>;
-
-  /**
-   * ASYNC: Returns the row with a specific logical/data-model index, scrolling/paginating to
-   * reach it. Unlike the sync \`getRowByIndex\` (render-window position), this resolves the true
-   * data-model row \`index\` on virtualized tables.
-   *
-   * Reaches the row via, in order: a currently-mounted match, the viewport's random-access
-   * \`scrollToRow\` fast path, then advancing pages (on infinite-scroll tables a "page" is a
-   * scroll step) up to \`maxPages\`.
-   *
-   * Requires a \`strategies.resolveRowIndex\` to identify rows by logical index — throws if one
-   * is not configured. Also throws if the row cannot be reached (no silent wrong-row fallback).
-   *
-   * @param index 0-based logical/data-model row index
-   * @param options - \`maxPages\` bounds how far to scroll/paginate (defaults to config.maxPages)
-   */
-  findRowByIndex: (
-    index: number,
-    options?: { maxPages?: number }
-  ) => Promise<SmartRow<T>>;
-
-  /**
-   * ASYNC: Searches for a single row across pages using pagination.
-   * Auto-initializes the table if not already initialized.
-   * @param filters - The filter criteria to match
-   * @param options - Search options including exact match and max pages
-   */
-  findRow: (
-    filters: Record<string, FilterValue>,
-    options?: { exact?: boolean, maxPages?: number }
-  ) => Promise<SmartRow<T>>;
-
-  /**
-   * ASYNC: Searches for all matching rows across pages using pagination.
-   * Auto-initializes the table if not already initialized.
-   * @param filters - The filter criteria to match (omit or pass {} for all rows)
-   * @param options - Search options (exact, maxPages). \`useBulkPagination\` defaults to \`false\`: pages advance one at a time via \`goNext\` so no intermediate page is skipped. Set it to \`true\` to opt into \`goNextBulk\` (faster, but skips the rows on jumped-over pages).
-   */
-  findRows: (
-    filters?: Record<string, FilterValue>,
-    options?: { exact?: boolean, maxPages?: number, useBulkPagination?: boolean }
-  ) => Promise<SmartRowArray<T>>;
-
-  /**
-   * Resolves the named column and scrolls it into view.
-   * Prefers \`strategies.viewport.scrollToColumn\` when configured; otherwise scrolls the
-   * header cell via Playwright \`scrollIntoViewIfNeeded()\`.
-   */
-  scrollToColumn: (columnName: string) => Promise<void>;
-
-  /**
-   * Counts the number of rows, optionally filtered.
-   * Without arguments, counts all rows. With filters, counts only matching rows.
-   * Paginates when pagination is configured.
-   */
-  countRows: (filters?: Record<string, FilterValue>, options?: { exact?: boolean; maxPages?: number }) => Promise<number>;
-
-  /**
-   * Iterates over rows and extracts the value of a single column.
-   * More efficient than map + toJSON for single-column extraction.
-   * @param columnName - The name of the column to extract
-   * @param options - Iteration options
-   */
-  mapColumn<R = string>(columnName: string, options?: RowIterationOptions): Promise<R[]>;
-
-  /**
-   * @deprecated Use \`mapColumn\` (or \`map\`) instead. Will be removed in v7.0.0.
-   * Iterates over rows and extracts the value of a single column as strings.
-   * @param columnName - The name of the column to extract
-   * @param options - Iteration options
-   */
-  getColumnValues(columnName: string, options?: RowIterationOptions): Promise<string[]>;
-
-
-  /**
-   * Resets the table: calls goToFirst (if configured), clears cache, re-inits headers, then calls onReset.
-   */
-  reset: () => Promise<void>;
-
-  /**
-   * Revalidates the table's structure (headers, columns) without resetting pagination or state.
-   * Useful when columns change visibility or order dynamically.
-   */
-  revalidate: () => Promise<void>;
-
-  /**
-   * Iterates every row across all pages, calling the callback for side effects.
-   * Execution is sequential by default (safe for interactions like clicking/filling).
-   * Call \`stop()\` in the callback to end iteration early.
-   *
-   * @param callback - Function receiving { row, rowIndex, stop }
-   * @param options - maxPages, concurrency, dedupe, useBulkPagination
-   *
-   * @example
-   * await table.forEach(async ({ row, stop }) => {
-   *   if (await row.getCell('Status').innerText() === 'Done') stop();
-   *   await row.getCell('Checkbox').click();
-   * });
-   */
-  forEach(
-    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,
-    options?: RowIterationOptions
-  ): Promise<void>;
-
-  /**
-   * Transforms every row across all pages into a value. Returns a flat array.
-   * Defaults to \`concurrency: 'sequential'\` (safe for clicks/fills). Pass
-   * \`concurrency: 'parallel'\` for read-only extraction, or \`'synchronized'\` when
-   * navigation must stay lock-step on virtualized grids.
-   * Call \`stop()\` to halt after the current page finishes.
-   *
-   * @param callback - Function receiving { row, rowIndex, stop }
-   * @param options - maxPages, concurrency, dedupe, useBulkPagination
-   *
-   * @example
-   * // Default sequential — safe for UI interactions
-   * const assignees = await table.map(async ({ row }) => {
-   *   await row.getCell('Assignee').locator('button').click();
-   *   const name = await page.locator('.popover .name').innerText();
-   *   await page.keyboard.press('Escape');
-   *   return name;
-   * });
-   *
-   * @example
-   * // Read-only extraction — opt into parallel
-   * const emails = await table.map(
-   *   ({ row }) => row.getCell('Email').innerText(),
-   *   { concurrency: 'parallel' }
-   * );
-   */
-  map<R>(
-    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,
-    options?: RowIterationOptions
-  ): Promise<R[]>;
-
-  /**
-   * Shorthand for \`map()\` + \`reset()\`. Iterates every row across all pages, applies the
-   * callback (defaults to \`row.toJSON()\`), then resets the table back to page 1 — even if
-   * the callback throws.
-   *
-   * @param callback - Optional map function. Defaults to \`({ row }) => row.toJSON()\`.
-   * @param options - Same options as \`map()\`.
-   *
-   * @example
-   * // Zero-arg: returns toJSON() for every row
-   * const rows = await table.toArray();
-   *
-   * @example
-   * // Custom callback
-   * const names = await table.toArray(({ row }) => row.getCell('Name').innerText());
-   *
-   * @example
-   * // With options
-   * const rows = await table.toArray(({ row }) => row.toJSON(), { concurrency: 'parallel' });
-   */
-  toArray<R = Record<string, unknown>>(
-    callback?: (ctx: RowIterationContext<T>) => R | Promise<R>,
-    options?: RowIterationOptions
-  ): Promise<R[]>;
-
-  /**
-   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.
-   * Rows are returned as-is — call \`bringIntoView()\` on each if needed.
-   * Execution is sequential by default.
-   *
-   * @param predicate - Function receiving { row, rowIndex, stop }
-   * @param options - maxPages, concurrency, dedupe, useBulkPagination
-   *
-   * @example
-   * const active = await table.filter(async ({ row }) =>
-   *   await row.getCell('Status').innerText() === 'Active'
-   * );
-   */
-  filter(
-    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,
-    options?: RowIterationOptions
-  ): Promise<SmartRowArray<T>>;
-
-  /**
-   * Provides access to sorting actions and assertions.
-   */
-  sorting: {
-    /**
-     * Applies the configured sorting strategy to the specified column.
-     * @param columnName The name of the column to sort.
-     * @param direction The direction to sort ('asc' or 'desc').
-     */
-    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;
-    /**
-     * Gets the current sort state of a column using the configured sorting strategy.
-     * @param columnName The name of the column to check.
-     * @returns A promise that resolves to 'asc', 'desc', or 'none'.
-     */
-    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
-  };
-
-  /**
-   * Generate an AI-friendly configuration prompt for debugging.
-   * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
-   * Automatically throws an Error containing the prompt.
-   */
-  generateConfig: () => Promise<void>;
-
-  /**
-   * @deprecated Use \`generateConfig()\` instead. Will be removed in v7.0.0.
-   */
-  generateConfigPrompt: () => Promise<void>;
-}
-`;