Greptile Summary

This PR introduces comprehensive Shadow DOM support to Stagehand, enabling interaction with elements inside both open and closed shadow roots. The implementation addresses multiple user-reported issues where Stagehand previously returned 'not-supported' errors for shadow DOM elements.

The solution uses a multi-layered approach: (1) JavaScript injection that intercepts Element.prototype.attachShadow early in the page lifecycle to capture closed shadow roots in a WeakMap, (2) a global window.__stagehand__ backdoor API providing safe access to closed shadow roots without DOM mutations, (3) a custom Playwright selector engine 'stagehand' that performs depth-first search traversal across regular DOM nodes, open shadow roots via el.shadowRoot, and closed roots via the backdoor API.

The feature integrates throughout the codebase by adding experimental flag support to all handlers (ActHandler, ExtractHandler, ObserveHandler), modifying XPath generation to include shadow root markers using '//' syntax, enhancing accessibility tree building to traverse shadow boundaries, and adding specialized error classes for shadow DOM failures. Eight comprehensive evaluation tests validate different combinations of shadow DOM modes (open/closed) with iframe contexts (OOPIF/SPIF).

The implementation is gated behind the experimental: true flag in the Stagehand constructor to prevent breaking existing behavior and is not yet available on the API. This architectural choice allows users to opt into the enhanced functionality while maintaining backward compatibility for production environments.

Confidence score: 3/5

• This PR introduces significant complexity with experimental shadow DOM support that could cause issues if not thoroughly tested in production scenarios
• Score reflects the experimental nature of the feature and potential edge cases in shadow DOM traversal, especially with the global window object modification and WeakMap approach
• Pay close attention to lib/StagehandPage.ts where shadow DOM detection logic may incorrectly identify elements, and evaluate files that lack proper return statements for failure cases

_{17 files reviewed, 10 comments}

_{Edit Code Review Bot Settings | Greptile}