smart_scroll
Scroll elements into view across browsers, virtual lists, and native apps using CDP, UIA, or image-based detection strategies.
Instructions
Purpose: Scroll any element into the viewport — handles nested scroll layers, virtualised lists, sticky-header occlusion, and image-only fallbacks in a single call. Details: Three paths selected by strategy:'auto' (default): (1) CDP (Chrome/Edge): walks scroll ancestor chain, handles overflow:hidden (expandHidden), virtualised lists (TanStack/data-index bisect), detects sticky headers and compensates. (2) UIA (native Windows apps): uses ScrollPattern.SetScrollPercent on ancestor containers then ScrollItemPattern for final snap. (3) Image: binary-search via Win32 GetScrollInfo (exact ratio) or scrollbar-strip pixel sampling (overlay scrollbars), with dHash verification — detects no-op scrolls (Hamming < 5). All paths emit a unified response: ok, path, attempts, pageRatio (0..1), scrolled (bool), ancestors[], viewportPosition. pageRatio is the normalised vertical position of the element on the full page (0=top, 1=bottom). Set verifyWithHash:true to explicitly check that pixels changed (auto-enabled on image path). Nested scroll: ancestors[] is ordered outer→inner; the tool scrolls outer containers first. Virtual lists: set virtualIndex + virtualTotal for O(log n) bisect (≤6 iterations). Prefer: Use instead of scroll_to_element when: content is virtualised (React Virtualized, TanStack Virtual), multiple scroll containers nest, or scroll_to_element returns scrolled:true but the viewport did not actually move. For a simple single-container non-virtual scroll, scroll_to_element is lighter. Caveats: CDP path requires browser_connect. Cross-origin iframes are not traversed (warning returned). expandHidden mutates live CSS (overflow:auto); previous value is stored in data-dt-prev-overflow and restored on the next smart_scroll call (or after 30 s). Image path cannot determine whether the target element is in-view — viewportPosition is null. Call screenshot(detail='text') afterwards to verify. UIA ScrollPattern may not be available in all native apps — falls through to image path. Examples: smart_scroll({target: '#create-release-btn'}) — CDP, nested container, no virtual list smart_scroll({target: '[data-index]', virtualIndex: 500, virtualTotal: 10000}) — TanStack virtual list smart_scroll({target: 'Create Release', windowTitle: 'File Explorer', strategy: 'uia'}) — native UIA smart_scroll({target: 'readme section', windowTitle: 'MyApp', strategy: 'image', hint: 'below'}) — image binary-search
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | CSS selector (Chrome/Edge) or partial UIA name (native apps). For CDP path, must be a valid CSS selector (starts with #, ., tag, or [ ). For UIA path, a partial name match against element Name property. | |
| windowTitle | No | Partial window title. Required for UIA and image paths. For CDP path, optional. | |
| tabId | No | CDP tab ID (Chrome path only). Omit for first page tab. | |
| port | No | CDP port (default 9222) | |
| strategy | No | auto (default): try CDP → UIA → image in order. cdp: Chrome/Edge only. uia: native Windows UIA. image: image + Win32 binary-search. | auto |
| direction | No | Scroll direction. into-view: scroll until target element is visible (default). Other values scroll unconditionally. | into-view |
| inline | No | Vertical alignment after scroll (CDP path). Default: center. | center |
| maxDepth | No | Max number of ancestor scroll containers to walk. Default 3. | |
| retryCount | No | Max scroll attempts (image path binary-search). Default 3, cap 4. | |
| verifyWithHash | No | Verify scroll effectiveness via perceptual hash comparison. Automatically enabled for image path. | |
| virtualIndex | No | Target row index in a virtualised list (0-based). Enables direct TanStack/data-index seeking. | |
| virtualTotal | No | Total row count in a virtualised list. Required when virtualIndex is set. | |
| expandHidden | No | Temporarily set overflow:hidden ancestors to overflow:auto to unlock scroll. Mutates live CSS. | |
| hint | No | Scroll direction hint for binary-search (image path). Seeds lo/hi bounds to reduce attempts. |