hypha-debugger 0.1.1 → 0.1.2

package/dist/hypha-debugger.mjs

@@ -446,6 +446,196 @@ class DebugOverlay {
     }
 }
 
+/**
+ * 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.
  */
@@ -642,7 +832,7 @@ queryDom.__schema__ = {
         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}` };
@@ -657,7 +847,7 @@ function clickElement(selector) {
     }));
     return { success: true, message: `Clicked element: ${selector}` };
 }
-clickElement.__schema__ = {
+clickElement$1.__schema__ = {
     name: "clickElement",
     description: "Click a DOM element matching the CSS selector.",
     parameters: {
@@ -2043,29 +2233,79 @@ function generateSkillMd(serviceFunctions, serviceUrl) {
         "",
         "# 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)",
+        "",
+        "The most reliable way to interact with a page is using the smart DOM analysis:",
+        "",
+        "### Step 1: Observe the page",
+        "```bash",
+        `curl '{SERVICE_URL}/get_browser_state'`,
+        "```",
+        "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 />",
+        "```",
+        "",
+        "### 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"}'`,
         "",
-        "All functions are available as HTTP endpoints. Use the service URL provided in the instructions.",
+        "# Scroll down:",
+        `curl -X POST '{SERVICE_URL}/scroll' \\`,
+        `  -H 'Content-Type: application/json' -d '{"direction": "down"}'`,
         "",
-        "**GET request** (for functions with no required parameters):",
+        "# Scroll a specific container (e.g. [4]):",
+        `curl -X POST '{SERVICE_URL}/scroll' \\`,
+        `  -H 'Content-Type: application/json' -d '{"direction": "down", "index": 4}'`,
         "```",
-        `curl '{SERVICE_URL}/get_page_info?_mode=last' -H 'Authorization: Bearer {TOKEN}'`,
+        "",
+        "### Step 3: Verify",
+        "```bash",
+        `curl '{SERVICE_URL}/take_screenshot'`,
         "```",
         "",
-        "**POST request** (for functions with parameters):",
+        "### Remove visual highlights (optional, for clean screenshots)",
+        "```bash",
+        `curl '{SERVICE_URL}/remove_highlights'`,
         "```",
-        `curl -X POST '{SERVICE_URL}/query_dom?_mode=last' \\`,
-        `  -H 'Authorization: Bearer {TOKEN}' \\`,
-        `  -H 'Content-Type: application/json' \\`,
-        `  -d '{"selector": "button"}'`,
+        "",
+        "## 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"}'`,
         "```",
         "",
-        "Replace `{SERVICE_URL}` and `{TOKEN}` with the actual values from the instruction block.",
+        "## 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
@@ -2108,8 +2348,7 @@ function generateSkillMd(serviceFunctions, serviceUrl) {
                 }
                 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("```");
@@ -2117,7 +2356,7 @@ function generateSkillMd(serviceFunctions, serviceUrl) {
             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("```");
             }
         }
@@ -2126,7 +2365,7 @@ function generateSkillMd(serviceFunctions, serviceUrl) {
             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("");
@@ -2134,239 +2373,3022 @@ function generateSkillMd(serviceFunctions, serviceUrl) {
     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");
 }
 
 /**
- * Core debugger class: connects to Hypha and registers the debug service.
+ * @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.
  */
-class HyphaDebugger {
-    constructor(config) {
-        this.overlay = null;
-        this.server = null;
-        this.serviceInfo = null;
-        this.config = {
-            server_url: config.server_url,
-            workspace: config.workspace ?? "",
-            token: config.token ?? "",
-            service_id: config.service_id ?? "web-debugger",
-            service_name: config.service_name ?? "Web Debugger",
-            show_ui: config.show_ui ?? true,
-            visibility: config.visibility ?? "public",
-        };
-    }
-    async start() {
-        // Install console capture early
-        installConsoleCapture();
-        // Guard against double-injection
-        const w = window;
-        if (w.__HYPHA_DEBUGGER__?.instance) {
-            console.warn("[hypha-debugger] Already running, returning existing session.");
-            return w.__HYPHA_DEBUGGER__.session;
-        }
-        // Show UI if enabled
-        if (this.config.show_ui) {
-            this.overlay = new DebugOverlay();
-            this.overlay.setStatus("disconnected");
-            this.overlay.setInfo({ Status: "Connecting..." });
-        }
-        try {
-            // Get the connectToServer function
-            const connect = this.getConnectToServer();
-            // Connect to Hypha server
-            const connectConfig = {
-                server_url: this.config.server_url,
-            };
-            if (this.config.workspace)
-                connectConfig.workspace = this.config.workspace;
-            if (this.config.token)
-                connectConfig.token = this.config.token;
-            this.server = await connect(connectConfig);
-            // Register debug service
-            this.serviceInfo = await this.server.registerService(this.buildServiceDefinition());
-            // Update overlay and build session
-            const session = await this.updateSession();
-            if (this.overlay) {
-                this.overlay.addLog("Service registered", "result");
-            }
-            // Store globally
-            w.__HYPHA_DEBUGGER__ = w.__HYPHA_DEBUGGER__ ?? {};
-            w.__HYPHA_DEBUGGER__.instance = this;
-            return session;
-        }
-        catch (err) {
-            console.error("[hypha-debugger] Failed to start:", err);
-            if (this.overlay) {
-                this.overlay.setStatus("error");
-                this.overlay.setInfo({
-                    Status: "Error",
-                    Error: err.message ?? String(err),
-                });
-            }
-            throw err;
-        }
-    }
-    async destroy() {
-        try {
-            if (this.serviceInfo && this.server) {
-                await this.server.unregisterService(this.serviceInfo.id);
-            }
-        }
-        catch {
-            // Ignore unregister errors on cleanup
-        }
-        this.overlay?.destroy();
-        this.overlay = null;
-        const w = window;
-        if (w.__HYPHA_DEBUGGER__) {
-            delete w.__HYPHA_DEBUGGER__.instance;
-            delete w.__HYPHA_DEBUGGER__.session;
-        }
-    }
-    /**
-     * Generate token, build service URL, update overlay instructions, and
-     * return a DebugSession.
-     */
-    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 ?? "";
-        if (this.overlay) {
-            this.overlay.setStatus("connected");
-            this.overlay.setInfo({
-                Status: "Connected",
-                Server: this.config.server_url,
-                ...extra,
-            });
-            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}'`);
-        const session = {
-            service_id: fullServiceId,
-            workspace,
-            server: this.server,
-            service_url: serviceUrl,
-            token: sessionToken,
-            destroy: () => this.destroy(),
-        };
-        // Always update global session
-        const w = window;
-        w.__HYPHA_DEBUGGER__ = w.__HYPHA_DEBUGGER__ ?? {};
-        w.__HYPHA_DEBUGGER__.session = session;
-        return session;
-    }
-    /**
-     * Build a stable, predictable service URL.
-     * Strips the clientId prefix so the URL uses only the bare service name.
-     * Callers append ?_mode=last to resolve the most recent instance.
-     */
-    buildServiceUrl(serviceId) {
-        const base = this.config.server_url.replace(/\/+$/, "");
-        const slashIdx = serviceId.indexOf("/");
-        if (slashIdx !== -1) {
-            const workspace = serviceId.substring(0, slashIdx);
-            const svcPart = serviceId.substring(slashIdx + 1);
-            // Strip clientId: "abc123:web-debugger" → "web-debugger"
-            const colonIdx = svcPart.indexOf(":");
-            const svcName = colonIdx !== -1 ? svcPart.substring(colonIdx + 1) : svcPart;
-            return `${base}/${workspace}/services/${svcName}`;
-        }
-        return `${base}/services/${serviceId}`;
-    }
-    getHyphaModule() {
-        // Check the static import (works when hypha-rpc is bundled or npm-installed)
-        if (hyphaRpc.connectToServer)
-            return hyphaRpc;
-        // hypha-rpc re-exports under a namespace
-        if (hyphaRpc.hyphaWebsocketClient?.connectToServer)
-            return hyphaRpc.hyphaWebsocketClient;
-        // Fall back to global (when hypha-rpc loaded via separate script tag)
-        const w = window;
-        if (w.hyphaWebsocketClient?.connectToServer)
-            return w.hyphaWebsocketClient;
-        throw new Error("hypha-rpc not found. Install it via npm or load it via: " +
-            '<script src="https://cdn.jsdelivr.net/npm/hypha-rpc@0.20.97/dist/hypha-rpc-websocket.min.js"></script>');
-    }
-    getConnectToServer() {
-        return this.getHyphaModule().connectToServer;
-    }
-    buildServiceDefinition() {
-        return {
-            id: this.config.service_id,
-            name: this.config.service_name,
-            type: "debugger",
-            description: "Remote web page debugger. Allows inspecting DOM, taking screenshots, executing JavaScript, and interacting with the page.",
-            config: {
-                visibility: this.config.visibility,
-            },
-            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"),
-            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"),
-            get_skill_md: this.wrapFn(this.createGetSkillMd(), "get_skill_md"),
-        };
-    }
-    createGetSkillMd() {
-        const fn = () => {
-            // Build a schema-only map (avoid calling buildServiceDefinition which would recurse)
-            const schemaFns = {};
-            const fns = {
-                get_page_info: getPageInfo, get_html: getHtml,
-                query_dom: queryDom, click_element: clickElement, fill_input: fillInput,
-                scroll_to: scrollTo, take_screenshot: takeScreenshot,
-                execute_script: executeScript, navigate: navigate,
-                get_react_tree: getReactTree,
-            };
-            for (const [name, f] of Object.entries(fns)) {
-                if (f.__schema__)
-                    schemaFns[name] = f;
-            }
-            this.serviceInfo
-                ? this.buildServiceUrl(this.serviceInfo.id ?? this.config.service_id)
-                : "{SERVICE_URL}";
-            return generateSkillMd(schemaFns);
-        };
-        fn.__schema__ = {
-            name: "getSkillMd",
-            description: "Get the SKILL.md document describing all available debugger functions, their parameters, and usage examples. Follows the agentskills.io specification.",
-            parameters: {
-                type: "object",
-                properties: {},
-            },
-        };
-        return fn;
-    }
-    /** 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"`,
-            ``,
-            `# Full API docs:`,
-            `curl "$SERVICE_URL/get_skill_md?_mode=last" -H "Authorization: Bearer $TOKEN"`,
-        ].join("\n");
+
+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: serviceId,
+            service_name: config.service_name ?? "Web Debugger",
+            show_ui: config.show_ui ?? true,
+            visibility,
+            require_token: requireToken,
+        };
+    }
+    async start() {
+        // Install console capture early
+        installConsoleCapture();
+        // Guard against double-injection
+        const w = window;
+        if (w.__HYPHA_DEBUGGER__?.instance) {
+            console.warn("[hypha-debugger] Already running, returning existing session.");
+            return w.__HYPHA_DEBUGGER__.session;
+        }
+        // Show UI if enabled
+        if (this.config.show_ui) {
+            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
+            const connect = this.getConnectToServer();
+            // Connect to Hypha server
+            const connectConfig = {
+                server_url: this.config.server_url,
+            };
+            if (this.config.workspace)
+                connectConfig.workspace = this.config.workspace;
+            if (this.config.token)
+                connectConfig.token = this.config.token;
+            this.server = await connect(connectConfig);
+            // Register debug service
+            this.serviceInfo = await this.server.registerService(this.buildServiceDefinition());
+            // Update overlay and build session
+            const session = await this.updateSession();
+            if (this.overlay) {
+                this.overlay.addLog("Service registered", "result");
+            }
+            // Store globally
+            w.__HYPHA_DEBUGGER__ = w.__HYPHA_DEBUGGER__ ?? {};
+            w.__HYPHA_DEBUGGER__.instance = this;
+            return session;
+        }
+        catch (err) {
+            console.error("[hypha-debugger] Failed to start:", err);
+            if (this.overlay) {
+                this.overlay.setStatus("error");
+                this.overlay.setInfo({
+                    Status: "Error",
+                    Error: err.message ?? String(err),
+                });
+            }
+            throw err;
+        }
+    }
+    async destroy() {
+        try {
+            if (this.serviceInfo && this.server) {
+                await this.server.unregisterService(this.serviceInfo.id);
+            }
+        }
+        catch {
+            // Ignore unregister errors on cleanup
+        }
+        disposeController();
+        this.cursor?.destroy();
+        this.cursor = null;
+        this.overlay?.destroy();
+        this.overlay = null;
+        const w = window;
+        if (w.__HYPHA_DEBUGGER__) {
+            delete w.__HYPHA_DEBUGGER__.instance;
+            delete w.__HYPHA_DEBUGGER__.session;
+        }
+    }
+    /**
+     * Generate token, build service URL, update overlay instructions, and
+     * return a DebugSession.
+     */
+    async updateSession(extra) {
+        const fullServiceId = this.serviceInfo?.id ?? this.config.service_id;
+        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({
+                Status: "Connected",
+                Server: this.config.server_url,
+                ...extra,
+            });
+            this.overlay.setInstructions(this.buildInstructionBlock(serviceUrl, sessionToken));
+        }
+        console.log(`[hypha-debugger] Service URL: ${serviceUrl}`);
+        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,
+            server: this.server,
+            service_url: serviceUrl,
+            token: sessionToken,
+            destroy: () => this.destroy(),
+        };
+        // Always update global session
+        const w = window;
+        w.__HYPHA_DEBUGGER__ = w.__HYPHA_DEBUGGER__ ?? {};
+        w.__HYPHA_DEBUGGER__.session = session;
+        return session;
+    }
+    /**
+     * Build a stable, predictable service URL.
+     * Strips the clientId prefix so the URL uses only the bare service name.
+     * Callers append ?_mode=last to resolve the most recent instance.
+     */
+    buildServiceUrl(serviceId) {
+        const base = this.config.server_url.replace(/\/+$/, "");
+        const slashIdx = serviceId.indexOf("/");
+        if (slashIdx !== -1) {
+            const workspace = serviceId.substring(0, slashIdx);
+            const svcPart = serviceId.substring(slashIdx + 1);
+            // Strip clientId: "abc123:web-debugger" → "web-debugger"
+            const colonIdx = svcPart.indexOf(":");
+            const svcName = colonIdx !== -1 ? svcPart.substring(colonIdx + 1) : svcPart;
+            return `${base}/${workspace}/services/${svcName}`;
+        }
+        return `${base}/services/${serviceId}`;
+    }
+    getHyphaModule() {
+        // Check the static import (works when hypha-rpc is bundled or npm-installed)
+        if (hyphaRpc.connectToServer)
+            return hyphaRpc;
+        // hypha-rpc re-exports under a namespace
+        if (hyphaRpc.hyphaWebsocketClient?.connectToServer)
+            return hyphaRpc.hyphaWebsocketClient;
+        // Fall back to global (when hypha-rpc loaded via separate script tag)
+        const w = window;
+        if (w.hyphaWebsocketClient?.connectToServer)
+            return w.hyphaWebsocketClient;
+        throw new Error("hypha-rpc not found. Install it via npm or load it via: " +
+            '<script src="https://cdn.jsdelivr.net/npm/hypha-rpc@0.20.97/dist/hypha-rpc-websocket.min.js"></script>');
+    }
+    getConnectToServer() {
+        return this.getHyphaModule().connectToServer;
+    }
+    buildServiceDefinition() {
+        return {
+            id: this.config.service_id,
+            name: this.config.service_name,
+            type: "debugger",
+            description: "Remote web page debugger. Allows inspecting DOM, taking screenshots, executing JavaScript, and interacting with the page.",
+            config: {
+                visibility: this.config.visibility,
+            },
+            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$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"),
+        };
+    }
+    createGetSkillMd() {
+        const fn = () => {
+            // Build a schema-only map (avoid calling buildServiceDefinition which would recurse)
+            const schemaFns = {};
+            const fns = {
+                get_page_info: getPageInfo, get_html: getHtml,
+                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__)
+                    schemaFns[name] = f;
+            }
+            this.serviceInfo
+                ? this.buildServiceUrl(this.serviceInfo.id ?? this.config.service_id)
+                : "{SERVICE_URL}";
+            return generateSkillMd(schemaFns);
+        };
+        fn.__schema__ = {
+            name: "getSkillMd",
+            description: "Get the SKILL.md document describing all available debugger functions, their parameters, and usage examples. Follows the agentskills.io specification.",
+            parameters: {
+                type: "object",
+                properties: {},
+            },
+        };
+        return fn;
+    }
+    /** Build the instruction block for the overlay panel. */
+    buildInstructionBlock(serviceUrl, 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.`,
+            ``,
+            `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) {
@@ -2454,7 +5476,8 @@ async function startDebugger(config) {
 /**
  * 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.
  */
@@ -2492,6 +5515,9 @@ function autoStart() {
     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);
     });