dom构建- buildDomTree.js
引言
在自动化测试、可视化辅助工具或浏览器扩展中，精准获取并标记页面中的可交互元素是核心需求。本文档从 DOM 树的构建与遍历出发，依次介绍如何判断元素的可见性与交互性，如何在页面上高亮并标记目标元素，最后阐述性能监控与缓存优化思路，为开发者提供一套全面且高效的实现方案。
1. DOM 树构建
通过递归遍历页面的节点，将每个节点的信息（包括标签名、属性、XPath、子节点等）存入一个全局映射。示例入口为 <body> 元素：
function buildDomTree(node, parentIframe = null, isParentHighlighted = false) {
// 记录当前节点的基础信息
const nodeData = {
tagName: node.nodeType === Node.TEXT_NODE ? '#text' : node.tagName.toLowerCase(),
attributes: {}, // 可根据需要收集元素属性
xpath: getXPath(node), // 生成节点在文档中的 XPath
children: [], // 子节点列表
};
// 递归处理子节点
for (const child of node.childNodes) {
const childId = buildDomTree(child, parentIframe, false);
if (childId) nodeData.children.push(childId);
}
// 将节点信息存入全局映射，并返回唯一 ID
const id = `${ID.current++}`;
DOM_HASH_MAP[id] = nodeData;
return id;
}
- 递归遍历：从根节点开始，深度优先地收集所有子节点。
- 统一存储：使用
DOM_HASH_MAP将节点数据与自增 ID 关联，便于后续快速查找与引用。
2. 元素可见性与交互性分析
在标记可交互元素前，必须先筛选出“可见”且“可交互”的节点。
2.1 可见性判断
判断元素在视口中是否可见，主要依据尺寸与样式属性：
function isElementVisible(element) {
const style = getCachedComputedStyle(element);
return (
element.offsetWidth > 0 &&
element.offsetHeight > 0 &&
style.visibility !== 'hidden' &&
style.display !== 'none'
);
}
- 尺寸检查：
offsetWidth/Height > 0保证元素有实际渲染尺寸。 - 样式检查：
visibility与display属性过滤隐藏或不参与布局的节点。
2.2 交互性判断
综合多种线索，判断元素是否具有用户交互能力：
光标样式
- 白名单（如
pointer,move,text） → 可交互 - 黑名单（如
not-allowed,wait） → 不可交互
- 白名单（如
标签类型
- 常见交互元素：
<a>,<button>,<input>等 - 同时排除
disabled、readonly、inert等属性
- 常见交互元素：
ARIA 与角色
- 通过
role或aria-*属性，识别自定义组件的交互意图
- 通过
事件监听器
if (typeof getEventListeners === 'function') { const listeners = getEventListeners(element); for (const evt of ['click','mousedown','mouseup','dblclick']) { if (listeners[evt]?.length) return true; } } else { // 回退：检查常用 DOM 属性 const attrs = ['onclick','onmousedown','onmouseup','ondblclick']; if (attrs.some(attr => element.hasAttribute(attr))) return true; }特殊组件识别
- 常见 UI 库或框架：
.button、.dropdown-toggle、data-toggle="dropdown"、aria-haspopup="true"等。
- 常见 UI 库或框架：
综合以上几类检测，放进 isInteractiveElement(element) 方法，只有既“可见”又“可交互”的节点，才会进入高亮阶段。
3. 元素高亮与索引标记系统
对筛选出的可交互元素进行可视化高亮，帮助用户快速定位。
3.1 高亮容器与样式
- 容器：创建一个全屏固定定位的
<div>，z-index设置为2147483647，并pointer-events: none避免阻断页面交互。 - 遮罩层：为每个元素生成一个同尺寸的半透明覆盖层，2px 实线边框，高度与宽度同步目标元素。
3.2 索引标签
- 在每个高亮框的左上角，附加一个数字标签，标识元素序号。
- 字号根据元素高度自适应：
font-size = clamp(8px, height/2, 12px)。 - 对于小元素，智能调整标签至元素之外，避免遮挡。
const label = document.createElement('div');
label.className = 'highlight-label';
label.textContent = index;
label.style.fontSize = `${Math.min(12, Math.max(8, rect.height/2))}px`;
// 若元素太小，调整 labelTop/Left
3.3 位置计算与动态更新
- 初次定位：使用
getClientRects()获取元素在视口中的精确区域，多矩形时循环创建多个 overlay。 - Iframe 偏移：若元素在
<iframe>内，通过父 iframe 的getBoundingClientRect()修正坐标。 - 动态更新：监听
scroll（捕获阶段）与resize事件，重新计算所有 overlay 和标签位置，确保高亮始终对齐。
4. 性能监控与缓存机制
面对海量节点与频繁的布局计算，需设计缓存与监控策略。
4.1 缓存计算样式与边界
const DOM_CACHE = {
boundingRects: new WeakMap(), // 缓存 getClientRects 结果
computedStyles: new WeakMap(), // 缓存 getComputedStyle 结果
clearCache() {
this.boundingRects = new WeakMap();
this.computedStyles = new WeakMap();
}
};
- WeakMap 按元素对象自动回收，避免内存泄漏。
- 读取前先查缓存，命中时跳过昂贵的 DOM 计算。
4.2 调试模式性能指标
在开发或调试阶段，收集关键指标帮助优化：
const PERF_METRICS = debugMode ? {
buildDomTreeCalls: 0,
timings: { total: 0, traverse: 0, highlight: 0 },
cacheHits: { rects: 0, styles: 0 },
cacheMisses: { rects: 0, styles: 0 }
} : null;
- 调用计数：统计核心函数（如
buildDomTree、highlightElement）的执行次数。 - 耗时拆分：分别记载遍历、样式计算、绘制 overlay 等耗时。
- 缓存命中率：help identify whether caching strategy effectively reduces重复计算。
dom/dom_tree/index.js
(
args = {
doHighlightElements: true,
focusHighlightIndex: -1,
viewportExpansion: 0,
debugMode: false,
}
) => {
const { doHighlightElements, focusHighlightIndex, viewportExpansion, debugMode } = args;
let highlightIndex = 0; // 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: 0 };
const HIGHLIGHT_CONTAINER_ID = "playwright-highlight-container";
// 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';
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);
}
}
}
// // Add this function to perform cleanup when needed
// function cleanupHighlights() {
// if (window._highlightCleanupFunctions && window._highlightCleanupFunctions.length) {
// window._highlightCleanupFunctions.forEach(fn => fn());
// window._highlightCleanupFunctions = [];
// }
// // Also remove the container
// const container = document.getElementById(HIGHLIGHT_CONTAINER_ID);
// if (container) container.remove();
// }
/**
* 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
// '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;
}
}
// For elements in viewport, check if they're topmost
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 = document.elementFromPoint(centerX, centerY);
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.
*/
function buildDomTree(node, parentIframe = null, isParentHighlighted = false) {
// Fast rejection checks first
if (!node || node.id === HIGHLIGHT_CONTAINER_ID ||
(node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.TEXT_NODE)) {
return null;
}
if (!node || node.id === HIGHLIGHT_CONTAINER_ID) {
return null;
}
// 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 node.childNodes) {
const domElement = buildDomTree(child, parentIframe, false); // 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);
if (nodeData.isTopElement) {
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") {
try {
const iframeDoc = node.contentDocument || node.contentWindow?.document;
if (iframeDoc) {
for (const child of iframeDoc.childNodes) {
const domElement = buildDomTree(child, node, false);
if (domElement) nodeData.children.push(domElement);
}
}
} catch (e) {
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 node.childNodes) {
const domElement = buildDomTree(child, parentIframe, nodeWasHighlighted);
if (domElement) nodeData.children.push(domElement);
}
}
else {
// Handle shadow DOM
if (node.shadowRoot) {
nodeData.shadowRoot = true;
for (const child of node.shadowRoot.childNodes) {
const domElement = buildDomTree(child, parentIframe, nodeWasHighlighted);
if (domElement) nodeData.children.push(domElement);
}
}
// Handle regular elements
for (const child of node.childNodes) {
// Pass the highlighted status of the *current* node to its children
const passHighlightStatusToChild = nodeWasHighlighted || isParentHighlighted;
const domElement = buildDomTree(child, parentIframe, passHighlightStatusToChild);
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;
}
const rootId = buildDomTree(document.body);
// Clear the cache before starting
DOM_CACHE.clearCache();
return { rootId, map: DOM_HASH_MAP };
};