hypha-debugger 0.1.1 → 0.1.2

package/dist/hypha-debugger.js

@@ -8903,6 +8903,196 @@
       }
   }
 
+  /**
+   * Animated AI cursor overlay.
+   * Shows a smooth-moving cursor with click ripple animation.
+   * Adapted from @page-agent/page-controller (MIT License).
+   *
+   * The cursor is injected as a fixed overlay and listens for
+   * custom events dispatched by the page-controller actions.
+   */
+  // SVG cursor graphics (inlined to avoid external file dependencies)
+  const CURSOR_BORDER_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="none"><g><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="none" stroke="currentColor" stroke-width="6" stroke-miterlimit="10"/></g></svg>`;
+  const CURSOR_FILL_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><g style="filter: drop-shadow(rgba(0, 0, 0, 0.3) 3px 4px 4px);"><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="#ffffff" stroke="none"/></g></svg>`;
+  const CURSOR_CSS = `
+  .hypha-cursor {
+    position: fixed;
+    width: 50px;
+    height: 50px;
+    pointer-events: none;
+    z-index: 2147483646;
+    transition: opacity 0.2s;
+    opacity: 0;
+  }
+  .hypha-cursor.visible {
+    opacity: 1;
+  }
+  .hypha-cursor-border {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    background: linear-gradient(45deg, rgb(57, 182, 255), rgb(189, 69, 251));
+    mask-image: var(--cursor-border);
+    -webkit-mask-image: var(--cursor-border);
+    mask-size: 100% 100%;
+    -webkit-mask-size: 100% 100%;
+    mask-repeat: no-repeat;
+    -webkit-mask-repeat: no-repeat;
+    transform-origin: center;
+    transform: rotate(-135deg) scale(1.2);
+    margin-left: -10px;
+    margin-top: -14px;
+  }
+  .hypha-cursor-fill {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    background-image: var(--cursor-fill);
+    background-size: 100% 100%;
+    background-repeat: no-repeat;
+    transform-origin: center;
+    transform: rotate(-135deg) scale(1.2);
+    margin-left: -10px;
+    margin-top: -14px;
+  }
+  .hypha-cursor-ripple {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    pointer-events: none;
+    margin-left: -50%;
+    margin-top: -50%;
+  }
+  .hypha-cursor-ripple::after {
+    content: '';
+    opacity: 0;
+    position: absolute;
+    inset: 0;
+    border: 3px solid rgba(57, 182, 255, 1);
+    border-radius: 50%;
+  }
+  .hypha-cursor.clicking .hypha-cursor-ripple::after {
+    animation: hypha-cursor-ripple 400ms ease-out forwards;
+  }
+  @keyframes hypha-cursor-ripple {
+    0% { transform: scale(0); opacity: 1; }
+    100% { transform: scale(2.5); opacity: 0; }
+  }
+`;
+  class AICursor {
+      constructor() {
+          this.currentX = 0;
+          this.currentY = 0;
+          this.targetX = 0;
+          this.targetY = 0;
+          this.animating = false;
+          this.visible = false;
+          this.hideTimeout = null;
+          // Create container (not in Shadow DOM — needs to be on top of everything)
+          this.container = document.createElement("div");
+          this.container.id = "hypha-debugger-cursor";
+          this.container.setAttribute("data-browser-use-ignore", "true");
+          this.container.setAttribute("data-page-agent-ignore", "true");
+          // Inject styles
+          const style = document.createElement("style");
+          style.textContent = CURSOR_CSS;
+          this.container.appendChild(style);
+          // Create cursor element
+          this.cursor = document.createElement("div");
+          this.cursor.className = "hypha-cursor";
+          // Set SVG as CSS custom properties (data URIs for mask-image)
+          const borderDataUri = "url(\"data:image/svg+xml," +
+              encodeURIComponent(CURSOR_BORDER_SVG) +
+              '")';
+          const fillDataUri = "url(\"data:image/svg+xml," +
+              encodeURIComponent(CURSOR_FILL_SVG) +
+              '")';
+          this.cursor.style.setProperty("--cursor-border", borderDataUri);
+          this.cursor.style.setProperty("--cursor-fill", fillDataUri);
+          // Ripple layer (behind cursor)
+          const ripple = document.createElement("div");
+          ripple.className = "hypha-cursor-ripple";
+          this.cursor.appendChild(ripple);
+          // Fill layer (white arrow with shadow)
+          const fill = document.createElement("div");
+          fill.className = "hypha-cursor-fill";
+          this.cursor.appendChild(fill);
+          // Border layer (gradient)
+          const border = document.createElement("div");
+          border.className = "hypha-cursor-border";
+          this.cursor.appendChild(border);
+          this.container.appendChild(this.cursor);
+          document.body.appendChild(this.container);
+          // Listen for move/click events from actions
+          window.addEventListener("HyphaDebugger::MovePointerTo", ((event) => {
+              const { x, y } = event.detail;
+              this.moveTo(x, y);
+          }));
+          window.addEventListener("HyphaDebugger::ClickPointer", () => {
+              this.triggerClickAnimation();
+          });
+      }
+      moveTo(x, y) {
+          this.targetX = x;
+          this.targetY = y;
+          // Show cursor
+          if (!this.visible) {
+              this.visible = true;
+              this.currentX = x;
+              this.currentY = y;
+              this.cursor.style.left = `${x}px`;
+              this.cursor.style.top = `${y}px`;
+              this.cursor.classList.add("visible");
+          }
+          // Cancel any pending hide
+          if (this.hideTimeout) {
+              clearTimeout(this.hideTimeout);
+              this.hideTimeout = null;
+          }
+          // Start animation loop if not running
+          if (!this.animating) {
+              this.animating = true;
+              this.animateLoop();
+          }
+      }
+      animateLoop() {
+          const ease = 0.18;
+          const dx = this.targetX - this.currentX;
+          const dy = this.targetY - this.currentY;
+          if (Math.abs(dx) > 1 || Math.abs(dy) > 1) {
+              this.currentX += dx * ease;
+              this.currentY += dy * ease;
+              this.cursor.style.left = `${this.currentX}px`;
+              this.cursor.style.top = `${this.currentY}px`;
+              requestAnimationFrame(() => this.animateLoop());
+          }
+          else {
+              // Snap to target
+              this.currentX = this.targetX;
+              this.currentY = this.targetY;
+              this.cursor.style.left = `${this.currentX}px`;
+              this.cursor.style.top = `${this.currentY}px`;
+              this.animating = false;
+              // Auto-hide cursor after 2s of inactivity
+              this.hideTimeout = setTimeout(() => {
+                  this.visible = false;
+                  this.cursor.classList.remove("visible");
+              }, 2000);
+          }
+      }
+      triggerClickAnimation() {
+          this.cursor.classList.remove("clicking");
+          // Force reflow to restart CSS animation
+          void this.cursor.offsetHeight;
+          this.cursor.classList.add("clicking");
+      }
+      destroy() {
+          if (this.hideTimeout)
+              clearTimeout(this.hideTimeout);
+          this.container.remove();
+      }
+  }
+
   /**
    * Environment detection and page metadata collection.
    */
@@ -9099,7 +9289,7 @@
           required: ["selector"],
       },
   };
-  function clickElement(selector) {
+  function clickElement$1(selector) {
       const el = document.querySelector(selector);
       if (!el) {
           return { success: false, message: `No element found for selector: ${selector}` };
@@ -9114,7 +9304,7 @@
       }));
       return { success: true, message: `Clicked element: ${selector}` };
   }
-  clickElement.__schema__ = {
+  clickElement$1.__schema__ = {
       name: "clickElement",
       description: "Click a DOM element matching the CSS selector.",
       parameters: {
@@ -10500,29 +10690,79 @@
           "",
           "# Web Debugger Skill",
           "",
-          "This skill allows you to remotely debug and interact with a web page through a set of HTTP API endpoints.",
+          "This skill allows you to remotely debug and interact with a web page through HTTP API endpoints.",
           "",
-          "## How to call functions",
+          "## Recommended Workflow (Index-Based Interaction)",
           "",
-          "All functions are available as HTTP endpoints. Use the service URL provided in the instructions.",
+          "The most reliable way to interact with a page is using the smart DOM analysis:",
           "",
-          "**GET request** (for functions with no required parameters):",
+          "### Step 1: Observe the page",
+          "```bash",
+          `curl '{SERVICE_URL}/get_browser_state'`,
           "```",
-          `curl '{SERVICE_URL}/get_page_info?_mode=last' -H 'Authorization: Bearer {TOKEN}'`,
+          "This returns all interactive elements indexed as `[0]`, `[1]`, `[2]`, etc.",
+          "Elements are detected via smart heuristics: CSS cursor, ARIA roles, event listeners, tag names.",
+          "Visual highlight labels are overlaid on the page for each detected element.",
+          "",
+          "Example output:",
+          "```",
+          "[0]<a aria-label=Home>Home />",
+          "[1]<input placeholder=Search... />",
+          "[2]<button>Sign In />",
+          "[3]<select name=language>English />",
+          "[4]<div data-scrollable=\"top=200, bottom=1500\">Content area />",
           "```",
           "",
-          "**POST request** (for functions with parameters):",
+          "### Step 2: Act on elements by index",
+          "```bash",
+          "# Click a button (e.g. [2] Sign In):",
+          `curl -X POST '{SERVICE_URL}/click_element_by_index' \\`,
+          `  -H 'Content-Type: application/json' -d '{"index": 2}'`,
+          "",
+          "# Type into an input (e.g. [1] Search):",
+          `curl -X POST '{SERVICE_URL}/input_text' \\`,
+          `  -H 'Content-Type: application/json' -d '{"index": 1, "text": "hello world"}'`,
+          "",
+          "# Select a dropdown option (e.g. [3] Language):",
+          `curl -X POST '{SERVICE_URL}/select_option' \\`,
+          `  -H 'Content-Type: application/json' -d '{"index": 3, "option_text": "French"}'`,
+          "",
+          "# Scroll down:",
+          `curl -X POST '{SERVICE_URL}/scroll' \\`,
+          `  -H 'Content-Type: application/json' -d '{"direction": "down"}'`,
+          "",
+          "# Scroll a specific container (e.g. [4]):",
+          `curl -X POST '{SERVICE_URL}/scroll' \\`,
+          `  -H 'Content-Type: application/json' -d '{"direction": "down", "index": 4}'`,
           "```",
-          `curl -X POST '{SERVICE_URL}/query_dom?_mode=last' \\`,
-          `  -H 'Authorization: Bearer {TOKEN}' \\`,
-          `  -H 'Content-Type: application/json' \\`,
-          `  -d '{"selector": "button"}'`,
+          "",
+          "### Step 3: Verify",
+          "```bash",
+          `curl '{SERVICE_URL}/take_screenshot'`,
           "```",
           "",
-          "Replace `{SERVICE_URL}` and `{TOKEN}` with the actual values from the instruction block.",
+          "### Remove visual highlights (optional, for clean screenshots)",
+          "```bash",
+          `curl '{SERVICE_URL}/remove_highlights'`,
+          "```",
+          "",
+          "## CSS Selector-Based Functions (Alternative)",
+          "",
+          "You can also use CSS selectors directly for precise targeting:",
+          "```bash",
+          `curl -X POST '{SERVICE_URL}/click_element' \\`,
+          `  -H 'Content-Type: application/json' -d '{"selector": "button.submit"}'`,
+          "",
+          `curl -X POST '{SERVICE_URL}/fill_input' \\`,
+          `  -H 'Content-Type: application/json' -d '{"selector": "#email", "value": "user@example.com"}'`,
+          "```",
+          "",
+          "## How to call functions",
+          "",
+          "All functions are available as HTTP endpoints. Replace `{SERVICE_URL}` with the actual service URL.",
           "",
-          "**Note:** The `_mode=last` query parameter ensures the latest debugger instance is used,",
-          "even if multiple sessions have connected to the same workspace.",
+          "- **GET** for functions with no required parameters",
+          "- **POST** with JSON body for functions with parameters",
           "",
       ].join("\n");
       // Build the function reference
@@ -10565,8 +10805,7 @@
                   }
                   functionDocs.push("**Example:**");
                   functionDocs.push("```bash");
-                  functionDocs.push(`curl -X POST '{SERVICE_URL}/${name}?_mode=last' \\`);
-                  functionDocs.push(`  -H 'Authorization: Bearer {TOKEN}' \\`);
+                  functionDocs.push(`curl -X POST '{SERVICE_URL}/${name}' \\`);
                   functionDocs.push(`  -H 'Content-Type: application/json' \\`);
                   functionDocs.push(`  -d '${JSON.stringify(exampleParams)}'`);
                   functionDocs.push("```");
@@ -10574,7 +10813,7 @@
               else {
                   functionDocs.push("**Example:**");
                   functionDocs.push("```bash");
-                  functionDocs.push(`curl '{SERVICE_URL}/${name}?_mode=last' -H 'Authorization: Bearer {TOKEN}'`);
+                  functionDocs.push(`curl '{SERVICE_URL}/${name}'`);
                   functionDocs.push("```");
               }
           }
@@ -10583,7 +10822,7 @@
               functionDocs.push("");
               functionDocs.push("**Example:**");
               functionDocs.push("```bash");
-              functionDocs.push(`curl '{SERVICE_URL}/${name}?_mode=last' -H 'Authorization: Bearer {TOKEN}'`);
+              functionDocs.push(`curl '{SERVICE_URL}/${name}'`);
               functionDocs.push("```");
           }
           functionDocs.push("");
@@ -10591,35 +10830,2780 @@
       const tips = [
           "## Tips",
           "",
-          "- **Start with `get_page_info`** to understand the page structure, URL, title, and viewport.",
-          "- **Use `query_dom`** with CSS selectors to find elements before clicking or filling them.",
-          "- **Use `take_screenshot`** to visually verify the page state.",
+          "- **Start with `get_browser_state`** — it's the best way to understand what's on the page and what you can interact with.",
+          "- **Prefer index-based interaction** (`click_element_by_index`, `input_text`, `select_option`) over CSS selectors — indices are more reliable across dynamic pages.",
+          "- **After each action, call `get_browser_state` again** — element indices change when the DOM updates.",
+          "- **Use `take_screenshot`** to visually verify the page state. Call `remove_highlights` first for a clean view.",
           "- **Use `execute_script`** for anything not covered by the built-in functions — it runs arbitrary JavaScript.",
+          "- **Use `scroll`** with an element index to scroll inside a specific container (e.g. a chat window, sidebar).",
           "- **Use `get_page_info` with `include_logs=true`** to check for JavaScript errors or debug output.",
           "- **Use `get_react_tree`** if the page uses React — it gives you component names, props, and state.",
           "- All POST endpoints accept JSON body with the parameter names as keys.",
-          "- All endpoints require the `Authorization: Bearer {TOKEN}` header.",
           "",
       ].join("\n");
       return [frontmatter, intro, functionDocs.join("\n"), tips].join("\n");
   }
 
+  /**
+   * @file port from browser-use
+   * @see https://github.com/browser-use/browser-use/commits/main/browser_use/dom/dom_tree/index.js
+   * @match 0.5.9 d51b6e73daff7165fdd3e44debd667e7f5f7fdc5
+   *
+   * search @edit for all the changed lines.
+   *
+   * @edit export
+   * @edit add interactiveBlacklist interactiveWhitelist
+   * @edit adjustable opacity
+   * @edit direct dom ref
+   * @edit @workaround input.checked
+   * @edit smaller zIndex for highlight
+   * @edit no need for xpath
+   * @edit add `extra` field for extra data
+   * @edit scrollable element detection
+   * @edit add `data-browser-use-ignore` attribute
+   * @edit improve `sampleRect`, filter out rects with 0 area
+   * @edit exclude aria-hidden elements
+   * @edit make sure attributes exist for interactive candidates.
+   */
+
+  var domTree = (
+  	args = {
+  		doHighlightElements: true,
+  		focusHighlightIndex: -1,
+  		viewportExpansion: 0,
+  		debugMode: false,
+
+  		/**
+  		 * @edit
+  		 */
+  		/** @type {Element[]} */
+  		interactiveBlacklist: [],
+  		/** @type {Element[]} */
+  		interactiveWhitelist: [],
+  		highlightOpacity: 0.1,
+  		highlightLabelOpacity: 0.5,
+  	}
+  ) => {
+  	/**
+  	 * @edit
+  	 */
+  	const { interactiveBlacklist, interactiveWhitelist, highlightOpacity, highlightLabelOpacity } =
+  		args;
+
+  	const { doHighlightElements, focusHighlightIndex, viewportExpansion, debugMode } = args;
+  	let highlightIndex = 0; // Reset highlight index
+
+  	/**
+  	 * @edit add `extra` field for extra data
+  	 */
+  	const extraData = new WeakMap();
+  	function addExtraData(element, data) {
+  		if (!element || element.nodeType !== Node.ELEMENT_NODE) return
+  		extraData.set(element, { ...extraData.get(element), ...data });
+  	}
+
+  	// 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';
+
+  	// // 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%';
+
+  				/**
+  				 * @edit smaller zIndex for highlight
+  				 */
+  				// Use the maximum valid value in zIndex to ensure the element is not blocked by overlapping elements.
+  				// container.style.zIndex = "2147483647";
+  				container.style.zIndex = '2147483640';
+
+  				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;
+  			let baseColor = colors[colorIndex];
+
+  			/**
+  			 * @edit adjustable opacity
+  			 */
+  			// const backgroundColor = baseColor + "1A"; // 10% opacity version of the color
+  			const backgroundColor =
+  				baseColor +
+  				Math.floor(highlightOpacity * 255)
+  					.toString(16)
+  					.padStart(2, '0');
+  			baseColor =
+  				baseColor +
+  				Math.floor(highlightLabelOpacity * 255)
+  					.toString(16)
+  					.padStart(2, '0');
+
+  			// 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) {
+  (window._highlightCleanupFunctions = window._highlightCleanupFunctions || []).push(
+  					cleanupFn
+  				);
+  			}
+  		}
+  	}
+
+  	/**
+  	 * @edit scrollable element detection
+  	 * Checks if an element is scrollable. if so, return the scrollable distance on each direction (left right top bottom). if not return null.
+  	 * @note distance smaller than 4 will be considered as not scrollable.
+  	 * @note only check block elements, not inline elements.
+  	 */
+  	function isScrollableElement(element) {
+  		if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+  			return null // Not a valid element
+  		}
+
+  		const style = getCachedComputedStyle(element);
+  		if (!style) return null
+
+  		// Check if the element is a block-level element
+  		const display = style.display;
+  		if (display === 'inline' || display === 'inline-block') {
+  			return null // Not a block-level element
+  		}
+
+  		// Check overflow properties
+  		const overflowX = style.overflowX;
+  		const overflowY = style.overflowY;
+
+  		// Check scrollable distances
+  		const scrollableX = overflowX === 'auto' || overflowX === 'scroll';
+  		const scrollableY = overflowY === 'auto' || overflowY === 'scroll';
+
+  		if (!scrollableX && !scrollableY) {
+  			return null // Not scrollable in any direction
+  		}
+
+  		const scrollWidth = element.scrollWidth - element.clientWidth;
+  		const scrollHeight = element.scrollHeight - element.clientHeight;
+
+  		// Consider small distances as not scrollable
+  		const threshold = 4;
+
+  		if (scrollWidth < threshold && scrollHeight < threshold) {
+  			return null // Not scrollable
+  		}
+
+  		if (!scrollableY && scrollWidth < threshold) {
+  			return null // Not scrollable horizontally
+  		}
+
+  		if (!scrollableX && scrollHeight < threshold) {
+  			return null // Not scrollable vertically
+  		}
+
+  		const distanceToTop = element.scrollTop;
+  		const distanceToLeft = element.scrollLeft;
+  		const distanceToRight = element.scrollWidth - element.clientWidth - element.scrollLeft;
+  		const distanceToBottom = element.scrollHeight - element.clientHeight - element.scrollTop;
+
+  		const scrollData = {
+  			top: distanceToTop,
+  			right: distanceToRight,
+  			bottom: distanceToBottom,
+  			left: distanceToLeft,
+  		};
+
+  		// Store extra data for the element
+  		addExtraData(element, {
+  			scrollable: true,
+  			scrollData: scrollData,
+  		});
+
+  		return scrollData
+  	}
+
+  	/**
+  	 * 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
+  		}
+
+  		/**
+  		 * @edit add interactiveBlacklist interactiveWhitelist
+  		 */
+  		if (interactiveBlacklist.includes(element)) {
+  			return false // Skip blacklisted elements
+  		}
+  		if (interactiveWhitelist.includes(element)) {
+  			return true // Skip whitelisted elements
+  		}
+
+  		// 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
+  		}
+
+  		/**
+  		 * @edit scrollable element detection
+  		 */
+  		if (isScrollableElement(element)) {
+  			return true
+  		}
+
+  		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
+  		}
+
+  		/**
+  		 * @edit improve `sampleRect`, filter out rects with 0 area
+  		 */
+  		// find a rect that has width and height as sample
+  		let rect = Array.from(rects).find((r) => r.width > 0 && r.height > 0);
+  		if (!rect) {
+  			return false // No valid rect found
+  		}
+
+  		// For shadow DOM, we need to check within its own root context
+  		const shadowRoot = element.getRootNode();
+  		if (shadowRoot instanceof ShadowRoot) {
+  			const centerX = rect.left + rect.width / 2;
+  			const centerY = rect.top + rect.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;
+
+  		// 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
+  				}
+  			}
+  		}
+
+  		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
+  		}
+
+  		/**
+  		 * @edit add `data-browser-use-ignore` attribute
+  		 */
+  		if (node.dataset?.browserUseIgnore === 'true' || node.dataset?.pageAgentIgnore === 'true') {
+  			return null // Skip this node and its children
+  		}
+
+  		/**
+  		 * @edit exclude aria-hidden elements
+  		 */
+  		if (node.getAttribute && node.getAttribute('aria-hidden') === 'true') {
+  			return null // Skip this node and its children
+  		}
+
+  		// 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: {},
+
+  			/**
+  			 * @edit no need for xpath
+  			 */
+  			// 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;
+  			}
+
+  			/**
+  			 * @edit @workaround input.checked
+  			 */
+  			if (
+  				node.tagName.toLowerCase() === 'input' &&
+  				(node.type === 'checkbox' || node.type === 'radio')
+  			) {
+  				nodeData.attributes.checked = node.checked ? 'true' : 'false'; // Store as string for consistency
+  			}
+  		}
+
+  		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);
+
+  					/**
+  					 * @edit direct dom ref
+  					 */
+  					nodeData.ref = node;
+
+  					/**
+  					 * @edit make sure attributes exist for interactive candidates.
+  					 * @note if the element failed the isInteractiveCandidate, attributes would be empty.
+  					 */
+  					if (nodeData.isInteractive && Object.keys(nodeData.attributes).length === 0) {
+  						const attributeNames = node.getAttributeNames?.() || [];
+  						for (const name of attributeNames) {
+  							const value = node.getAttribute(name);
+  							nodeData.attributes[name] = value;
+  						}
+  					}
+  				}
+  			}
+  		}
+
+  		// 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
+  			}
+  		}
+
+  		/**
+  		 * @edit add `extra` field for extra data
+  		 */
+  		nodeData.extra = extraData.get(node) || 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 }
+  };
+
+  /**
+   * DOM tree utilities: build flat tree, convert to string, manage highlights.
+   * Adapted from @page-agent/page-controller (MIT License).
+   */
+  const DEFAULT_VIEWPORT_EXPANSION = -1;
+  function resolveViewportExpansion(viewportExpansion) {
+      return viewportExpansion ?? DEFAULT_VIEWPORT_EXPANSION;
+  }
+  const newElementsCache = new WeakMap();
+  function getFlatTree(config) {
+      const viewportExpansion = resolveViewportExpansion(config.viewportExpansion);
+      const interactiveBlacklist = [];
+      for (const item of config.interactiveBlacklist || []) {
+          if (typeof item === "function") {
+              interactiveBlacklist.push(item());
+          }
+          else {
+              interactiveBlacklist.push(item);
+          }
+      }
+      const interactiveWhitelist = [];
+      for (const item of config.interactiveWhitelist || []) {
+          if (typeof item === "function") {
+              interactiveWhitelist.push(item());
+          }
+          else {
+              interactiveWhitelist.push(item);
+          }
+      }
+      const elements = domTree({
+          doHighlightElements: true,
+          debugMode: true,
+          focusHighlightIndex: -1,
+          viewportExpansion,
+          interactiveBlacklist,
+          interactiveWhitelist,
+          highlightOpacity: config.highlightOpacity ?? 0.0,
+          highlightLabelOpacity: config.highlightLabelOpacity ?? 0.1,
+      });
+      for (const nodeId in elements.map) {
+          const node = elements.map[nodeId];
+          if (node.isInteractive && node.ref) {
+              const ref = node.ref;
+              if (!newElementsCache.has(ref)) {
+                  newElementsCache.set(ref, window.location.href);
+                  node.isNew = true;
+              }
+          }
+      }
+      return elements;
+  }
+  // ---- flatTreeToString ----
+  const globRegexCache = new Map();
+  function globToRegex(pattern) {
+      let regex = globRegexCache.get(pattern);
+      if (!regex) {
+          const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+          regex = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+          globRegexCache.set(pattern, regex);
+      }
+      return regex;
+  }
+  function matchAttributes(attrs, patterns) {
+      const result = {};
+      for (const pattern of patterns) {
+          if (pattern.includes("*")) {
+              const regex = globToRegex(pattern);
+              for (const key of Object.keys(attrs)) {
+                  if (regex.test(key) && attrs[key].trim()) {
+                      result[key] = attrs[key].trim();
+                  }
+              }
+          }
+          else {
+              const value = attrs[pattern];
+              if (value && value.trim()) {
+                  result[pattern] = value.trim();
+              }
+          }
+      }
+      return result;
+  }
+  function flatTreeToString(flatTree, includeAttributes) {
+      const DEFAULT_INCLUDE_ATTRIBUTES = [
+          "title",
+          "type",
+          "checked",
+          "name",
+          "role",
+          "value",
+          "placeholder",
+          "data-date-format",
+          "alt",
+          "aria-label",
+          "aria-expanded",
+          "data-state",
+          "aria-checked",
+          "id",
+          "for",
+          "target",
+          "aria-haspopup",
+          "aria-controls",
+          "aria-owns",
+          "contenteditable",
+      ];
+      const includeAttrs = [
+          ...(includeAttributes || []),
+          ...DEFAULT_INCLUDE_ATTRIBUTES,
+      ];
+      const capTextLength = (text, maxLength) => {
+          if (text.length > maxLength) {
+              return text.substring(0, maxLength) + "...";
+          }
+          return text;
+      };
+      const buildTreeNode = (nodeId) => {
+          const node = flatTree.map[nodeId];
+          if (!node)
+              return null;
+          if (node.type === "TEXT_NODE") {
+              const textNode = node;
+              return {
+                  type: "text",
+                  text: textNode.text,
+                  isVisible: textNode.isVisible,
+                  parent: null,
+                  children: [],
+              };
+          }
+          else {
+              const elementNode = node;
+              const children = [];
+              if (elementNode.children) {
+                  for (const childId of elementNode.children) {
+                      const child = buildTreeNode(childId);
+                      if (child) {
+                          children.push(child);
+                      }
+                  }
+              }
+              return {
+                  type: "element",
+                  tagName: elementNode.tagName,
+                  attributes: elementNode.attributes ?? {},
+                  isVisible: elementNode.isVisible ?? false,
+                  isInteractive: elementNode.isInteractive ?? false,
+                  isTopElement: elementNode.isTopElement ?? false,
+                  isNew: elementNode.isNew ?? false,
+                  highlightIndex: elementNode.highlightIndex,
+                  parent: null,
+                  children,
+                  extra: elementNode.extra ?? {},
+              };
+          }
+      };
+      const setParentReferences = (node, parent = null) => {
+          node.parent = parent;
+          for (const child of node.children) {
+              setParentReferences(child, node);
+          }
+      };
+      const rootNode = buildTreeNode(flatTree.rootId);
+      if (!rootNode)
+          return "";
+      setParentReferences(rootNode);
+      const hasParentWithHighlightIndex = (node) => {
+          let current = node.parent;
+          while (current) {
+              if (current.type === "element" &&
+                  current.highlightIndex !== undefined) {
+                  return true;
+              }
+              current = current.parent;
+          }
+          return false;
+      };
+      const processNode = (node, depth, result) => {
+          let nextDepth = depth;
+          const depthStr = "\t".repeat(depth);
+          if (node.type === "element") {
+              if (node.highlightIndex !== undefined) {
+                  nextDepth += 1;
+                  const text = getAllTextTillNextClickableElement(node);
+                  let attributesHtmlStr = "";
+                  if (includeAttrs.length > 0 && node.attributes) {
+                      const attributesToInclude = matchAttributes(node.attributes, includeAttrs);
+                      const keys = Object.keys(attributesToInclude);
+                      if (keys.length > 1) {
+                          const keysToRemove = new Set();
+                          const seenValues = {};
+                          for (const key of keys) {
+                              const value = attributesToInclude[key];
+                              if (value.length > 5) {
+                                  if (value in seenValues) {
+                                      keysToRemove.add(key);
+                                  }
+                                  else {
+                                      seenValues[value] = key;
+                                  }
+                              }
+                          }
+                          for (const key of keysToRemove) {
+                              delete attributesToInclude[key];
+                          }
+                      }
+                      if (attributesToInclude.role === node.tagName) {
+                          delete attributesToInclude.role;
+                      }
+                      const attrsToRemoveIfTextMatches = [
+                          "aria-label",
+                          "placeholder",
+                          "title",
+                      ];
+                      for (const attr of attrsToRemoveIfTextMatches) {
+                          if (attributesToInclude[attr] &&
+                              attributesToInclude[attr].toLowerCase().trim() ===
+                                  text.toLowerCase().trim()) {
+                              delete attributesToInclude[attr];
+                          }
+                      }
+                      if (Object.keys(attributesToInclude).length > 0) {
+                          attributesHtmlStr = Object.entries(attributesToInclude)
+                              .map(([key, value]) => `${key}=${capTextLength(value, 20)}`)
+                              .join(" ");
+                      }
+                  }
+                  const highlightIndicator = node.isNew
+                      ? `*[${node.highlightIndex}]`
+                      : `[${node.highlightIndex}]`;
+                  let line = `${depthStr}${highlightIndicator}<${node.tagName ?? ""}`;
+                  if (attributesHtmlStr) {
+                      line += ` ${attributesHtmlStr}`;
+                  }
+                  if (node.extra) {
+                      if (node.extra.scrollable) {
+                          let scrollDataText = "";
+                          if (node.extra.scrollData?.left)
+                              scrollDataText += `left=${node.extra.scrollData.left}, `;
+                          if (node.extra.scrollData?.top)
+                              scrollDataText += `top=${node.extra.scrollData.top}, `;
+                          if (node.extra.scrollData?.right)
+                              scrollDataText += `right=${node.extra.scrollData.right}, `;
+                          if (node.extra.scrollData?.bottom)
+                              scrollDataText += `bottom=${node.extra.scrollData.bottom}`;
+                          line += ` data-scrollable="${scrollDataText}"`;
+                      }
+                  }
+                  if (text) {
+                      const trimmedText = text.trim();
+                      if (!attributesHtmlStr) {
+                          line += " ";
+                      }
+                      line += `>${trimmedText}`;
+                  }
+                  else if (!attributesHtmlStr) {
+                      line += " ";
+                  }
+                  line += " />";
+                  result.push(line);
+              }
+              for (const child of node.children) {
+                  processNode(child, nextDepth, result);
+              }
+          }
+          else if (node.type === "text") {
+              if (hasParentWithHighlightIndex(node)) {
+                  return;
+              }
+              if (node.parent &&
+                  node.parent.type === "element" &&
+                  node.parent.isVisible &&
+                  node.parent.isTopElement) {
+                  result.push(`${depthStr}${node.text ?? ""}`);
+              }
+          }
+      };
+      const result = [];
+      processNode(rootNode, 0, result);
+      return result.join("\n");
+  }
+  const getAllTextTillNextClickableElement = (node, maxDepth = -1) => {
+      const textParts = [];
+      const collectText = (currentNode, currentDepth) => {
+          if (maxDepth !== -1 && currentDepth > maxDepth) {
+              return;
+          }
+          if (currentNode.type === "element" &&
+              currentNode !== node &&
+              currentNode.highlightIndex !== undefined) {
+              return;
+          }
+          if (currentNode.type === "text" && currentNode.text) {
+              textParts.push(currentNode.text);
+          }
+          else if (currentNode.type === "element") {
+              for (const child of currentNode.children) {
+                  collectText(child, currentDepth + 1);
+              }
+          }
+      };
+      collectText(node, 0);
+      return textParts.join("\n").trim();
+  };
+  function getSelectorMap(flatTree) {
+      const selectorMap = new Map();
+      const keys = Object.keys(flatTree.map);
+      for (const key of keys) {
+          const node = flatTree.map[key];
+          if (node.isInteractive && typeof node.highlightIndex === "number") {
+              selectorMap.set(node.highlightIndex, node);
+          }
+      }
+      return selectorMap;
+  }
+  function getElementTextMap(simplifiedHTML) {
+      const lines = simplifiedHTML
+          .split("\n")
+          .map((line) => line.trim())
+          .filter((line) => line.length > 0);
+      const elementTextMap = new Map();
+      for (const line of lines) {
+          const regex = /^\[(\d+)\]<[^>]+>([^<]*)/;
+          const match = regex.exec(line);
+          if (match) {
+              const index = parseInt(match[1], 10);
+              elementTextMap.set(index, line);
+          }
+      }
+      return elementTextMap;
+  }
+  function cleanUpHighlights() {
+      const cleanupFunctions = window._highlightCleanupFunctions || [];
+      for (const cleanup of cleanupFunctions) {
+          if (typeof cleanup === "function") {
+              cleanup();
+          }
+      }
+      window._highlightCleanupFunctions = [];
+  }
+
+  async function waitFor(seconds) {
+      await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+  }
+  function getElementByIndex(selectorMap, index) {
+      const interactiveNode = selectorMap.get(index);
+      if (!interactiveNode) {
+          throw new Error(`No interactive element found at index ${index}`);
+      }
+      const element = interactiveNode.ref;
+      if (!element) {
+          throw new Error(`Element at index ${index} does not have a reference`);
+      }
+      if (!(element instanceof HTMLElement)) {
+          throw new Error(`Element at index ${index} is not an HTMLElement`);
+      }
+      return element;
+  }
+  let lastClickedElement = null;
+  function blurLastClickedElement() {
+      if (lastClickedElement) {
+          lastClickedElement.blur();
+          lastClickedElement.dispatchEvent(new MouseEvent("mouseout", { bubbles: true, cancelable: true }));
+          lastClickedElement = null;
+      }
+  }
+  async function scrollIntoViewIfNeeded(element) {
+      // Check if element is already in viewport
+      const rect = element.getBoundingClientRect();
+      const inViewport = rect.top >= 0 &&
+          rect.bottom <= window.innerHeight &&
+          rect.left >= 0 &&
+          rect.right <= window.innerWidth;
+      if (!inViewport) {
+          element.scrollIntoView({ behavior: "smooth", block: "center", inline: "nearest" });
+          // Wait for smooth scroll animation to settle
+          await waitFor(0.4);
+      }
+  }
+  /** Move the visual AI cursor to the center of an element. */
+  async function movePointerToElement(element) {
+      const rect = element.getBoundingClientRect();
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      window.dispatchEvent(new CustomEvent("HyphaDebugger::MovePointerTo", { detail: { x, y } }));
+      await waitFor(0.3); // wait for cursor animation
+  }
+  async function clickElement(element) {
+      blurLastClickedElement();
+      lastClickedElement = element;
+      await scrollIntoViewIfNeeded(element);
+      await movePointerToElement(element);
+      // Trigger click ripple animation
+      window.dispatchEvent(new CustomEvent("HyphaDebugger::ClickPointer"));
+      await waitFor(0.05);
+      // hover
+      element.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true, cancelable: true }));
+      element.dispatchEvent(new MouseEvent("mouseover", { bubbles: true, cancelable: true }));
+      // mouse sequence
+      element.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true }));
+      element.focus();
+      element.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true }));
+      element.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+      await waitFor(0.2);
+  }
+  // Lazy-initialized to avoid "window is not defined" in Node/SSR
+  let _nativeInputValueSetter = null;
+  let _nativeTextAreaValueSetter = null;
+  function getNativeInputValueSetter() {
+      if (!_nativeInputValueSetter) {
+          _nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value").set;
+      }
+      return _nativeInputValueSetter;
+  }
+  function getNativeTextAreaValueSetter() {
+      if (!_nativeTextAreaValueSetter) {
+          _nativeTextAreaValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, "value").set;
+      }
+      return _nativeTextAreaValueSetter;
+  }
+  async function inputTextElement(element, text) {
+      const isContentEditable = element.isContentEditable;
+      if (!(element instanceof HTMLInputElement) &&
+          !(element instanceof HTMLTextAreaElement) &&
+          !isContentEditable) {
+          throw new Error("Element is not an input, textarea, or contenteditable");
+      }
+      await clickElement(element);
+      if (isContentEditable) {
+          // Clear
+          if (element.dispatchEvent(new InputEvent("beforeinput", {
+              bubbles: true,
+              cancelable: true,
+              inputType: "deleteContent",
+          }))) {
+              element.innerText = "";
+              element.dispatchEvent(new InputEvent("input", {
+                  bubbles: true,
+                  inputType: "deleteContent",
+              }));
+          }
+          // Insert
+          if (element.dispatchEvent(new InputEvent("beforeinput", {
+              bubbles: true,
+              cancelable: true,
+              inputType: "insertText",
+              data: text,
+          }))) {
+              element.innerText = text;
+              element.dispatchEvent(new InputEvent("input", {
+                  bubbles: true,
+                  inputType: "insertText",
+                  data: text,
+              }));
+          }
+          element.dispatchEvent(new Event("change", { bubbles: true }));
+          element.blur();
+      }
+      else if (element instanceof HTMLTextAreaElement) {
+          getNativeTextAreaValueSetter().call(element, text);
+      }
+      else {
+          getNativeInputValueSetter().call(element, text);
+      }
+      if (!isContentEditable) {
+          element.dispatchEvent(new Event("input", { bubbles: true }));
+      }
+      await waitFor(0.1);
+      blurLastClickedElement();
+  }
+  async function selectOptionElement(selectElement, optionText) {
+      if (!(selectElement instanceof HTMLSelectElement)) {
+          throw new Error("Element is not a select element");
+      }
+      await scrollIntoViewIfNeeded(selectElement);
+      // Move cursor to element
+      const rect = selectElement.getBoundingClientRect();
+      window.dispatchEvent(new CustomEvent("HyphaDebugger::MovePointerTo", {
+          detail: { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+      }));
+      await waitFor(0.3);
+      window.dispatchEvent(new CustomEvent("HyphaDebugger::ClickPointer"));
+      const options = Array.from(selectElement.options);
+      const option = options.find((opt) => opt.textContent?.trim() === optionText.trim());
+      if (!option) {
+          throw new Error(`Option with text "${optionText}" not found in select element`);
+      }
+      selectElement.value = option.value;
+      selectElement.dispatchEvent(new Event("change", { bubbles: true }));
+      await waitFor(0.1);
+  }
+  async function scrollVertically(down, scroll_amount, element) {
+      if (element) {
+          let currentElement = element;
+          let scrollSuccess = false;
+          let scrolledElement = null;
+          let scrollDelta = 0;
+          let attempts = 0;
+          const dy = scroll_amount;
+          while (currentElement && attempts < 10) {
+              const computedStyle = window.getComputedStyle(currentElement);
+              const hasScrollableY = /(auto|scroll|overlay)/.test(computedStyle.overflowY);
+              const canScrollVertically = currentElement.scrollHeight > currentElement.clientHeight;
+              if (hasScrollableY && canScrollVertically) {
+                  const beforeScroll = currentElement.scrollTop;
+                  const maxScroll = currentElement.scrollHeight - currentElement.clientHeight;
+                  let scrollAmount = dy / 3;
+                  if (scrollAmount > 0) {
+                      scrollAmount = Math.min(scrollAmount, maxScroll - beforeScroll);
+                  }
+                  else {
+                      scrollAmount = Math.max(scrollAmount, -beforeScroll);
+                  }
+                  currentElement.scrollTop = beforeScroll + scrollAmount;
+                  const afterScroll = currentElement.scrollTop;
+                  const actualScrollDelta = afterScroll - beforeScroll;
+                  if (Math.abs(actualScrollDelta) > 0.5) {
+                      scrollSuccess = true;
+                      scrolledElement = currentElement;
+                      scrollDelta = actualScrollDelta;
+                      break;
+                  }
+              }
+              if (currentElement === document.body ||
+                  currentElement === document.documentElement) {
+                  break;
+              }
+              currentElement = currentElement.parentElement;
+              attempts++;
+          }
+          if (scrollSuccess) {
+              return `Scrolled container (${scrolledElement?.tagName}) by ${scrollDelta}px`;
+          }
+          else {
+              return `No scrollable container found for element (${element.tagName})`;
+          }
+      }
+      // Page-level scrolling
+      const dy = scroll_amount;
+      const bigEnough = (el) => el.clientHeight >= window.innerHeight * 0.5;
+      const canScroll = (el) => el &&
+          /(auto|scroll|overlay)/.test(getComputedStyle(el).overflowY) &&
+          el.scrollHeight > el.clientHeight &&
+          bigEnough(el);
+      let el = document.activeElement;
+      while (el && !canScroll(el) && el !== document.body)
+          el = el.parentElement;
+      el = canScroll(el)
+          ? el
+          : Array.from(document.querySelectorAll("*")).find(canScroll) ||
+              document.scrollingElement ||
+              document.documentElement;
+      if (el === document.scrollingElement ||
+          el === document.documentElement ||
+          el === document.body) {
+          const scrollBefore = window.scrollY;
+          window.scrollBy(0, dy);
+          const scrollAfter = window.scrollY;
+          const scrolled = scrollAfter - scrollBefore;
+          if (Math.abs(scrolled) < 1) {
+              return dy > 0
+                  ? "Already at the bottom of the page."
+                  : "Already at the top of the page.";
+          }
+          const scrollMax = document.documentElement.scrollHeight - window.innerHeight;
+          const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1;
+          const reachedTop = dy < 0 && scrollAfter <= 1;
+          if (reachedBottom)
+              return `Scrolled page by ${scrolled}px. Reached the bottom.`;
+          if (reachedTop)
+              return `Scrolled page by ${scrolled}px. Reached the top.`;
+          return `Scrolled page by ${scrolled}px.`;
+      }
+      else {
+          const scrollBefore = el.scrollTop;
+          const scrollMax = el.scrollHeight - el.clientHeight;
+          el.scrollBy({ top: dy, behavior: "smooth" });
+          await waitFor(0.1);
+          const scrollAfter = el.scrollTop;
+          const scrolled = scrollAfter - scrollBefore;
+          if (Math.abs(scrolled) < 1) {
+              return dy > 0
+                  ? `Already at the bottom of container (${el.tagName}).`
+                  : `Already at the top of container (${el.tagName}).`;
+          }
+          const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1;
+          const reachedTop = dy < 0 && scrollAfter <= 1;
+          if (reachedBottom)
+              return `Scrolled container (${el.tagName}) by ${scrolled}px. Reached the bottom.`;
+          if (reachedTop)
+              return `Scrolled container (${el.tagName}) by ${scrolled}px. Reached the top.`;
+          return `Scrolled container (${el.tagName}) by ${scrolled}px.`;
+      }
+  }
+  async function scrollHorizontally(right, scroll_amount, element) {
+      if (element) {
+          let currentElement = element;
+          let scrollSuccess = false;
+          let scrolledElement = null;
+          let scrollDelta = 0;
+          let attempts = 0;
+          const dx = right ? scroll_amount : -scroll_amount;
+          while (currentElement && attempts < 10) {
+              const computedStyle = window.getComputedStyle(currentElement);
+              const hasScrollableX = /(auto|scroll|overlay)/.test(computedStyle.overflowX);
+              const canScrollHorizontally = currentElement.scrollWidth > currentElement.clientWidth;
+              if (hasScrollableX && canScrollHorizontally) {
+                  const beforeScroll = currentElement.scrollLeft;
+                  const maxScroll = currentElement.scrollWidth - currentElement.clientWidth;
+                  let scrollAmount = dx / 3;
+                  if (scrollAmount > 0) {
+                      scrollAmount = Math.min(scrollAmount, maxScroll - beforeScroll);
+                  }
+                  else {
+                      scrollAmount = Math.max(scrollAmount, -beforeScroll);
+                  }
+                  currentElement.scrollLeft = beforeScroll + scrollAmount;
+                  const afterScroll = currentElement.scrollLeft;
+                  const actualScrollDelta = afterScroll - beforeScroll;
+                  if (Math.abs(actualScrollDelta) > 0.5) {
+                      scrollSuccess = true;
+                      scrolledElement = currentElement;
+                      scrollDelta = actualScrollDelta;
+                      break;
+                  }
+              }
+              if (currentElement === document.body ||
+                  currentElement === document.documentElement) {
+                  break;
+              }
+              currentElement = currentElement.parentElement;
+              attempts++;
+          }
+          if (scrollSuccess) {
+              return `Scrolled container (${scrolledElement?.tagName}) horizontally by ${scrollDelta}px`;
+          }
+          else {
+              return `No horizontally scrollable container found for element (${element.tagName})`;
+          }
+      }
+      // Page-level horizontal scroll
+      const dx = right ? scroll_amount : -scroll_amount;
+      const bigEnough = (el) => el.clientWidth >= window.innerWidth * 0.5;
+      const canScroll = (el) => el &&
+          /(auto|scroll|overlay)/.test(getComputedStyle(el).overflowX) &&
+          el.scrollWidth > el.clientWidth &&
+          bigEnough(el);
+      let el = document.activeElement;
+      while (el && !canScroll(el) && el !== document.body)
+          el = el.parentElement;
+      el = canScroll(el)
+          ? el
+          : Array.from(document.querySelectorAll("*")).find(canScroll) ||
+              document.scrollingElement ||
+              document.documentElement;
+      if (el === document.scrollingElement ||
+          el === document.documentElement ||
+          el === document.body) {
+          const scrollBefore = window.scrollX;
+          const scrollMax = document.documentElement.scrollWidth - window.innerWidth;
+          window.scrollBy(dx, 0);
+          const scrollAfter = window.scrollX;
+          const scrolled = scrollAfter - scrollBefore;
+          if (Math.abs(scrolled) < 1) {
+              return dx > 0
+                  ? "Already at the right edge of the page."
+                  : "Already at the left edge of the page.";
+          }
+          const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1;
+          const reachedLeft = dx < 0 && scrollAfter <= 1;
+          if (reachedRight)
+              return `Scrolled page by ${scrolled}px. Reached the right edge.`;
+          if (reachedLeft)
+              return `Scrolled page by ${scrolled}px. Reached the left edge.`;
+          return `Scrolled page horizontally by ${scrolled}px.`;
+      }
+      else {
+          const scrollBefore = el.scrollLeft;
+          const scrollMax = el.scrollWidth - el.clientWidth;
+          el.scrollBy({ left: dx, behavior: "smooth" });
+          await waitFor(0.1);
+          const scrollAfter = el.scrollLeft;
+          const scrolled = scrollAfter - scrollBefore;
+          if (Math.abs(scrolled) < 1) {
+              return dx > 0
+                  ? `Already at the right edge of container (${el.tagName}).`
+                  : `Already at the left edge of container (${el.tagName}).`;
+          }
+          const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1;
+          const reachedLeft = dx < 0 && scrollAfter <= 1;
+          if (reachedRight)
+              return `Scrolled container (${el.tagName}) by ${scrolled}px. Reached the right edge.`;
+          if (reachedLeft)
+              return `Scrolled container (${el.tagName}) by ${scrolled}px. Reached the left edge.`;
+          return `Scrolled container (${el.tagName}) horizontally by ${scrolled}px.`;
+      }
+  }
+
+  /**
+   * Page info utilities: viewport, scroll position, page dimensions.
+   * Adapted from @page-agent/page-controller (MIT License).
+   */
+  function getPageScrollInfo() {
+      const viewport_width = window.innerWidth;
+      const viewport_height = window.innerHeight;
+      const page_width = Math.max(document.documentElement.scrollWidth, document.body.scrollWidth || 0);
+      const page_height = Math.max(document.documentElement.scrollHeight, document.body.scrollHeight || 0);
+      const scroll_x = window.scrollX ||
+          window.pageXOffset ||
+          document.documentElement.scrollLeft ||
+          0;
+      const scroll_y = window.scrollY ||
+          window.pageYOffset ||
+          document.documentElement.scrollTop ||
+          0;
+      const pixels_below = Math.max(0, page_height - (window.innerHeight + scroll_y));
+      const pixels_right = Math.max(0, page_width - (window.innerWidth + scroll_x));
+      return {
+          viewport_width,
+          viewport_height,
+          page_width,
+          page_height,
+          scroll_x,
+          scroll_y,
+          pixels_above: scroll_y,
+          pixels_below,
+          pages_above: viewport_height > 0 ? scroll_y / viewport_height : 0,
+          pages_below: viewport_height > 0 ? pixels_below / viewport_height : 0,
+          total_pages: viewport_height > 0 ? page_height / viewport_height : 0,
+          current_page_position: scroll_y / Math.max(1, page_height - viewport_height),
+          pixels_left: scroll_x,
+          pixels_right,
+      };
+  }
+
+  /**
+   * PageController: manages DOM state and element interactions.
+   * Adapted from @page-agent/page-controller (MIT License).
+   *
+   * This wraps the smart DOM analysis (interactive element detection,
+   * indexed element map) and provides an API for external agents.
+   */
+  class PageController {
+      constructor(config = {}) {
+          this.flatTree = null;
+          this.selectorMap = new Map();
+          this.elementTextMap = new Map();
+          this.simplifiedHTML = "";
+          this.isIndexed = false;
+          this.config = config;
+      }
+      /**
+       * Get structured browser state for LLM consumption.
+       * Builds the DOM tree, highlights interactive elements, and returns
+       * a simplified text representation with numeric indices.
+       */
+      async getBrowserState() {
+          const url = window.location.href;
+          const title = document.title;
+          const pi = getPageScrollInfo();
+          const viewportExpansion = resolveViewportExpansion(this.config.viewportExpansion);
+          await this.updateTree();
+          const content = this.simplifiedHTML;
+          const titleLine = `Current Page: [${title}](${url})`;
+          const pageInfoLine = `Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, at ${(pi.current_page_position * 100).toFixed(0)}%`;
+          const elementsLabel = viewportExpansion === -1
+              ? "Interactive elements (full page):"
+              : "Interactive elements (viewport):";
+          const hasContentAbove = pi.pixels_above > 4;
+          const scrollHintAbove = hasContentAbove && viewportExpansion !== -1
+              ? `... ${pi.pixels_above} pixels above - scroll to see more ...`
+              : "[Start of page]";
+          const header = `${titleLine}\n${pageInfoLine}\n\n${elementsLabel}\n\n${scrollHintAbove}`;
+          const hasContentBelow = pi.pixels_below > 4;
+          const footer = hasContentBelow && viewportExpansion !== -1
+              ? `... ${pi.pixels_below} pixels below - scroll to see more ...`
+              : "[End of page]";
+          return {
+              url,
+              title,
+              header,
+              content,
+              footer,
+              element_count: this.selectorMap.size,
+          };
+      }
+      /**
+       * Update DOM tree, returns simplified HTML for LLM.
+       */
+      async updateTree() {
+          cleanUpHighlights();
+          this.flatTree = getFlatTree(this.config);
+          this.simplifiedHTML = flatTreeToString(this.flatTree, this.config.includeAttributes);
+          this.selectorMap.clear();
+          this.selectorMap = getSelectorMap(this.flatTree);
+          this.elementTextMap.clear();
+          this.elementTextMap = getElementTextMap(this.simplifiedHTML);
+          this.isIndexed = true;
+          return this.simplifiedHTML;
+      }
+      async cleanUpHighlights() {
+          cleanUpHighlights();
+      }
+      assertIndexed() {
+          if (!this.isIndexed) {
+              throw new Error("DOM tree not indexed yet. Call get_browser_state first.");
+          }
+      }
+      /** Clean up highlights after performing an action. */
+      cleanUpAfterAction() {
+          cleanUpHighlights();
+      }
+      async clickElement(index) {
+          try {
+              this.assertIndexed();
+              const element = getElementByIndex(this.selectorMap, index);
+              const elemText = this.elementTextMap.get(index);
+              this.cleanUpAfterAction();
+              await clickElement(element);
+              if (element instanceof HTMLAnchorElement &&
+                  element.target === "_blank") {
+                  return {
+                      success: true,
+                      message: `Clicked element (${elemText ?? index}). Link opened in a new tab.`,
+                  };
+              }
+              return {
+                  success: true,
+                  message: `Clicked element (${elemText ?? index}).`,
+              };
+          }
+          catch (error) {
+              return {
+                  success: false,
+                  message: `Failed to click element: ${error}`,
+              };
+          }
+      }
+      async inputText(index, text) {
+          try {
+              this.assertIndexed();
+              const element = getElementByIndex(this.selectorMap, index);
+              const elemText = this.elementTextMap.get(index);
+              this.cleanUpAfterAction();
+              await inputTextElement(element, text);
+              return {
+                  success: true,
+                  message: `Input text "${text}" into element (${elemText ?? index}).`,
+              };
+          }
+          catch (error) {
+              return {
+                  success: false,
+                  message: `Failed to input text: ${error}`,
+              };
+          }
+      }
+      async selectOption(index, optionText) {
+          try {
+              this.assertIndexed();
+              const element = getElementByIndex(this.selectorMap, index);
+              const elemText = this.elementTextMap.get(index);
+              this.cleanUpAfterAction();
+              await selectOptionElement(element, optionText);
+              return {
+                  success: true,
+                  message: `Selected option "${optionText}" in element (${elemText ?? index}).`,
+              };
+          }
+          catch (error) {
+              return {
+                  success: false,
+                  message: `Failed to select option: ${error}`,
+              };
+          }
+      }
+      async scroll(options) {
+          try {
+              this.assertIndexed();
+              this.cleanUpAfterAction();
+              const { direction, amount, index } = options;
+              const element = index !== undefined
+                  ? getElementByIndex(this.selectorMap, index)
+                  : null;
+              let message;
+              if (direction === "left" || direction === "right") {
+                  const pixels = amount ?? window.innerWidth * 0.8;
+                  message = await scrollHorizontally(direction === "right", pixels, element);
+              }
+              else {
+                  const pixels = amount ?? window.innerHeight * 0.8;
+                  const scrollAmount = direction === "down" ? pixels : -pixels;
+                  message = await scrollVertically(direction === "down", scrollAmount, element);
+              }
+              return { success: true, message };
+          }
+          catch (error) {
+              return {
+                  success: false,
+                  message: `Failed to scroll: ${error}`,
+              };
+          }
+      }
+      dispose() {
+          cleanUpHighlights();
+          this.flatTree = null;
+          this.selectorMap.clear();
+          this.elementTextMap.clear();
+          this.simplifiedHTML = "";
+          this.isIndexed = false;
+      }
+  }
+
+  /**
+   * Hypha RPC service wrappers for the PageController.
+   *
+   * These functions are schema-annotated for AI agent / LLM tool calling.
+   * They provide smart DOM analysis with indexed interactive elements,
+   * enabling agents to interact with pages by element index instead of
+   * fragile CSS selectors.
+   */
+  // Singleton — shared across all service calls
+  let controller = null;
+  function getController() {
+      if (!controller) {
+          controller = new PageController({
+              viewportExpansion: -1, // full page by default
+              highlightOpacity: 0.1, // 10% fill on element boxes
+              highlightLabelOpacity: 0.5, // 50% opacity on number labels + borders
+          });
+      }
+      return controller;
+  }
+  /**
+   * Get the current browser state: page info, scroll position, and a
+   * simplified HTML representation with all interactive elements indexed
+   * as [0], [1], [2], etc. Use the indices to call click_element_by_index,
+   * input_text, select_option, or scroll.
+   */
+  async function getBrowserState(viewport_only) {
+      const ctrl = getController();
+      if (viewport_only !== undefined) {
+          ctrl.config.viewportExpansion = viewport_only ? 0 : -1;
+      }
+      return ctrl.getBrowserState();
+  }
+  getBrowserState.__schema__ = {
+      name: "getBrowserState",
+      description: "Get the current page state with all interactive elements indexed as [0], [1], [2], etc. " +
+          "Returns a simplified HTML representation optimized for LLM consumption. " +
+          "Interactive elements (buttons, links, inputs, scrollable areas) are detected via smart heuristics " +
+          "(CSS cursor, ARIA roles, event listeners, tag names). " +
+          "Use the returned indices with click_element_by_index, input_text, select_option, or scroll. " +
+          "Call this first to understand the page before performing any actions.",
+      parameters: {
+          type: "object",
+          properties: {
+              viewport_only: {
+                  type: "boolean",
+                  description: "If true, only return elements visible in the current viewport. Default: false (full page).",
+              },
+          },
+      },
+  };
+  /**
+   * Click an interactive element by its index from get_browser_state.
+   */
+  async function clickElementByIndex(index) {
+      return getController().clickElement(index);
+  }
+  clickElementByIndex.__schema__ = {
+      name: "clickElementByIndex",
+      description: "Click an interactive element by its numeric index from get_browser_state output. " +
+          "Simulates a full mouse event sequence (hover, mousedown, focus, mouseup, click) " +
+          "to trigger all event listeners including React/Vue handlers.",
+      parameters: {
+          type: "object",
+          properties: {
+              index: {
+                  type: "number",
+                  description: "The element index from get_browser_state (e.g. 0 for [0], 5 for [5]).",
+              },
+          },
+          required: ["index"],
+      },
+  };
+  /**
+   * Type text into an input, textarea, or contenteditable element by index.
+   */
+  async function inputText(index, text) {
+      return getController().inputText(index, text);
+  }
+  inputText.__schema__ = {
+      name: "inputText",
+      description: "Type text into an input, textarea, or contenteditable element by its index. " +
+          "Replaces existing content. Works with React controlled components, " +
+          "contenteditable editors (LinkedIn, Quill), and native inputs.",
+      parameters: {
+          type: "object",
+          properties: {
+              index: {
+                  type: "number",
+                  description: "The element index from get_browser_state.",
+              },
+              text: {
+                  type: "string",
+                  description: "The text to type into the element.",
+              },
+          },
+          required: ["index", "text"],
+      },
+  };
+  /**
+   * Select a dropdown option by element index and option text.
+   */
+  async function selectOption(index, option_text) {
+      return getController().selectOption(index, option_text);
+  }
+  selectOption.__schema__ = {
+      name: "selectOption",
+      description: "Select a dropdown option in a <select> element by its index and the visible option text.",
+      parameters: {
+          type: "object",
+          properties: {
+              index: {
+                  type: "number",
+                  description: "The <select> element index from get_browser_state.",
+              },
+              option_text: {
+                  type: "string",
+                  description: "The visible text of the option to select (case-sensitive, trimmed).",
+              },
+          },
+          required: ["index", "option_text"],
+      },
+  };
+  /**
+   * Scroll the page or a specific scrollable container.
+   */
+  async function scroll(direction, amount, index) {
+      return getController().scroll({ direction, amount, index });
+  }
+  scroll.__schema__ = {
+      name: "scroll",
+      description: "Scroll the page or a specific scrollable container. " +
+          "If index is provided, scrolls the nearest scrollable ancestor of that element. " +
+          "Otherwise scrolls the page or the largest scrollable container.",
+      parameters: {
+          type: "object",
+          properties: {
+              direction: {
+                  type: "string",
+                  enum: ["up", "down", "left", "right"],
+                  description: "Scroll direction.",
+              },
+              amount: {
+                  type: "number",
+                  description: "Scroll amount in pixels. Default: ~80% of viewport height (vertical) or width (horizontal).",
+              },
+              index: {
+                  type: "number",
+                  description: "Optional element index. If provided, scrolls the nearest scrollable ancestor of this element.",
+              },
+          },
+          required: ["direction"],
+      },
+  };
+  /**
+   * Remove all visual element highlights/labels from the page.
+   */
+  async function removeHighlights() {
+      getController().cleanUpHighlights();
+      return { success: true, message: "Highlights removed." };
+  }
+  removeHighlights.__schema__ = {
+      name: "removeHighlights",
+      description: "Remove all visual element index labels/highlights from the page. " +
+          "Useful after taking a screenshot if you want a clean view.",
+      parameters: {
+          type: "object",
+          properties: {},
+      },
+  };
+  /**
+   * Dispose the page controller (for cleanup).
+   */
+  function disposeController() {
+      if (controller) {
+          controller.dispose();
+          controller = null;
+      }
+  }
+
   /**
    * Core debugger class: connects to Hypha and registers the debug service.
    */
+  /** Generate a cryptographically random hex string of `bytes` bytes. */
+  function randomHex(bytes = 8) {
+      const arr = new Uint8Array(bytes);
+      crypto.getRandomValues(arr);
+      return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
   class HyphaDebugger {
       constructor(config) {
           this.overlay = null;
+          this.cursor = null;
           this.server = null;
           this.serviceInfo = null;
+          const requireToken = config.require_token ?? false;
+          // Always append random suffix unless user provided a custom id.
+          let serviceId = config.service_id ?? "web-debugger";
+          if (!config.service_id) {
+              serviceId = `web-debugger-${randomHex(16)}`;
+          }
+          // Derive visibility: require_token mode → protected, no-token → unlisted.
+          // An explicit config.visibility always takes precedence.
+          const visibility = config.visibility ?? (requireToken ? "protected" : "unlisted");
           this.config = {
               server_url: config.server_url,
               workspace: config.workspace ?? "",
               token: config.token ?? "",
-              service_id: config.service_id ?? "web-debugger",
+              service_id: serviceId,
               service_name: config.service_name ?? "Web Debugger",
               show_ui: config.show_ui ?? true,
-              visibility: config.visibility ?? "public",
+              visibility,
+              require_token: requireToken,
           };
       }
       async start() {
@@ -10636,6 +13620,8 @@
               this.overlay = new DebugOverlay();
               this.overlay.setStatus("disconnected");
               this.overlay.setInfo({ Status: "Connecting..." });
+              // Initialize animated AI cursor
+              this.cursor = new AICursor();
           }
           try {
               // Get the connectToServer function
@@ -10682,6 +13668,9 @@
           catch {
               // Ignore unregister errors on cleanup
           }
+          disposeController();
+          this.cursor?.destroy();
+          this.cursor = null;
           this.overlay?.destroy();
           this.overlay = null;
           const w = window;
@@ -10696,9 +13685,12 @@
        */
       async updateSession(extra) {
           const fullServiceId = this.serviceInfo?.id ?? this.config.service_id;
-          const sessionToken = await this.server.generateToken();
           const serviceUrl = this.buildServiceUrl(fullServiceId);
           const workspace = this.server.config?.workspace ?? "";
+          // In no-token mode the URL itself is the secret — skip token generation.
+          const sessionToken = this.config.require_token
+              ? await this.server.generateToken({ expires_in: 86400 })
+              : "";
           if (this.overlay) {
               this.overlay.setStatus("connected");
               this.overlay.setInfo({
@@ -10709,8 +13701,13 @@
               this.overlay.setInstructions(this.buildInstructionBlock(serviceUrl, sessionToken));
           }
           console.log(`[hypha-debugger] Service URL: ${serviceUrl}`);
-          console.log(`[hypha-debugger] Token: ${sessionToken}`);
-          console.log(`[hypha-debugger] Test:\n  curl '${serviceUrl}/get_page_info?_mode=last' -H 'Authorization: Bearer ${sessionToken}'`);
+          if (sessionToken) {
+              console.log(`[hypha-debugger] Token: ${sessionToken}`);
+              console.log(`[hypha-debugger] Test:\n  curl '${serviceUrl}/get_page_info' -H 'Authorization: Bearer ${sessionToken}'`);
+          }
+          else {
+              console.log(`[hypha-debugger] Test:\n  curl '${serviceUrl}/get_page_info'`);
+          }
           const session = {
               service_id: fullServiceId,
               workspace,
@@ -10772,13 +13769,20 @@
               get_page_info: this.wrapFn(getPageInfo, "get_page_info"),
               get_html: this.wrapFn(getHtml, "get_html"),
               query_dom: this.wrapFn(queryDom, "query_dom"),
-              click_element: this.wrapFn(clickElement, "click_element"),
+              click_element: this.wrapFn(clickElement$1, "click_element"),
               fill_input: this.wrapFn(fillInput, "fill_input"),
               scroll_to: this.wrapFn(scrollTo, "scroll_to"),
               take_screenshot: this.wrapFn(takeScreenshot, "take_screenshot"),
               execute_script: this.wrapFn(executeScript, "execute_script"),
               navigate: this.wrapFn(navigate, "navigate"),
               get_react_tree: this.wrapFn(getReactTree, "get_react_tree"),
+              // Smart DOM analysis + index-based interaction (from page-controller)
+              get_browser_state: this.wrapFn(getBrowserState, "get_browser_state"),
+              click_element_by_index: this.wrapFn(clickElementByIndex, "click_element_by_index"),
+              input_text: this.wrapFn(inputText, "input_text"),
+              select_option: this.wrapFn(selectOption, "select_option"),
+              scroll: this.wrapFn(scroll, "scroll"),
+              remove_highlights: this.wrapFn(removeHighlights, "remove_highlights"),
               get_skill_md: this.wrapFn(this.createGetSkillMd(), "get_skill_md"),
           };
       }
@@ -10788,10 +13792,15 @@
               const schemaFns = {};
               const fns = {
                   get_page_info: getPageInfo, get_html: getHtml,
-                  query_dom: queryDom, click_element: clickElement, fill_input: fillInput,
+                  query_dom: queryDom, click_element: clickElement$1, fill_input: fillInput,
                   scroll_to: scrollTo, take_screenshot: takeScreenshot,
                   execute_script: executeScript, navigate: navigate,
                   get_react_tree: getReactTree,
+                  // Smart DOM analysis + index-based interaction
+                  get_browser_state: getBrowserState,
+                  click_element_by_index: clickElementByIndex,
+                  input_text: inputText, select_option: selectOption,
+                  scroll: scroll, remove_highlights: removeHighlights,
               };
               for (const [name, f] of Object.entries(fns)) {
                   if (f.__schema__)
@@ -10814,16 +13823,29 @@
       }
       /** Build the instruction block for the overlay panel. */
       buildInstructionBlock(serviceUrl, token) {
-          return [
-              `SERVICE_URL="${serviceUrl}"`,
-              `TOKEN="${token}"`,
-              ``,
-              `# Quick test:`,
-              `curl "$SERVICE_URL/get_page_info?_mode=last" -H "Authorization: Bearer $TOKEN"`,
+          const auth = token ? ` -H "Authorization: Bearer $TOKEN"` : "";
+          const lines = [
+              `# Hypha Remote Debugger — Web Page`,
+              `# A debugger is attached to a live web page.`,
+              `# You can remotely inspect, interact with, and control this page via the HTTP API below.`,
+              `#`,
+              `# RECOMMENDED WORKFLOW (index-based, most reliable):`,
+              `#   1. get_browser_state → see all interactive elements as [0], [1], [2], ...`,
+              `#   2. click_element_by_index / input_text / select_option / scroll → act by index`,
+              `#   3. take_screenshot → verify the result visually`,
+              `#`,
+              `# Also available: get_page_info, get_html, query_dom, click_element, fill_input,`,
+              `#   scroll_to, execute_script, navigate, get_react_tree, remove_highlights`,
+              `#`,
+              `# POST endpoints accept JSON body with parameter names as keys.`,
               ``,
-              `# Full API docs:`,
-              `curl "$SERVICE_URL/get_skill_md?_mode=last" -H "Authorization: Bearer $TOKEN"`,
-          ].join("\n");
+              `SERVICE_URL="${serviceUrl}"`,
+          ];
+          if (token) {
+              lines.push(`TOKEN="${token}"`);
+          }
+          lines.push(``, `# 1. Get interactive elements (smart DOM analysis with indexed elements):`, `curl "$SERVICE_URL/get_browser_state"${auth}`, ``, `# 2. Click element by index (e.g. click [3]):`, `curl -X POST "$SERVICE_URL/click_element_by_index"${auth} -H "Content-Type: application/json" -d '{"index": 3}'`, ``, `# 3. Type into an input by index:`, `curl -X POST "$SERVICE_URL/input_text"${auth} -H "Content-Type: application/json" -d '{"index": 5, "text": "hello"}'`, ``, `# Take a screenshot:`, `curl "$SERVICE_URL/take_screenshot"${auth}`, ``, `# Execute JavaScript remotely:`, `curl -X POST "$SERVICE_URL/execute_script"${auth} -H "Content-Type: application/json" -d '{"code": "document.title"}'`, ``, `# Full API docs:`, `curl "$SERVICE_URL/get_skill_md"${auth}`);
+          return lines.join("\n");
       }
       /** Wrap a service function with logging and kwargs-to-positional-args support. */
       wrapFn(fn, name) {
@@ -10911,7 +13933,8 @@
   /**
    * Auto-start: when loaded via <script> tag, automatically start the debugger.
    * Configuration can be provided via data-* attributes on the script tag:
-   *   data-server-url, data-workspace, data-token, data-service-id, data-no-ui
+   *   data-server-url, data-workspace, data-token, data-service-id, data-no-ui,
+   *   data-require-token
    *
    * Set data-manual to disable auto-start.
    */
@@ -10949,6 +13972,9 @@
       if (scriptEl?.hasAttribute("data-no-ui")) {
           config.show_ui = false;
       }
+      if (scriptEl?.hasAttribute("data-require-token")) {
+          config.require_token = true;
+      }
       startDebugger(config).catch((err) => {
           console.error("[hypha-debugger] Auto-start failed:", err);
       });