bb-browser-api 0.11.5

package/packages/shared/buildDomTree.js

@@ -0,0 +1,1501 @@
+window.buildDomTree = (
+  args = {
+    showHighlightElements: true,
+    focusHighlightIndex: -1,
+    viewportExpansion: 0,
+    debugMode: false,
+    startId: 0,
+    startHighlightIndex: 0,
+  },
+) => {
+  const { showHighlightElements, focusHighlightIndex, viewportExpansion, startHighlightIndex, startId, debugMode } =
+    args;
+  // Make sure to do highlight elements always, but we can hide the highlights if needed
+  const doHighlightElements = true;
+
+  let highlightIndex = startHighlightIndex; // Reset highlight index
+
+  // Add caching mechanisms at the top level
+  const DOM_CACHE = {
+    boundingRects: new WeakMap(),
+    clientRects: new WeakMap(),
+    computedStyles: new WeakMap(),
+    clearCache: () => {
+      DOM_CACHE.boundingRects = new WeakMap();
+      DOM_CACHE.clientRects = new WeakMap();
+      DOM_CACHE.computedStyles = new WeakMap();
+    },
+  };
+
+  /**
+   * Gets the cached bounding rect for an element.
+   *
+   * @param {HTMLElement} element - The element to get the bounding rect for.
+   * @returns {DOMRect | null} The cached bounding rect, or null if the element is not found.
+   */
+  function getCachedBoundingRect(element) {
+    if (!element) return null;
+
+    if (DOM_CACHE.boundingRects.has(element)) {
+      return DOM_CACHE.boundingRects.get(element);
+    }
+
+    const rect = element.getBoundingClientRect();
+
+    if (rect) {
+      DOM_CACHE.boundingRects.set(element, rect);
+    }
+    return rect;
+  }
+
+  /**
+   * Gets the cached computed style for an element.
+   *
+   * @param {HTMLElement} element - The element to get the computed style for.
+   * @returns {CSSStyleDeclaration | null} The cached computed style, or null if the element is not found.
+   */
+  function getCachedComputedStyle(element) {
+    if (!element) return null;
+
+    if (DOM_CACHE.computedStyles.has(element)) {
+      return DOM_CACHE.computedStyles.get(element);
+    }
+
+    const style = window.getComputedStyle(element);
+
+    if (style) {
+      DOM_CACHE.computedStyles.set(element, style);
+    }
+    return style;
+  }
+
+  /**
+   * Gets the cached client rects for an element.
+   *
+   * @param {HTMLElement} element - The element to get the client rects for.
+   * @returns {DOMRectList | null} The cached client rects, or null if the element is not found.
+   */
+  function getCachedClientRects(element) {
+    if (!element) return null;
+
+    if (DOM_CACHE.clientRects.has(element)) {
+      return DOM_CACHE.clientRects.get(element);
+    }
+
+    const rects = element.getClientRects();
+
+    if (rects) {
+      DOM_CACHE.clientRects.set(element, rects);
+    }
+    return rects;
+  }
+
+  /**
+   * Hash map of DOM nodes indexed by their highlight index.
+   *
+   * @type {Object<string, any>}
+   */
+  const DOM_HASH_MAP = {};
+
+  const ID = { current: startId };
+
+  const HIGHLIGHT_CONTAINER_ID = 'playwright-highlight-container';
+
+  // Clean up any previous highlights before building a new tree
+  if (window._highlightCleanupFunctions && window._highlightCleanupFunctions.length) {
+    window._highlightCleanupFunctions.forEach(fn => { try { fn(); } catch {} });
+    window._highlightCleanupFunctions = [];
+  }
+  const existingContainer = document.getElementById(HIGHLIGHT_CONTAINER_ID);
+  if (existingContainer) existingContainer.remove();
+
+  // Add a WeakMap cache for XPath strings
+  const xpathCache = new WeakMap();
+
+  // // Initialize once and reuse
+  // const viewportObserver = new IntersectionObserver(
+  //   (entries) => {
+  //     entries.forEach(entry => {
+  //       elementVisibilityMap.set(entry.target, entry.isIntersecting);
+  //     });
+  //   },
+  //   { rootMargin: `${viewportExpansion}px` }
+  // );
+
+  /**
+   * Highlights an element in the DOM and returns the index of the next element.
+   *
+   * @param {HTMLElement} element - The element to highlight.
+   * @param {number} index - The index of the element.
+   * @param {HTMLElement | null} parentIframe - The parent iframe node.
+   * @returns {number} The index of the next element.
+   */
+  function highlightElement(element, index, parentIframe = null) {
+    if (!element) return index;
+
+    const overlays = [];
+    /**
+     * @type {HTMLElement | null}
+     */
+    let label = null;
+    let labelWidth = 20;
+    let labelHeight = 16;
+    let cleanupFn = null;
+
+    try {
+      // Create or get highlight container
+      let container = document.getElementById(HIGHLIGHT_CONTAINER_ID);
+      if (!container) {
+        container = document.createElement('div');
+        container.id = HIGHLIGHT_CONTAINER_ID;
+        container.style.position = 'fixed';
+        container.style.pointerEvents = 'none';
+        container.style.top = '0';
+        container.style.left = '0';
+        container.style.width = '100%';
+        container.style.height = '100%';
+        // Use the maximum valid value in zIndex to ensure the element is not blocked by overlapping elements.
+        container.style.zIndex = '2147483647';
+        container.style.backgroundColor = 'transparent';
+        // Show or hide the container based on the showHighlightElements flag
+        container.style.display = showHighlightElements ? 'block' : 'none';
+        document.body.appendChild(container);
+      }
+
+      // Get element client rects
+      const rects = element.getClientRects(); // Use getClientRects()
+
+      if (!rects || rects.length === 0) return index; // Exit if no rects
+
+      // Generate a color based on the index
+      const colors = [
+        '#FF0000',
+        '#00FF00',
+        '#0000FF',
+        '#FFA500',
+        '#800080',
+        '#008080',
+        '#FF69B4',
+        '#4B0082',
+        '#FF4500',
+        '#2E8B57',
+        '#DC143C',
+        '#4682B4',
+      ];
+      const colorIndex = index % colors.length;
+      const baseColor = colors[colorIndex];
+      const backgroundColor = baseColor + '1A'; // 10% opacity version of the color
+
+      // Get iframe offset if necessary
+      let iframeOffset = { x: 0, y: 0 };
+      if (parentIframe) {
+        const iframeRect = parentIframe.getBoundingClientRect(); // Keep getBoundingClientRect for iframe offset
+        iframeOffset.x = iframeRect.left;
+        iframeOffset.y = iframeRect.top;
+      }
+
+      // Create fragment to hold overlay elements
+      const fragment = document.createDocumentFragment();
+
+      // Create highlight overlays for each client rect
+      for (const rect of rects) {
+        if (rect.width === 0 || rect.height === 0) continue; // Skip empty rects
+
+        const overlay = document.createElement('div');
+        overlay.style.position = 'fixed';
+        overlay.style.border = `2px solid ${baseColor}`;
+        overlay.style.backgroundColor = backgroundColor;
+        overlay.style.pointerEvents = 'none';
+        overlay.style.boxSizing = 'border-box';
+
+        const top = rect.top + iframeOffset.y;
+        const left = rect.left + iframeOffset.x;
+
+        overlay.style.top = `${top}px`;
+        overlay.style.left = `${left}px`;
+        overlay.style.width = `${rect.width}px`;
+        overlay.style.height = `${rect.height}px`;
+
+        fragment.appendChild(overlay);
+        overlays.push({ element: overlay, initialRect: rect }); // Store overlay and its rect
+      }
+
+      // Create and position a single label relative to the first rect
+      const firstRect = rects[0];
+      label = document.createElement('div');
+      label.className = 'playwright-highlight-label';
+      label.style.position = 'fixed';
+      label.style.background = baseColor;
+      label.style.color = 'white';
+      label.style.padding = '1px 4px';
+      label.style.borderRadius = '4px';
+      label.style.fontSize = `${Math.min(12, Math.max(8, firstRect.height / 2))}px`;
+      label.textContent = index.toString();
+
+      labelWidth = label.offsetWidth > 0 ? label.offsetWidth : labelWidth; // Update actual width if possible
+      labelHeight = label.offsetHeight > 0 ? label.offsetHeight : labelHeight; // Update actual height if possible
+
+      const firstRectTop = firstRect.top + iframeOffset.y;
+      const firstRectLeft = firstRect.left + iframeOffset.x;
+
+      let labelTop = firstRectTop + 2;
+      let labelLeft = firstRectLeft + firstRect.width - labelWidth - 2;
+
+      // Adjust label position if first rect is too small
+      if (firstRect.width < labelWidth + 4 || firstRect.height < labelHeight + 4) {
+        labelTop = firstRectTop - labelHeight - 2;
+        labelLeft = firstRectLeft + firstRect.width - labelWidth; // Align with right edge
+        if (labelLeft < iframeOffset.x) labelLeft = firstRectLeft; // Prevent going off-left
+      }
+
+      // Ensure label stays within viewport bounds slightly better
+      labelTop = Math.max(0, Math.min(labelTop, window.innerHeight - labelHeight));
+      labelLeft = Math.max(0, Math.min(labelLeft, window.innerWidth - labelWidth));
+
+      label.style.top = `${labelTop}px`;
+      label.style.left = `${labelLeft}px`;
+
+      fragment.appendChild(label);
+
+      // Update positions on scroll/resize
+      const updatePositions = () => {
+        const newRects = element.getClientRects(); // Get fresh rects
+        let newIframeOffset = { x: 0, y: 0 };
+
+        if (parentIframe) {
+          const iframeRect = parentIframe.getBoundingClientRect(); // Keep getBoundingClientRect for iframe
+          newIframeOffset.x = iframeRect.left;
+          newIframeOffset.y = iframeRect.top;
+        }
+
+        // Update each overlay
+        overlays.forEach((overlayData, i) => {
+          if (i < newRects.length) {
+            // Check if rect still exists
+            const newRect = newRects[i];
+            const newTop = newRect.top + newIframeOffset.y;
+            const newLeft = newRect.left + newIframeOffset.x;
+
+            overlayData.element.style.top = `${newTop}px`;
+            overlayData.element.style.left = `${newLeft}px`;
+            overlayData.element.style.width = `${newRect.width}px`;
+            overlayData.element.style.height = `${newRect.height}px`;
+            overlayData.element.style.display = newRect.width === 0 || newRect.height === 0 ? 'none' : 'block';
+          } else {
+            // If fewer rects now, hide extra overlays
+            overlayData.element.style.display = 'none';
+          }
+        });
+
+        // If there are fewer new rects than overlays, hide the extras
+        if (newRects.length < overlays.length) {
+          for (let i = newRects.length; i < overlays.length; i++) {
+            overlays[i].element.style.display = 'none';
+          }
+        }
+
+        // Update label position based on the first new rect
+        if (label && newRects.length > 0) {
+          const firstNewRect = newRects[0];
+          const firstNewRectTop = firstNewRect.top + newIframeOffset.y;
+          const firstNewRectLeft = firstNewRect.left + newIframeOffset.x;
+
+          let newLabelTop = firstNewRectTop + 2;
+          let newLabelLeft = firstNewRectLeft + firstNewRect.width - labelWidth - 2;
+
+          if (firstNewRect.width < labelWidth + 4 || firstNewRect.height < labelHeight + 4) {
+            newLabelTop = firstNewRectTop - labelHeight - 2;
+            newLabelLeft = firstNewRectLeft + firstNewRect.width - labelWidth;
+            if (newLabelLeft < newIframeOffset.x) newLabelLeft = firstNewRectLeft;
+          }
+
+          // Ensure label stays within viewport bounds
+          newLabelTop = Math.max(0, Math.min(newLabelTop, window.innerHeight - labelHeight));
+          newLabelLeft = Math.max(0, Math.min(newLabelLeft, window.innerWidth - labelWidth));
+
+          label.style.top = `${newLabelTop}px`;
+          label.style.left = `${newLabelLeft}px`;
+          label.style.display = 'block';
+        } else if (label) {
+          // Hide label if element has no rects anymore
+          label.style.display = 'none';
+        }
+      };
+
+      const throttleFunction = (func, delay) => {
+        let lastCall = 0;
+        return (...args) => {
+          const now = performance.now();
+          if (now - lastCall < delay) return;
+          lastCall = now;
+          return func(...args);
+        };
+      };
+
+      const throttledUpdatePositions = throttleFunction(updatePositions, 16); // ~60fps
+      window.addEventListener('scroll', throttledUpdatePositions, true);
+      window.addEventListener('resize', throttledUpdatePositions);
+
+      // Add cleanup function
+      cleanupFn = () => {
+        window.removeEventListener('scroll', throttledUpdatePositions, true);
+        window.removeEventListener('resize', throttledUpdatePositions);
+        // Remove overlay elements if needed
+        overlays.forEach(overlay => overlay.element.remove());
+        if (label) label.remove();
+      };
+
+      // Then add fragment to container in one operation
+      container.appendChild(fragment);
+
+      return index + 1;
+    } finally {
+      // Store cleanup function for later use
+      if (cleanupFn) {
+        // Keep a reference to cleanup functions in a global array
+        (window._highlightCleanupFunctions = window._highlightCleanupFunctions || []).push(cleanupFn);
+      }
+    }
+  }
+
+  /**
+   * Gets the position of an element in its parent.
+   *
+   * @param {HTMLElement} currentElement - The element to get the position for.
+   * @returns {number} The position of the element in its parent.
+   */
+  function getElementPosition(currentElement) {
+    if (!currentElement.parentElement) {
+      return 0; // No parent means no siblings
+    }
+
+    const tagName = currentElement.nodeName.toLowerCase();
+
+    const siblings = Array.from(currentElement.parentElement.children).filter(
+      sib => sib.nodeName.toLowerCase() === tagName,
+    );
+
+    if (siblings.length === 1) {
+      return 0; // Only element of its type
+    }
+
+    const index = siblings.indexOf(currentElement) + 1; // 1-based index
+    return index;
+  }
+
+  function getXPathTree(element, stopAtBoundary = true) {
+    if (xpathCache.has(element)) return xpathCache.get(element);
+
+    const segments = [];
+    let currentElement = element;
+
+    while (currentElement && currentElement.nodeType === Node.ELEMENT_NODE) {
+      // Stop if we hit a shadow root or iframe
+      if (
+        stopAtBoundary &&
+        (currentElement.parentNode instanceof ShadowRoot || currentElement.parentNode instanceof HTMLIFrameElement)
+      ) {
+        break;
+      }
+
+      const position = getElementPosition(currentElement);
+      const tagName = currentElement.nodeName.toLowerCase();
+      const xpathIndex = position > 0 ? `[${position}]` : '';
+      segments.unshift(`${tagName}${xpathIndex}`);
+
+      currentElement = currentElement.parentNode;
+    }
+
+    const result = segments.join('/');
+    xpathCache.set(element, result);
+    return result;
+  }
+
+  /**
+   * Checks if a text node is visible.
+   *
+   * @param {Text} textNode - The text node to check.
+   * @returns {boolean} Whether the text node is visible.
+   */
+  function isTextNodeVisible(textNode) {
+    try {
+      // Special case: when viewportExpansion is -1, consider all text nodes as visible
+      if (viewportExpansion === -1) {
+        // Still check parent visibility for basic filtering
+        const parentElement = textNode.parentElement;
+        if (!parentElement) return false;
+
+        try {
+          return parentElement.checkVisibility({
+            checkOpacity: true,
+            checkVisibilityCSS: true,
+          });
+        } catch (e) {
+          // Fallback if checkVisibility is not supported
+          const style = window.getComputedStyle(parentElement);
+          return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+        }
+      }
+
+      const range = document.createRange();
+      range.selectNodeContents(textNode);
+      const rects = range.getClientRects(); // Use getClientRects for Range
+
+      if (!rects || rects.length === 0) {
+        return false;
+      }
+
+      let isAnyRectVisible = false;
+      let isAnyRectInViewport = false;
+
+      for (const rect of rects) {
+        // Check size
+        if (rect.width > 0 && rect.height > 0) {
+          isAnyRectVisible = true;
+
+          // Viewport check for this rect
+          if (
+            !(
+              rect.bottom < -viewportExpansion ||
+              rect.top > window.innerHeight + viewportExpansion ||
+              rect.right < -viewportExpansion ||
+              rect.left > window.innerWidth + viewportExpansion
+            )
+          ) {
+            isAnyRectInViewport = true;
+            break; // Found a visible rect in viewport, no need to check others
+          }
+        }
+      }
+
+      if (!isAnyRectVisible || !isAnyRectInViewport) {
+        return false;
+      }
+
+      // Check parent visibility
+      const parentElement = textNode.parentElement;
+      if (!parentElement) return false;
+
+      try {
+        return parentElement.checkVisibility({
+          checkOpacity: true,
+          checkVisibilityCSS: true,
+        });
+      } catch (e) {
+        // Fallback if checkVisibility is not supported
+        const style = window.getComputedStyle(parentElement);
+        return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+      }
+    } catch (e) {
+      console.warn('Error checking text node visibility:', e);
+      return false;
+    }
+  }
+
+  /**
+   * Checks if an element is accepted.
+   *
+   * @param {HTMLElement} element - The element to check.
+   * @returns {boolean} Whether the element is accepted.
+   */
+  function isElementAccepted(element) {
+    if (!element || !element.tagName) return false;
+
+    // Always accept body and common container elements
+    const alwaysAccept = new Set(['body', 'div', 'main', 'article', 'section', 'nav', 'header', 'footer']);
+    const tagName = element.tagName.toLowerCase();
+
+    if (alwaysAccept.has(tagName)) return true;
+
+    const leafElementDenyList = new Set(['svg', 'script', 'style', 'link', 'meta', 'noscript', 'template']);
+
+    return !leafElementDenyList.has(tagName);
+  }
+
+  /**
+   * Checks if an element is visible.
+   *
+   * @param {HTMLElement} element - The element to check.
+   * @returns {boolean} Whether the element is visible.
+   */
+  function isElementVisible(element) {
+    const style = getCachedComputedStyle(element);
+    return (
+      element.offsetWidth > 0 && element.offsetHeight > 0 && style?.visibility !== 'hidden' && style?.display !== 'none'
+    );
+  }
+
+  /**
+   * Checks if an element is interactive.
+   *
+   * lots of comments, and uncommented code - to show the logic of what we already tried
+   *
+   * One of the things we tried at the beginning was also to use event listeners, and other fancy class, style stuff -> what actually worked best was just combining most things with computed cursor style :)
+   *
+   * @param {HTMLElement} element - The element to check.
+   */
+  function isInteractiveElement(element) {
+    if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+      return false;
+    }
+
+    // Cache the tagName and style lookups
+    const tagName = element.tagName.toLowerCase();
+    const style = getCachedComputedStyle(element);
+
+    // Define interactive cursors
+    const interactiveCursors = new Set([
+      'pointer', // Link/clickable elements
+      'move', // Movable elements
+      'text', // Text selection
+      'grab', // Grabbable elements
+      'grabbing', // Currently grabbing
+      'cell', // Table cell selection
+      'copy', // Copy operation
+      'alias', // Alias creation
+      'all-scroll', // Scrollable content
+      'col-resize', // Column resize
+      'context-menu', // Context menu available
+      'crosshair', // Precise selection
+      'e-resize', // East resize
+      'ew-resize', // East-west resize
+      'help', // Help available
+      'n-resize', // North resize
+      'ne-resize', // Northeast resize
+      'nesw-resize', // Northeast-southwest resize
+      'ns-resize', // North-south resize
+      'nw-resize', // Northwest resize
+      'nwse-resize', // Northwest-southeast resize
+      'row-resize', // Row resize
+      's-resize', // South resize
+      'se-resize', // Southeast resize
+      'sw-resize', // Southwest resize
+      'vertical-text', // Vertical text selection
+      'w-resize', // West resize
+      'zoom-in', // Zoom in
+      'zoom-out', // Zoom out
+    ]);
+
+    // Define non-interactive cursors
+    const nonInteractiveCursors = new Set([
+      'not-allowed', // Action not allowed
+      'no-drop', // Drop not allowed
+      'wait', // Processing
+      'progress', // In progress
+      'initial', // Initial value
+      'inherit', // Inherited value
+      //? Let's just include all potentially clickable elements that are not specifically blocked
+      // 'none',        // No cursor
+      // 'default',     // Default cursor
+      // 'auto',        // Browser default
+    ]);
+
+    /**
+     * Checks if an element has an interactive pointer.
+     *
+     * @param {HTMLElement} element - The element to check.
+     * @returns {boolean} Whether the element has an interactive pointer.
+     */
+    function doesElementHaveInteractivePointer(element) {
+      if (element.tagName.toLowerCase() === 'html') return false;
+
+      if (style?.cursor && interactiveCursors.has(style.cursor)) return true;
+
+      return false;
+    }
+
+    let isInteractiveCursor = doesElementHaveInteractivePointer(element);
+
+    // Genius fix for almost all interactive elements
+    if (isInteractiveCursor) {
+      return true;
+    }
+
+    const interactiveElements = new Set([
+      'a', // Links
+      'button', // Buttons
+      'input', // All input types (text, checkbox, radio, etc.)
+      'select', // Dropdown menus
+      'textarea', // Text areas
+      'details', // Expandable details
+      'summary', // Summary element (clickable part of details)
+      'label', // Form labels (often clickable)
+      'option', // Select options
+      'optgroup', // Option groups
+      'fieldset', // Form fieldsets (can be interactive with legend)
+      'legend', // Fieldset legends
+    ]);
+
+    // Define explicit disable attributes and properties
+    const explicitDisableTags = new Set([
+      'disabled', // Standard disabled attribute
+      // 'aria-disabled',      // ARIA disabled state
+      'readonly', // Read-only state
+      // 'aria-readonly',     // ARIA read-only state
+      // 'aria-hidden',       // Hidden from accessibility
+      // 'hidden',            // Hidden attribute
+      // 'inert',             // Inert attribute
+      // 'aria-inert',        // ARIA inert state
+      // 'tabindex="-1"',     // Removed from tab order
+      // 'aria-hidden="true"' // Hidden from screen readers
+    ]);
+
+    // handle inputs, select, checkbox, radio, textarea, button and make sure they are not cursor style disabled/not-allowed
+    if (interactiveElements.has(tagName)) {
+      // Check for non-interactive cursor
+      if (style?.cursor && nonInteractiveCursors.has(style.cursor)) {
+        return false;
+      }
+
+      // Check for explicit disable attributes
+      for (const disableTag of explicitDisableTags) {
+        if (
+          element.hasAttribute(disableTag) ||
+          element.getAttribute(disableTag) === 'true' ||
+          element.getAttribute(disableTag) === ''
+        ) {
+          return false;
+        }
+      }
+
+      // Check for disabled property on form elements
+      if (element.disabled) {
+        return false;
+      }
+
+      // Check for readonly property on form elements
+      if (element.readOnly) {
+        return false;
+      }
+
+      // Check for inert property
+      if (element.inert) {
+        return false;
+      }
+
+      return true;
+    }
+
+    const role = element.getAttribute('role');
+    const ariaRole = element.getAttribute('aria-role');
+
+    // Check for contenteditable attribute
+    if (element.getAttribute('contenteditable') === 'true' || element.isContentEditable) {
+      return true;
+    }
+
+    // Added enhancement to capture dropdown interactive elements
+    if (
+      element.classList &&
+      (element.classList.contains('button') ||
+        element.classList.contains('dropdown-toggle') ||
+        element.getAttribute('data-index') ||
+        element.getAttribute('data-toggle') === 'dropdown' ||
+        element.getAttribute('aria-haspopup') === 'true')
+    ) {
+      return true;
+    }
+
+    const interactiveRoles = new Set([
+      'button', // Directly clickable element
+      // 'link',            // Clickable link
+      'menu', // Menu container (ARIA menus)
+      'menubar', // Menu bar container
+      'menuitem', // Clickable menu item
+      'menuitemradio', // Radio-style menu item (selectable)
+      'menuitemcheckbox', // Checkbox-style menu item (toggleable)
+      'radio', // Radio button (selectable)
+      'checkbox', // Checkbox (toggleable)
+      'tab', // Tab (clickable to switch content)
+      'switch', // Toggle switch (clickable to change state)
+      'slider', // Slider control (draggable)
+      'spinbutton', // Number input with up/down controls
+      'combobox', // Dropdown with text input
+      'searchbox', // Search input field
+      'textbox', // Text input field
+      'listbox', // Selectable list
+      'option', // Selectable option in a list
+      'scrollbar', // Scrollable control
+    ]);
+
+    // Basic role/attribute checks
+    const hasInteractiveRole =
+      interactiveElements.has(tagName) ||
+      (role && interactiveRoles.has(role)) ||
+      (ariaRole && interactiveRoles.has(ariaRole));
+
+    if (hasInteractiveRole) return true;
+
+    // check whether element has event listeners by window.getEventListeners
+    try {
+      if (typeof getEventListeners === 'function') {
+        const listeners = getEventListeners(element);
+        const mouseEvents = ['click', 'mousedown', 'mouseup', 'dblclick'];
+        for (const eventType of mouseEvents) {
+          if (listeners[eventType] && listeners[eventType].length > 0) {
+            return true; // Found a mouse interaction listener
+          }
+        }
+      }
+
+      const getEventListenersForNode =
+        element?.ownerDocument?.defaultView?.getEventListenersForNode || window.getEventListenersForNode;
+      if (typeof getEventListenersForNode === 'function') {
+        const listeners = getEventListenersForNode(element);
+        const interactionEvents = [
+          'click',
+          'mousedown',
+          'mouseup',
+          'keydown',
+          'keyup',
+          'submit',
+          'change',
+          'input',
+          'focus',
+          'blur',
+        ];
+        for (const eventType of interactionEvents) {
+          for (const listener of listeners) {
+            if (listener.type === eventType) {
+              return true; // Found a common interaction listener
+            }
+          }
+        }
+      }
+      // Fallback: Check common event attributes if getEventListeners is not available (getEventListeners doesn't work in page.evaluate context)
+      const commonMouseAttrs = ['onclick', 'onmousedown', 'onmouseup', 'ondblclick'];
+      for (const attr of commonMouseAttrs) {
+        if (element.hasAttribute(attr) || typeof element[attr] === 'function') {
+          return true;
+        }
+      }
+    } catch (e) {
+      // console.warn(`Could not check event listeners for ${element.tagName}:`, e);
+      // If checking listeners fails, rely on other checks
+    }
+
+    return false;
+  }
+
+  /**
+   * Checks if an element is the topmost element at its position.
+   *
+   * @param {HTMLElement} element - The element to check.
+   * @returns {boolean} Whether the element is the topmost element at its position.
+   */
+  function isTopElement(element) {
+    // Special case: when viewportExpansion is -1, consider all elements as "top" elements
+    if (viewportExpansion === -1) {
+      return true;
+    }
+
+    const rects = getCachedClientRects(element); // Replace element.getClientRects()
+
+    if (!rects || rects.length === 0) {
+      return false; // No geometry, cannot be top
+    }
+
+    let isAnyRectInViewport = false;
+    for (const rect of rects) {
+      // Use the same logic as isInExpandedViewport check
+      if (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        !(
+          // Only check non-empty rects
+          (
+            rect.bottom < -viewportExpansion ||
+            rect.top > window.innerHeight + viewportExpansion ||
+            rect.right < -viewportExpansion ||
+            rect.left > window.innerWidth + viewportExpansion
+          )
+        )
+      ) {
+        isAnyRectInViewport = true;
+        break;
+      }
+    }
+
+    if (!isAnyRectInViewport) {
+      return false; // All rects are outside the viewport area
+    }
+
+    // Find the correct document context and root element
+    let doc = element.ownerDocument;
+
+    // If we're in an iframe, elements are considered top by default
+    if (doc !== window.document) {
+      return true;
+    }
+
+    // For shadow DOM, we need to check within its own root context
+    const shadowRoot = element.getRootNode();
+    if (shadowRoot instanceof ShadowRoot) {
+      const centerX = rects[Math.floor(rects.length / 2)].left + rects[Math.floor(rects.length / 2)].width / 2;
+      const centerY = rects[Math.floor(rects.length / 2)].top + rects[Math.floor(rects.length / 2)].height / 2;
+
+      try {
+        const topEl = shadowRoot.elementFromPoint(centerX, centerY);
+        if (!topEl) return false;
+
+        let current = topEl;
+        while (current && current !== shadowRoot) {
+          if (current === element) return true;
+          current = current.parentElement;
+        }
+        return false;
+      } catch (e) {
+        return true;
+      }
+    }
+
+    const margin = 5;
+    const rect = rects[Math.floor(rects.length / 2)];
+
+    // For elements in viewport, check if they're topmost. Do the check in the
+    // center of the element and at the corners to ensure we catch more cases.
+    const checkPoints = [
+      // Initially only this was used, but it was not enough
+      { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+      { x: rect.left + margin, y: rect.top + margin }, // top left
+      // { x: rect.right - margin, y: rect.top + margin },    // top right
+      // { x: rect.left + margin, y: rect.bottom - margin },  // bottom left
+      { x: rect.right - margin, y: rect.bottom - margin }, // bottom right
+    ];
+
+    return checkPoints.some(({ x, y }) => {
+      try {
+        const topEl = document.elementFromPoint(x, y);
+        if (!topEl) return false;
+
+        let current = topEl;
+        while (current && current !== document.documentElement) {
+          if (current === element) return true;
+          current = current.parentElement;
+        }
+        return false;
+      } catch (e) {
+        return true;
+      }
+    });
+  }
+
+  /**
+   * Checks if an element is within the expanded viewport.
+   *
+   * @param {HTMLElement} element - The element to check.
+   * @param {number} viewportExpansion - The viewport expansion.
+   * @returns {boolean} Whether the element is within the expanded viewport.
+   */
+  function isInExpandedViewport(element, viewportExpansion) {
+    if (viewportExpansion === -1) {
+      return true;
+    }
+
+    const rects = element.getClientRects(); // Use getClientRects
+
+    if (!rects || rects.length === 0) {
+      // Fallback to getBoundingClientRect if getClientRects is empty,
+      // useful for elements like <svg> that might not have client rects but have a bounding box.
+      const boundingRect = getCachedBoundingRect(element);
+      if (!boundingRect || boundingRect.width === 0 || boundingRect.height === 0) {
+        return false;
+      }
+      return !(
+        boundingRect.bottom < -viewportExpansion ||
+        boundingRect.top > window.innerHeight + viewportExpansion ||
+        boundingRect.right < -viewportExpansion ||
+        boundingRect.left > window.innerWidth + viewportExpansion
+      );
+    }
+
+    // Check if *any* client rect is within the viewport
+    for (const rect of rects) {
+      if (rect.width === 0 || rect.height === 0) continue; // Skip empty rects
+
+      if (
+        !(
+          rect.bottom < -viewportExpansion ||
+          rect.top > window.innerHeight + viewportExpansion ||
+          rect.right < -viewportExpansion ||
+          rect.left > window.innerWidth + viewportExpansion
+        )
+      ) {
+        return true; // Found at least one rect in the viewport
+      }
+    }
+
+    return false; // No rects were found in the viewport
+  }
+
+  // /**
+  //  * Gets the effective scroll of an element.
+  //  *
+  //  * @param {HTMLElement} element - The element to get the effective scroll for.
+  //  * @returns {Object} The effective scroll of the element.
+  //  */
+  // function getEffectiveScroll(element) {
+  //   let currentEl = element;
+  //   let scrollX = 0;
+  //   let scrollY = 0;
+
+  //   while (currentEl && currentEl !== document.documentElement) {
+  //     if (currentEl.scrollLeft || currentEl.scrollTop) {
+  //       scrollX += currentEl.scrollLeft;
+  //       scrollY += currentEl.scrollTop;
+  //     }
+  //     currentEl = currentEl.parentElement;
+  //   }
+
+  //   scrollX += window.scrollX;
+  //   scrollY += window.scrollY;
+
+  //   return { scrollX, scrollY };
+  // }
+
+  /**
+   * Checks if an element is an interactive candidate.
+   *
+   * @param {HTMLElement} element - The element to check.
+   * @returns {boolean} Whether the element is an interactive candidate.
+   */
+  function isInteractiveCandidate(element) {
+    if (!element || element.nodeType !== Node.ELEMENT_NODE) return false;
+
+    const tagName = element.tagName.toLowerCase();
+
+    // Fast-path for common interactive elements
+    const interactiveElements = new Set(['a', 'button', 'input', 'select', 'textarea', 'details', 'summary', 'label']);
+
+    if (interactiveElements.has(tagName)) return true;
+
+    // Quick attribute checks without getting full lists
+    const hasQuickInteractiveAttr =
+      element.hasAttribute('onclick') ||
+      element.hasAttribute('role') ||
+      element.hasAttribute('tabindex') ||
+      element.hasAttribute('aria-') ||
+      element.hasAttribute('data-action') ||
+      element.getAttribute('contenteditable') === 'true';
+
+    return hasQuickInteractiveAttr;
+  }
+
+  // --- Define constants for distinct interaction check ---
+  const DISTINCT_INTERACTIVE_TAGS = new Set([
+    'a',
+    'button',
+    'input',
+    'select',
+    'textarea',
+    'summary',
+    'details',
+    'label',
+    'option',
+  ]);
+  const INTERACTIVE_ROLES = new Set([
+    'button',
+    'link',
+    'menuitem',
+    'menuitemradio',
+    'menuitemcheckbox',
+    'radio',
+    'checkbox',
+    'tab',
+    'switch',
+    'slider',
+    'spinbutton',
+    'combobox',
+    'searchbox',
+    'textbox',
+    'listbox',
+    'option',
+    'scrollbar',
+  ]);
+
+  /**
+   * Heuristically determines if an element should be considered as independently interactive,
+   * even if it's nested inside another interactive container.
+   *
+   * This function helps detect deeply nested actionable elements (e.g., menu items within a button)
+   * that may not be picked up by strict interactivity checks.
+   *
+   * @param {HTMLElement} element - The element to check.
+   * @returns {boolean} Whether the element is heuristically interactive.
+   */
+  function isHeuristicallyInteractive(element) {
+    if (!element || element.nodeType !== Node.ELEMENT_NODE) return false;
+
+    // Skip non-visible elements early for performance
+    if (!isElementVisible(element)) return false;
+
+    // Check for common attributes that often indicate interactivity
+    const hasInteractiveAttributes =
+      element.hasAttribute('role') ||
+      element.hasAttribute('tabindex') ||
+      element.hasAttribute('onclick') ||
+      typeof element.onclick === 'function';
+
+    // Check for semantic class names suggesting interactivity
+    const hasInteractiveClass = /\b(btn|clickable|menu|item|entry|link)\b/i.test(element.className || '');
+
+    // Determine whether the element is inside a known interactive container
+    const isInKnownContainer = Boolean(element.closest('button,a,[role="button"],.menu,.dropdown,.list,.toolbar'));
+
+    // Ensure the element has at least one visible child (to avoid marking empty wrappers)
+    const hasVisibleChildren = [...element.children].some(isElementVisible);
+
+    // Avoid highlighting elements whose parent is <body> (top-level wrappers)
+    const isParentBody = element.parentElement && element.parentElement.isSameNode(document.body);
+
+    return (
+      (isInteractiveElement(element) || hasInteractiveAttributes || hasInteractiveClass) &&
+      hasVisibleChildren &&
+      isInKnownContainer &&
+      !isParentBody
+    );
+  }
+
+  /**
+   * Checks if an element likely represents a distinct interaction
+   * separate from its parent (if the parent is also interactive).
+   *
+   * @param {HTMLElement} element - The element to check.
+   * @returns {boolean} Whether the element is a distinct interaction.
+   */
+  function isElementDistinctInteraction(element) {
+    if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+      return false;
+    }
+
+    const tagName = element.tagName.toLowerCase();
+    const role = element.getAttribute('role');
+
+    // Check if it's an iframe - always distinct boundary
+    if (tagName === 'iframe') {
+      return true;
+    }
+
+    // Check tag name
+    if (DISTINCT_INTERACTIVE_TAGS.has(tagName)) {
+      return true;
+    }
+    // Check interactive roles
+    if (role && INTERACTIVE_ROLES.has(role)) {
+      return true;
+    }
+    // Check contenteditable
+    if (element.isContentEditable || element.getAttribute('contenteditable') === 'true') {
+      return true;
+    }
+    // Check for common testing/automation attributes
+    if (element.hasAttribute('data-testid') || element.hasAttribute('data-cy') || element.hasAttribute('data-test')) {
+      return true;
+    }
+    // Check for explicit onclick handler (attribute or property)
+    if (element.hasAttribute('onclick') || typeof element.onclick === 'function') {
+      return true;
+    }
+
+    // return false
+
+    // Check for other common interaction event listeners
+    try {
+      const getEventListenersForNode =
+        element?.ownerDocument?.defaultView?.getEventListenersForNode || window.getEventListenersForNode;
+      if (typeof getEventListenersForNode === 'function') {
+        const listeners = getEventListenersForNode(element);
+        const interactionEvents = [
+          'click',
+          'mousedown',
+          'mouseup',
+          'keydown',
+          'keyup',
+          'submit',
+          'change',
+          'input',
+          'focus',
+          'blur',
+        ];
+        for (const eventType of interactionEvents) {
+          for (const listener of listeners) {
+            if (listener.type === eventType) {
+              return true; // Found a common interaction listener
+            }
+          }
+        }
+      }
+      // Fallback: Check common event attributes if getEventListeners is not available (getEventListenersForNode doesn't work in page.evaluate context)
+      const commonEventAttrs = [
+        'onmousedown',
+        'onmouseup',
+        'onkeydown',
+        'onkeyup',
+        'onsubmit',
+        'onchange',
+        'oninput',
+        'onfocus',
+        'onblur',
+      ];
+      if (commonEventAttrs.some(attr => element.hasAttribute(attr))) {
+        return true;
+      }
+    } catch (e) {
+      // console.warn(`Could not check event listeners for ${element.tagName}:`, e);
+      // If checking listeners fails, rely on other checks
+    }
+
+    // if the element is not strictly interactive but appears clickable based on heuristic signals
+    if (isHeuristicallyInteractive(element)) {
+      return true;
+    }
+
+    // Default to false: if it's interactive but doesn't match above,
+    // assume it triggers the same action as the parent.
+    return false;
+  }
+  // --- End distinct interaction check ---
+
+  /**
+   * Handles the logic for deciding whether to highlight an element and performing the highlight.
+   * @param {
+    {
+        tagName: string;
+        attributes: Record<string, string>;
+        xpath: any;
+        children: never[];
+        isVisible?: boolean;
+        isTopElement?: boolean;
+        isInteractive?: boolean;
+        isInViewport?: boolean;
+        highlightIndex?: number;
+        shadowRoot?: boolean;
+   }} nodeData - The node data object.
+   * @param {HTMLElement} node - The node to highlight.
+   * @param {HTMLElement | null} parentIframe - The parent iframe node.
+   * @param {boolean} isParentHighlighted - Whether the parent node is highlighted.
+   * @returns {boolean} Whether the element was highlighted.
+   */
+  function handleHighlighting(nodeData, node, parentIframe, isParentHighlighted) {
+    if (!nodeData.isInteractive) return false; // Not interactive, definitely don't highlight
+
+    let shouldHighlight = false;
+    if (!isParentHighlighted) {
+      // Parent wasn't highlighted, this interactive node can be highlighted.
+      shouldHighlight = true;
+    } else {
+      // Parent *was* highlighted. Only highlight this node if it represents a distinct interaction.
+      if (isElementDistinctInteraction(node)) {
+        shouldHighlight = true;
+      } else {
+        // console.log(`Skipping highlight for ${nodeData.tagName} (parent highlighted)`);
+        shouldHighlight = false;
+      }
+    }
+
+    if (shouldHighlight) {
+      // Check viewport status before assigning index and highlighting
+      nodeData.isInViewport = isInExpandedViewport(node, viewportExpansion);
+
+      // When viewportExpansion is -1, all interactive elements should get a highlight index
+      // regardless of viewport status
+      if (nodeData.isInViewport || viewportExpansion === -1) {
+        nodeData.highlightIndex = highlightIndex++;
+
+        if (doHighlightElements) {
+          if (focusHighlightIndex >= 0) {
+            if (focusHighlightIndex === nodeData.highlightIndex) {
+              highlightElement(node, nodeData.highlightIndex, parentIframe);
+            }
+          } else {
+            highlightElement(node, nodeData.highlightIndex, parentIframe);
+          }
+          return true; // Successfully highlighted
+        }
+      } else {
+        // console.log(`Skipping highlight for ${nodeData.tagName} (outside viewport)`);
+      }
+    }
+
+    return false; // Did not highlight
+  }
+
+  /**
+   * Creates a node data object for a given node and its descendants.
+   *
+   * @param {HTMLElement} node - The node to process.
+   * @param {HTMLElement | null} parentIframe - The parent iframe node.
+   * @param {boolean} isParentHighlighted - Whether the parent node is highlighted.
+   * @returns {string | null} The ID of the node data object, or null if the node is not processed.
+   */
+  const MAX_DEPTH = 100;
+  let visitedNodes;
+
+  function buildDomTree(node, parentIframe = null, isParentHighlighted = false, depth = 0) {
+    // Initialize visited nodes tracking on first call
+    if (!visitedNodes) {
+      visitedNodes = new WeakSet();
+    }
+
+    // Prevent infinite recursion
+    if (depth > MAX_DEPTH) {
+      return null;
+    }
+
+    // Fast rejection checks first
+    if (
+      !node ||
+      node.id === HIGHLIGHT_CONTAINER_ID ||
+      (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.TEXT_NODE)
+    ) {
+      return null;
+    }
+
+    // Prevent circular references (only for valid nodes)
+    if (node.nodeType === Node.ELEMENT_NODE && visitedNodes.has(node)) {
+      return null;
+    }
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      visitedNodes.add(node);
+    }
+
+    // Special handling for root node (body)
+    if (node === document.body) {
+      const nodeData = {
+        tagName: 'body',
+        attributes: {},
+        xpath: '/body',
+        children: [],
+      };
+
+      // Process children of body
+      for (const child of Array.from(node.childNodes)) {
+        const domElement = buildDomTree(child, parentIframe, false, depth + 1); // Body's children have no highlighted parent initially
+        if (domElement) nodeData.children.push(domElement);
+      }
+
+      const id = `${ID.current++}`;
+      DOM_HASH_MAP[id] = nodeData;
+      return id;
+    }
+
+    // Early bailout for non-element nodes except text
+    if (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.TEXT_NODE) {
+      return null;
+    }
+
+    // Process text nodes
+    if (node.nodeType === Node.TEXT_NODE) {
+      const textContent = node.textContent?.trim();
+      if (!textContent) {
+        return null;
+      }
+
+      // Only check visibility for text nodes that might be visible
+      const parentElement = node.parentElement;
+      if (!parentElement || parentElement.tagName.toLowerCase() === 'script') {
+        return null;
+      }
+
+      const id = `${ID.current++}`;
+      DOM_HASH_MAP[id] = {
+        type: 'TEXT_NODE',
+        text: textContent,
+        isVisible: isTextNodeVisible(node),
+      };
+      return id;
+    }
+
+    // Quick checks for element nodes
+    if (node.nodeType === Node.ELEMENT_NODE && !isElementAccepted(node)) {
+      return null;
+    }
+
+    // Early viewport check - only filter out elements clearly outside viewport
+    // The getBoundingClientRect() of the Shadow DOM host element may return width/height = 0
+    if (viewportExpansion !== -1 && !node.shadowRoot) {
+      const rect = getCachedBoundingRect(node); // Keep for initial quick check
+      const style = getCachedComputedStyle(node);
+
+      // Skip viewport check for fixed/sticky elements as they may appear anywhere
+      const isFixedOrSticky = style && (style.position === 'fixed' || style.position === 'sticky');
+
+      // Check if element has actual dimensions using offsetWidth/Height (quick check)
+      const hasSize = node.offsetWidth > 0 || node.offsetHeight > 0;
+
+      // Use getBoundingClientRect for the quick OUTSIDE check.
+      // isInExpandedViewport will do the more accurate check later if needed.
+      if (
+        !rect ||
+        (!isFixedOrSticky &&
+          !hasSize &&
+          (rect.bottom < -viewportExpansion ||
+            rect.top > window.innerHeight + viewportExpansion ||
+            rect.right < -viewportExpansion ||
+            rect.left > window.innerWidth + viewportExpansion))
+      ) {
+        // console.log("Skipping node outside viewport (quick check):", node.tagName, rect);
+        return null;
+      }
+    }
+
+    /**
+     * @type {
+      {
+          tagName: string;
+          attributes: Record<string, string | null>;
+          xpath: any;
+          children: never[];
+          isVisible?: boolean;
+          isTopElement?: boolean;
+          isInteractive?: boolean;
+          isInViewport?: boolean;
+          highlightIndex?: number;
+          shadowRoot?: boolean;
+      }
+    } nodeData - The node data object.
+     */
+    const nodeData = {
+      tagName: node.tagName.toLowerCase(),
+      attributes: {},
+      xpath: getXPathTree(node, true),
+      children: [],
+    };
+
+    // Get attributes for interactive elements or potential text containers
+    if (
+      isInteractiveCandidate(node) ||
+      node.tagName.toLowerCase() === 'iframe' ||
+      node.tagName.toLowerCase() === 'body'
+    ) {
+      const attributeNames = node.getAttributeNames?.() || [];
+      for (const name of attributeNames) {
+        const value = node.getAttribute(name);
+        nodeData.attributes[name] = value;
+      }
+    }
+
+    let nodeWasHighlighted = false;
+    // Perform visibility, interactivity, and highlighting checks
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      nodeData.isVisible = isElementVisible(node); // isElementVisible uses offsetWidth/Height, which is fine
+      if (nodeData.isVisible) {
+        nodeData.isTopElement = isTopElement(node);
+
+        // Special handling for ARIA menu containers - check interactivity even if not top element
+        const role = node.getAttribute('role');
+        const isMenuContainer = role === 'menu' || role === 'menubar' || role === 'listbox';
+
+        if (nodeData.isTopElement || isMenuContainer) {
+          nodeData.isInteractive = isInteractiveElement(node);
+          // Call the dedicated highlighting function
+          nodeWasHighlighted = handleHighlighting(nodeData, node, parentIframe, isParentHighlighted);
+        }
+      }
+    }
+
+    // Process children, with special handling for iframes and rich text editors
+    if (node.tagName) {
+      const tagName = node.tagName.toLowerCase();
+
+      // Handle iframes
+      if (tagName === 'iframe') {
+        const rect = getCachedBoundingRect(node);
+        nodeData.attributes['computedHeight'] = String(Math.ceil(rect.height));
+        nodeData.attributes['computedWidth'] = String(Math.ceil(rect.width));
+
+        // Check if iframe should be skipped (invisible tracking/ad iframes)
+        const shouldSkipIframe =
+          // Invisible iframes (1x1 pixel or similar)
+          (rect.width <= 1 && rect.height <= 1) ||
+          // Positioned off-screen
+          rect.left < -1000 ||
+          rect.top < -1000;
+
+        // Early detection for sandboxed iframes
+        const sandbox = node.getAttribute('sandbox');
+        const isSandboxed = sandbox !== null;
+        const isRestrictiveSandbox = isSandboxed && !sandbox.includes('allow-same-origin');
+
+        if (shouldSkipIframe) {
+          // Skip processing invisible/tracking iframes entirely
+          nodeData.attributes['skipped'] = 'invisible-tracking-iframe';
+        } else if (isRestrictiveSandbox) {
+          // Set error directly for sandboxed iframes we know will fail
+          nodeData.attributes['error'] = 'Cross-origin iframe access blocked by sandbox';
+        } else {
+          // Only attempt access for iframes that might succeed
+          try {
+            const iframeDoc = node.contentDocument || node.contentWindow?.document;
+            if (iframeDoc && iframeDoc.childNodes) {
+              for (const child of Array.from(iframeDoc.childNodes)) {
+                const domElement = buildDomTree(child, node, false, depth + 1);
+                if (domElement) nodeData.children.push(domElement);
+              }
+            }
+          } catch (e) {
+            nodeData.attributes['error'] = e.message;
+            // Only log unexpected errors, not predictable ones
+            if (!e.message.includes('cross-origin') && !e.message.includes('origin "null"')) {
+              console.warn('Unable to access iframe:', e);
+            }
+          }
+        }
+      }
+      // Handle rich text editors and contenteditable elements
+      else if (
+        node.isContentEditable ||
+        node.getAttribute('contenteditable') === 'true' ||
+        node.id === 'tinymce' ||
+        node.classList.contains('mce-content-body') ||
+        (tagName === 'body' && node.getAttribute('data-id')?.startsWith('mce_'))
+      ) {
+        // Process all child nodes to capture formatted text
+        for (const child of Array.from(node.childNodes)) {
+          const domElement = buildDomTree(child, parentIframe, nodeWasHighlighted, depth + 1);
+          if (domElement) nodeData.children.push(domElement);
+        }
+      } else {
+        // Handle shadow DOM
+        if (node.shadowRoot) {
+          nodeData.shadowRoot = true;
+          for (const child of Array.from(node.shadowRoot.childNodes)) {
+            const domElement = buildDomTree(child, parentIframe, nodeWasHighlighted, depth + 1);
+            if (domElement) nodeData.children.push(domElement);
+          }
+        }
+        // Handle regular elements
+        for (const child of Array.from(node.childNodes)) {
+          // Pass the highlighted status of the *current* node to its children
+          const passHighlightStatusToChild = nodeWasHighlighted || isParentHighlighted;
+          const domElement = buildDomTree(child, parentIframe, passHighlightStatusToChild, depth + 1);
+          if (domElement) nodeData.children.push(domElement);
+        }
+      }
+    }
+
+    // Skip empty anchor tags only if they have no dimensions and no children
+    if (nodeData.tagName === 'a' && nodeData.children.length === 0 && !nodeData.attributes.href) {
+      // Check if the anchor has actual dimensions
+      const rect = getCachedBoundingRect(node);
+      const hasSize = (rect && rect.width > 0 && rect.height > 0) || node.offsetWidth > 0 || node.offsetHeight > 0;
+
+      if (!hasSize) {
+        return null;
+      }
+    }
+
+    const id = `${ID.current++}`;
+    DOM_HASH_MAP[id] = nodeData;
+    return id;
+  }
+
+  // Reset visited nodes for new DOM tree build
+  visitedNodes = null;
+  const rootId = buildDomTree(document.body);
+
+  // Clear the cache before starting
+  DOM_CACHE.clearCache();
+
+  return { rootId, map: DOM_HASH_MAP };
+};