core-browser-automation

## Selector Strategy (Stability First) - **Priority 1**: `data-testid`, `data-test`, `data-cy`, `id` (if stable). - **Priority 2**: Accessible roles with names (e.g., `getByRole('button', { name: 'Submit' })`). - **Priority 3**: Text content (e.g., `getByText('Submit')`) - use with caution if text is dynamic. - **Avoid**: Brittle CSS selectors (e.g., `div > div:nth-child(3)`), XPath, or selectors tied to visual layout. ## Waiting Strategy (No Flaky Sleeps) - **Explicit Waits**: Wait for elements to be **attached**, **visible**, and **enabled** before interacting. - **State Changes**: Wait for clear UI signals (spinners disappearing, success messages appearing). - **Bounded Polling**: If no clear signal exists, use a loop with a short sleep (1-2s) and a max retry count. - **Avoid**: Long blind sleeps (e.g., `sleep(5000)`). ## Evidence Capture Hygiene - When a tool accepts a `filename`, prefer a **simple filename** (e.g., `tab2-detail-limit-200.png`) rather than passing a full/relative directory path; some environments will prepend their own output directory and can accidentally create nested paths. ## Scroll Strategy - **Window vs. Container**: Determine if the scrollbar belongs to the `window` or a specific container element. - **Incremental Scan**: Scroll in small chunks (e.g., half viewport) to trigger lazy-loading or reveal elements. - **Check after Scroll**: Re-evaluate the page state after scrolling (elements might become visible). ## Handling Overlays & Modals - **D...