@rickcedwhat/playwright-smart-table 5.1.0 → 5.2.0

package/README.md

@@ -117,7 +117,7 @@ await expect(row).toBeVisible();
 ```
 <!-- /embed: advanced-debug -->
 
-This will log header mappings, row scans, and pagination triggers to help troubleshoot issues.
+This will log header mappings, row scans, and pagination triggers to the console, and slow down operations to help you see what's happening.
 
 ### Resetting Table State
 
@@ -922,8 +922,8 @@ export interface TableConfig {
   headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;
   /** Automatically scroll to table on init */
   autoScroll?: boolean;
-  /** Enable debug logs */
-  debug?: boolean;
+  /** Debug options for development and troubleshooting */
+  debug?: DebugConfig;
   /** Reset hook */
   onReset?: (context: TableContext) => Promise<void>;
   /** All interaction strategies */

package/dist/filterEngine.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FilterEngine = void 0;
+const stringUtils_1 = require("./utils/stringUtils");
 class FilterEngine {
     constructor(config, resolve) {
         this.config = config;
@@ -17,7 +18,7 @@ class FilterEngine {
             const colIndex = map.get(colName);
             // TODO: Use ColumnStrategy for better resolution error handling
             if (colIndex === undefined) {
-                throw new Error(`Filter Error: Column "${colName}" not found.`);
+                throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, Array.from(map.keys())));
             }
             const filterVal = typeof value === 'number' ? String(value) : value;
             // Use strategy if provided (For future: configured filter strategies)

package/dist/smartRow.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSmartRow = void 0;
 const fill_1 = require("./strategies/fill");
 const stringUtils_1 = require("./utils/stringUtils");
-const traceUtils_1 = require("./utils/traceUtils");
+const debugUtils_1 = require("./utils/debugUtils");
 /**
  * Factory to create a SmartRow by extending a Playwright Locator.
  * We avoid Class/Proxy to ensure full compatibility with Playwright's expect(locator) matchers.
@@ -36,8 +36,6 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 page: rootLocator.page()
             });
         }
-        // Add trace event
-        (0, traceUtils_1.addTraceEvent)(rootLocator.page(), 'getCell', { column: colName, columnIndex: idx, rowIndex }).catch(() => { });
         return resolve(config.cellSelector, rowLocator).nth(idx);
     };
     smart.toJSON = (options) => __awaiter(void 0, void 0, void 0, function* () {
@@ -115,10 +113,13 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
         return result;
     });
     smart.smartFill = (data, fillOptions) => __awaiter(void 0, void 0, void 0, function* () {
+        (0, debugUtils_1.logDebug)(config, 'info', 'Filling row', data);
         for (const [colName, value] of Object.entries(data)) {
+            if (value === undefined)
+                continue;
             const colIdx = map.get(colName);
             if (colIdx === undefined) {
-                throw new Error(`Column "${colName}" not found in fill data.`);
+                throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, Array.from(map.keys())));
             }
             yield config.strategies.cellNavigation({
                 config: config,
@@ -131,6 +132,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 rowIndex: rowIndex
             });
             const strategy = config.strategies.fill || fill_1.FillStrategies.default;
+            (0, debugUtils_1.logDebug)(config, 'verbose', `Filling cell "${colName}" with value`, value);
             yield strategy({
                 row: smart,
                 columnName: colName,
@@ -141,7 +143,10 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 table: table,
                 fillOptions
             });
+            // Delay after filling
+            yield (0, debugUtils_1.debugDelay)(config, 'getCell');
         }
+        (0, debugUtils_1.logDebug)(config, 'info', 'Row fill complete');
     });
     smart.bringIntoView = () => __awaiter(void 0, void 0, void 0, function* () {
         if (rowIndex === undefined) {

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\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 * 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  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\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 }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Enable debug logs */\n  debug?: boolean;\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: boolean;\n  headerTransformer: (args: { text: string, index: number, locator: Locator }) => 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\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   * ASYNC: Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * @param options - Filter and formatting options\n   */\n  getRows: <R extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\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: SmartRow[];\n      allData: T[];\n      table: RestrictedTableResult;\n      batchInfo?: {\n        startIndex: number;\n        endIndex: number;\n        size: number;\n      };\n    }) => T | Promise<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  ) => Promise<T[]>;\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 * 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  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\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 }) => 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 }) => 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\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   * ASYNC: Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * @param options - Filter and formatting options\n   */\n  getRows: <R extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\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: SmartRow[];\n      allData: T[];\n      table: RestrictedTableResult;\n      batchInfo?: {\n        startIndex: number;\n        endIndex: number;\n        size: number;\n      };\n    }) => T | Promise<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  ) => Promise<T[]>;\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

@@ -133,6 +133,31 @@ export interface SortingStrategy {
   }): 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 {
   root: Locator;
   config: FinalTableConfig;
@@ -221,8 +246,8 @@ export interface TableConfig {
   headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;
   /** Automatically scroll to table on init */
   autoScroll?: boolean;
-  /** Enable debug logs */
-  debug?: boolean;
+  /** Debug options for development and troubleshooting */
+  debug?: DebugConfig;
   /** Reset hook */
   onReset?: (context: TableContext) => Promise<void>;
   /** All interaction strategies */
@@ -235,7 +260,7 @@ export interface FinalTableConfig extends TableConfig {
   cellSelector: string;
   maxPages: number;
   autoScroll: boolean;
-  debug: boolean;
+  debug?: TableConfig['debug'];
   headerTransformer: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;
   onReset: (context: TableContext) => Promise<void>;
   strategies: TableStrategies;

package/dist/types.d.ts

@@ -118,6 +118,30 @@ export interface SortingStrategy {
         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 {
     root: Locator;
     config: FinalTableConfig;
@@ -206,8 +230,8 @@ export interface TableConfig {
     }) => string | Promise<string>;
     /** Automatically scroll to table on init */
     autoScroll?: boolean;
-    /** Enable debug logs */
-    debug?: boolean;
+    /** Debug options for development and troubleshooting */
+    debug?: DebugConfig;
     /** Reset hook */
     onReset?: (context: TableContext) => Promise<void>;
     /** All interaction strategies */
@@ -219,7 +243,7 @@ export interface FinalTableConfig extends TableConfig {
     cellSelector: string;
     maxPages: number;
     autoScroll: boolean;
-    debug: boolean;
+    debug?: TableConfig['debug'];
     headerTransformer: (args: {
         text: string;
         index: number;

package/dist/useTable.js

@@ -26,7 +26,7 @@ Object.defineProperty(exports, "ResolutionStrategies", { enumerable: true, get:
 const strategies_1 = require("./strategies");
 Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
 const validation_1 = require("./strategies/validation");
-const traceUtils_1 = require("./utils/traceUtils");
+const debugUtils_1 = require("./utils/debugUtils");
 /**
  * Main hook to interact with a table.
  */
@@ -41,7 +41,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         cellNavigation: columns_1.CellNavigationStrategies.default,
         pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }),
     };
-    const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "thead th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { }) }, configOptions), { strategies: Object.assign(Object.assign({}, defaultStrategies), configOptions.strategies) });
+    const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "thead th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text, index, locator }) => 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) => {
         if (typeof item === 'string')
             return parent.locator(item);
@@ -54,9 +54,8 @@ const useTable = (rootLocator, configOptions = {}) => {
     let _hasPaginated = false;
     let _isInitialized = false;
     // Helpers
-    const logDebug = (msg) => {
-        if (config.debug)
-            console.log(`🔎 [SmartTable Debug] ${msg}`);
+    const log = (msg) => {
+        (0, debugUtils_1.logDebug)(config, 'verbose', msg); // Legacy(`🔎 [SmartTable Debug] ${msg}`);
     };
     const _createColumnError = (colName, map, context) => {
         const availableColumns = Array.from(map.keys());
@@ -81,7 +80,7 @@ const useTable = (rootLocator, configOptions = {}) => {
     const _getMap = (timeout) => __awaiter(void 0, void 0, void 0, function* () {
         if (_headerMap)
             return _headerMap;
-        logDebug('Mapping headers...');
+        log('Mapping headers...');
         const headerTimeout = timeout !== null && timeout !== void 0 ? timeout : 3000;
         if (config.autoScroll) {
             try {
@@ -113,8 +112,25 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return [text, i];
         })));
+        // 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);
-        logDebug(`Mapped ${entries.length} columns: ${JSON.stringify(entries.map(e => e[0]))}`);
+        log(`Mapped ${entries.length} columns: ${JSON.stringify(entries.map(e => e[0]))}`);
         return _headerMap;
     });
     // Placeholder for the final table object
@@ -130,13 +146,13 @@ const useTable = (rootLocator, configOptions = {}) => {
         const map = yield _getMap();
         const effectiveMaxPages = (_a = options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages;
         let currentPage = 1;
-        logDebug(`Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
+        log(`Looking for row: ${JSON.stringify(filters)} (MaxPages: ${effectiveMaxPages})`);
         while (true) {
             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();
-            logDebug(`Page ${currentPage}: Found ${count} matches.`);
+            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 = [];
@@ -156,7 +172,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             if (count === 1)
                 return matchedRows.first();
             if (currentPage < effectiveMaxPages) {
-                logDebug(`Page ${currentPage}: Not found. Attempting pagination...`);
+                log(`Page ${currentPage}: Not found. Attempting pagination...`);
                 const context = {
                     root: rootLocator,
                     config: config,
@@ -171,7 +187,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                     continue;
                 }
                 else {
-                    logDebug(`Page ${currentPage}: Pagination failed (end of data).`);
+                    log(`Page ${currentPage}: Pagination failed (end of data).`);
                 }
             }
             if (_hasPaginated) {
@@ -224,11 +240,15 @@ const useTable = (rootLocator, configOptions = {}) => {
         init: (options) => __awaiter(void 0, void 0, void 0, function* () {
             if (_isInitialized && _headerMap)
                 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) {
-                yield (0, traceUtils_1.addTraceEvent)(rootLocator.page(), 'init', { headers: Array.from(_headerMap.keys()), columnCount: _headerMap.size });
+                (0, debugUtils_1.logDebug)(config, 'info', `Table initialized with ${_headerMap.size} columns`, Array.from(_headerMap.keys()));
+                // Trace event removed - redundant with debug logging
             }
+            yield (0, debugUtils_1.debugDelay)(config, 'default');
             return result;
         }),
         scrollToColumn: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
@@ -259,19 +279,19 @@ const useTable = (rootLocator, configOptions = {}) => {
             return resolve(config.headerSelector, rootLocator).nth(idx);
         }),
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
-            logDebug("Resetting table...");
+            log("Resetting table...");
             const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
             yield config.onReset(context);
             _hasPaginated = false;
             _headerMap = null;
             _isInitialized = false;
-            logDebug("Table reset complete.");
+            log("Table reset complete.");
         }),
         revalidate: () => __awaiter(void 0, void 0, void 0, function* () {
-            logDebug("Revalidating table structure...");
+            log("Revalidating table structure...");
             _headerMap = null; // Clear the map to force re-scanning
             yield _getMap(); // Re-scan headers
-            logDebug("Table revalidated.");
+            log("Table revalidated.");
         }),
         getColumnValues: (column, options) => __awaiter(void 0, void 0, void 0, function* () {
             var _a, _b;
@@ -283,7 +303,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages;
             let currentPage = 1;
             const results = [];
-            logDebug(`Getting column values for '${column}' (Pages: ${effectiveMaxPages})`);
+            log(`Getting column values for '${column}' (Pages: ${effectiveMaxPages})`);
             while (true) {
                 const rows = yield resolve(config.rowSelector, rootLocator).all();
                 for (const row of rows) {
@@ -320,11 +340,18 @@ const useTable = (rootLocator, configOptions = {}) => {
             return _makeSmart(rowLocator, _headerMap, rowIndex);
         },
         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) {
-                row = resolve(config.rowSelector, rootLocator).filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
+            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);
         }),
         getRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
@@ -383,7 +410,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 yield _ensureInitialized();
                 if (!config.strategies.sorting)
                     throw new Error('No sorting strategy has been configured.');
-                logDebug(`Applying sort for column "${columnName}" (${direction})`);
+                log(`Applying sort for column "${columnName}" (${direction})`);
                 const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
                 yield config.strategies.sorting.doSort({ columnName, direction, context });
             }),
@@ -430,7 +457,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             let seenKeys = null;
             let batchRows = [];
             let batchStartIndex = 0;
-            logDebug(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations}, batchSize: ${batchSize !== null && batchSize !== void 0 ? batchSize : 'none'})`);
+            log(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations}, batchSize: ${batchSize !== null && batchSize !== void 0 ? batchSize : 'none'})`);
             while (index < effectiveMaxIterations) {
                 const rowLocators = yield resolve(config.rowSelector, rootLocator).all();
                 let rows = rowLocators.map((loc, i) => _makeSmart(loc, _headerMap, i));
@@ -446,7 +473,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                         }
                     }
                     rows = deduplicated;
-                    logDebug(`Deduplicated ${rowLocators.length} rows to ${rows.length} unique rows (total seen: ${seenKeys.size})`);
+                    log(`Deduplicated ${rowLocators.length} rows to ${rows.length} unique rows (total seen: ${seenKeys.size})`);
                 }
                 // Add rows to batch if batching is enabled
                 if (isBatching) {
@@ -485,13 +512,15 @@ const useTable = (rootLocator, configOptions = {}) => {
                     if (!isLastIteration) {
                         const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
                         paginationResult = yield paginationStrategy(context);
+                        (0, debugUtils_1.logDebug)(config, 'info', `Pagination ${paginationResult ? 'succeeded' : 'failed'}`);
+                        yield (0, debugUtils_1.debugDelay)(config, 'pagination');
                         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 });
                     }
                     if (finalIsLast || !paginationResult) {
-                        logDebug(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
+                        log(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
                         break;
                     }
                     // Reset batch
@@ -504,6 +533,8 @@ const useTable = (rootLocator, configOptions = {}) => {
                     // Continue paginating even when batching
                     const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
                     paginationResult = yield paginationStrategy(context);
+                    (0, debugUtils_1.logDebug)(config, 'info', `Pagination ${paginationResult ? 'succeeded' : 'failed'} (batching mode)`);
+                    yield (0, debugUtils_1.debugDelay)(config, 'pagination');
                     if (!paginationResult) {
                         // Pagination failed, invoke callback with current batch
                         const callbackIndex = batchStartIndex;
@@ -530,14 +561,14 @@ const useTable = (rootLocator, configOptions = {}) => {
                         if (options === null || options === void 0 ? void 0 : options.afterLast) {
                             yield options.afterLast({ index: callbackIndex, rows: batchRows, allData });
                         }
-                        logDebug(`Pagination failed mid-batch (index: ${index})`);
+                        log(`Pagination failed mid-batch (index: ${index})`);
                         break;
                     }
                 }
                 index++;
-                logDebug(`Iteration ${index} completed, continuing...`);
+                log(`Iteration ${index} completed, continuing...`);
             }
-            logDebug(`iterateThroughTable completed after ${index + 1} iterations, collected ${allData.length} items`);
+            log(`iterateThroughTable completed after ${index + 1} iterations, collected ${allData.length} items`);
             return allData;
         }),
     };

package/dist/utils/debugUtils.d.ts

@@ -0,0 +1,17 @@
+import type { FinalTableConfig } from '../types';
+/**
+ * Get delay for specific action type
+ */
+export declare function getDebugDelay(config: FinalTableConfig, actionType: 'pagination' | 'getCell' | 'findRow' | 'default'): number;
+/**
+ * Add debug delay for specific action type
+ */
+export declare function debugDelay(config: FinalTableConfig, actionType: 'pagination' | 'getCell' | 'findRow' | 'default'): Promise<void>;
+/**
+ * Log debug message based on log level
+ */
+export declare function logDebug(config: FinalTableConfig, level: 'error' | 'info' | 'verbose', message: string, data?: any): void;
+/**
+ * Warn if debug.slow is enabled in CI environment
+ */
+export declare function warnIfDebugInCI(config: FinalTableConfig): void;

package/dist/utils/debugUtils.js

@@ -0,0 +1,62 @@
+"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.getDebugDelay = getDebugDelay;
+exports.debugDelay = debugDelay;
+exports.logDebug = logDebug;
+exports.warnIfDebugInCI = warnIfDebugInCI;
+/**
+ * Get delay for specific action type
+ */
+function getDebugDelay(config, actionType) {
+    var _a, _b, _c;
+    if (!((_a = config.debug) === null || _a === void 0 ? void 0 : _a.slow))
+        return 0;
+    if (typeof config.debug.slow === 'number') {
+        return config.debug.slow;
+    }
+    return (_c = (_b = config.debug.slow[actionType]) !== null && _b !== void 0 ? _b : config.debug.slow.default) !== null && _c !== void 0 ? _c : 0;
+}
+/**
+ * Add debug delay for specific action type
+ */
+function debugDelay(config, actionType) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const delay = getDebugDelay(config, actionType);
+        if (delay > 0) {
+            yield new Promise(resolve => setTimeout(resolve, delay));
+        }
+    });
+}
+/**
+ * Log debug message based on log level
+ */
+function logDebug(config, level, message, data) {
+    var _a, _b;
+    const logLevel = (_b = (_a = config.debug) === null || _a === void 0 ? void 0 : _a.logLevel) !== null && _b !== void 0 ? _b : 'none';
+    const levels = { none: 0, error: 1, info: 2, verbose: 3 };
+    if (levels[logLevel] >= levels[level]) {
+        const prefix = level === 'error' ? '❌' : level === 'info' ? 'ℹ️' : '🔍';
+        const timestamp = new Date().toISOString().split('T')[1].split('.')[0];
+        console.log(`${prefix} [${timestamp}] [SmartTable] ${message}`, data !== null && data !== void 0 ? data : '');
+    }
+}
+/**
+ * Warn if debug.slow is enabled in CI environment
+ */
+function warnIfDebugInCI(config) {
+    var _a;
+    if (process.env.CI === 'true' && ((_a = config.debug) === null || _a === void 0 ? void 0 : _a.slow)) {
+        console.warn('⚠️  [SmartTable] Warning: debug.slow is enabled in CI environment.\n' +
+            '   This will significantly slow down test execution.\n' +
+            '   Consider disabling debug mode in CI.');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Production-ready table testing for Playwright with smart column-aware locators. Core library with plugin support for custom table implementations.",
   "repository": {
     "type": "git",