feat: add shadow DOM support for element identification

[redsquare]

Summary

This PR adds comprehensive shadow DOM support to the element identification utilities, enabling Agentation to work correctly with web components and shadow DOM elements.

Changes

New Utility Functions

• getParentElement(element) - Gets parent element, crossing shadow DOM boundaries
• closestCrossingShadow(element, selector) - Like closest() but crosses shadow boundaries
• isInShadowDOM(element) - Checks if an element is inside a shadow root
• getShadowHost(element) - Gets the shadow host for an element in shadow DOM
• getShadowAwareSelectors(element) - Generates selectors for shadow DOM elements

Updated Functions

• getElementPath() - Now marks shadow boundaries with ⟨shadow⟩ marker and traverses into light DOM
• getFullElementPath() - Updated to traverse shadow boundaries correctly
• getNearbyElements() - Updated to use shadow-aware parent traversal
• identifyElement() - Returns contextual identification including shadow DOM info

Test Page

Added /shadow-dom-test page in the example app that verifies:

• isInShadowDOM() detection
• getShadowHost() retrieval
• Shadow boundary markers in element paths
• identifyElement() for shadow DOM elements
• getShadowAwareSelectors() output
• Nested element detection
• Shadow DOM links
• Light DOM control (no false positives)

Testing

1. Run the example app: cd _package-export/example && pnpm run dev
2. Navigate to /shadow-dom-test
3. All 8 tests should show ✓ PASS
4. Try annotating elements inside the shadow DOM - paths should show the ⟨shadow⟩ marker

Use Case

This enables Agentation to work correctly with:

• Custom elements / web components
• Shadow DOM-based UI frameworks
• Design systems using shadow DOM encapsulation
• Chat widgets and other embedded components using shadow DOM

[vercel]

@redsquare is attempting to deploy a commit to the Benji Taylor's Projects Team on Vercel.

A member of the Team first needs to authorize it.