app-manager-edge-worker 1.1.5 → 1.2.1

package/README.md

@@ -203,6 +203,25 @@ Log levels: `[INFO]` · `[SUCCESS]` · `[WARN]` · `[ERROR]` · `[TASK]` (job di
 
 ## 📝 Changelog
 
+### v1.2.1
+- **Smart Form Field & Leaf Control Element Resolution**:
+  - Replaced single-surface `elementFromPoint` with full-stack `elementsFromPoint` coordinate sampling and multi-offset probing.
+  - Implemented intelligent priority scoring favoring form inputs (`<input>`, `<textarea>`, `<select>`), captcha images (`<img>`, `<canvas>`), and interactive action buttons over generic wrapper `<div>` tags.
+  - Added severe scoring penalties (-50,000) for full-screen dimmer overlays, modal backdrops (`div.dimmer-holder`, `div.ui.dimmer`, `div.backdrop`), and transparent blocker masks.
+  - Added automatic container drill-down to pick child form inputs when clicking inside input groups or labels.
+  - Extended candidate selector generation to include form `name`, `placeholder`, `type`, and image `alt`/`captcha` attributes.
+  - Added stacked `alternates` metadata return for rapid element switching in the Visual Element Inspector.
+
+### v1.2.0
+- **Human-In-The-Loop (HITL) Interactive Scraping Engine**:
+  - Added stateful interactive session handlers: `HITL_SESSION_INIT`, `HITL_SESSION_REFRESH`, `HITL_SESSION_SOLVE`, and `HITL_SESSION_ABORT`.
+  - Automated form field pre-filling (GSTIN, PAN, registration numbers) with clear-first input semantics.
+  - Direct DOM element screenshotting for precise visual captcha capture (`imageSelector`).
+  - MD5 visual pixel hash comparison and DOM `src` watcher for guaranteed captcha refresh verification.
+  - Post-submit dual-outcome race between success selectors and in-page error messages (handling HTTP 200 responses with error banners).
+  - Fast-retry loop: on invalid captcha entry, preserves active browser page, resets TTL timer, and captures newly regenerated captcha without restarting form from scratch.
+  - Resource protection with active session maps and configurable TTL auto-close timers to prevent worker memory leaks.
+
 ### v1.1.5
 - **Real-Time WhatsApp Task & Document Streaming Telemetry**:
   - Added timestamped terminal logging for incoming WhatsApp text and document task receipts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "app-manager-edge-worker",
-  "version": "1.1.5",
+  "version": "1.2.1",
   "description": "Distributed Scraper Edge Worker for Apps Manager. Run on any local machine, VPS, or Termux Android device to serve browser and HTTP scraping jobs.",
   "type": "module",
   "bin": {

package/src/banner.js

@@ -1,7 +1,7 @@
 import { createRequire } from "module";
 
 const require = createRequire(import.meta.url);
-let workerVersion = "1.1.5";
+let workerVersion = "1.2.1";
 try {
     const pkg = require("../package.json");
     if (pkg?.version) workerVersion = pkg.version;

package/src/client.js

@@ -8,11 +8,17 @@ import { handleChromiumScrape, handleHttpScrape } from "./handlers/scrapeHandler
 import { handlePreviewPage, handleInspectElement } from "./handlers/previewHandler.js";
 import { handleSendEmail } from "./handlers/mailHandler.js";
 import { handleAiSmartRepair } from "./handlers/aiRepairHandler.js";
+import {
+    handleInteractiveSessionInit,
+    handleInteractiveSessionRefresh,
+    handleInteractiveSessionSolve,
+    handleInteractiveSessionAbort,
+} from "./handlers/interactiveHandler.js";
 import fs from "fs";
 import { getWhatsAppHandler } from "./handlers/whatsappHandler.js";
 import { printBanner, logInfo, logSuccess, logWarn, logError, logJob } from "./banner.js";
 
-let workerPkgVersion = "1.1.5";
+let workerPkgVersion = "1.2.1";
 try {
     const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
     if (pkg?.version) workerPkgVersion = pkg.version;
@@ -249,6 +255,14 @@ export async function startWorkerClient(config) {
                 resultData = await waHandler.sendDocument(payload);
             } else if (jobType === "WHATSAPP_RECONCILE") {
                 resultData = await waHandler.reconcileDelivery(payload.recipientPhone, payload.idempotencyKey);
+            } else if (jobType === "HITL_SESSION_INIT") {
+                resultData = await handleInteractiveSessionInit(payload);
+            } else if (jobType === "HITL_SESSION_REFRESH") {
+                resultData = await handleInteractiveSessionRefresh(payload);
+            } else if (jobType === "HITL_SESSION_SOLVE") {
+                resultData = await handleInteractiveSessionSolve(payload);
+            } else if (jobType === "HITL_SESSION_ABORT") {
+                resultData = await handleInteractiveSessionAbort(payload);
             } else {
                 throw new Error(`Unsupported job type: ${jobType}`);
             }

package/src/handlers/interactiveHandler.js

@@ -0,0 +1,466 @@
+import crypto from "crypto";
+import localBrowserManager from "../browser.js";
+import { runTransformPipeline, castValueToType } from "./transformUtils.js";
+
+/**
+ * In-memory map of active interactive sessions on this Edge Worker.
+ * sessionId -> { page, timeoutTimer, createdAt, url, captchaConfig, fieldMappings, collections }
+ */
+const activeSessions = new Map();
+
+/**
+ * Extracts a single field from a Puppeteer page given a strategy.
+ */
+async function extractBrowserField(page, strategy) {
+    if (!strategy || !strategy.value) return null;
+
+    try {
+        const type = strategy.type || "css";
+        const attr = strategy.attribute || "text";
+
+        if (type === "css") {
+            const el = await page.$(strategy.value);
+            if (!el) return null;
+
+            if (attr === "text") {
+                const text = await page.evaluate((element) => element.textContent, el);
+                return text ? text.trim() : null;
+            } else if (attr === "html") {
+                return await page.evaluate((element) => element.innerHTML, el);
+            } else {
+                const val = await page.evaluate((element, a) => element.getAttribute(a), el, attr);
+                return val !== null && val !== undefined ? String(val).trim() : null;
+            }
+        }
+
+        if (type === "xpath") {
+            const val = await page.evaluate(
+                (xpathStr, attrName) => {
+                    try {
+                        const result = document.evaluate(
+                            xpathStr,
+                            document,
+                            null,
+                            XPathResult.FIRST_ORDERED_NODE_TYPE,
+                            null
+                        );
+                        const node = result.singleNodeValue;
+                        if (!node) return null;
+                        if (attrName === "text") {
+                            return node.textContent ? node.textContent.trim() : null;
+                        }
+                        return node.getAttribute ? node.getAttribute(attrName) : null;
+                    } catch (e) {
+                        return null;
+                    }
+                },
+                strategy.value,
+                attr
+            );
+            return val;
+        }
+
+        return null;
+    } catch (_) {
+        return null;
+    }
+}
+
+/**
+ * Closes and purges an interactive session safely.
+ */
+async function purgeSession(sessionId) {
+    const session = activeSessions.get(sessionId);
+    if (!session) return;
+
+    if (session.timeoutTimer) {
+        clearTimeout(session.timeoutTimer);
+    }
+
+    try {
+        if (session.page && !session.page.isClosed()) {
+            await session.page.close().catch(() => {});
+        }
+    } catch (_) {}
+
+    activeSessions.delete(sessionId);
+}
+
+/**
+ * 1. Handles HITL_SESSION_INIT:
+ *    Launches page, pre-fills initial form inputs, captures captcha screenshot,
+ *    and keeps the page alive with an auto-close TTL timer.
+ */
+export async function handleInteractiveSessionInit(payload) {
+    const {
+        sessionId,
+        url,
+        formInputs = [],
+        captchaConfig = {},
+        preScrapeActions = [],
+        authentication = null,
+        timeoutMs = 30000,
+        fieldMappings = [],
+        collections = [],
+    } = payload;
+
+    if (!sessionId || !url) {
+        throw new Error("sessionId and url are required for HITL_SESSION_INIT");
+    }
+
+    // Clean up any existing session with this ID
+    if (activeSessions.has(sessionId)) {
+        await purgeSession(sessionId);
+    }
+
+    const browser = await localBrowserManager.getBrowser();
+    const page = await browser.newPage();
+
+    try {
+        await page.setViewport({ width: 1366, height: 900, deviceScaleFactor: 1 });
+
+        // Apply authentication headers or cookies if provided
+        if (authentication) {
+            if (authentication.type === "COOKIES" && Array.isArray(authentication.cookies)) {
+                const parsedUrl = new URL(url);
+                await page
+                    .setCookie(
+                        ...authentication.cookies.map((c) => ({
+                            name: c.name,
+                            value: c.value,
+                            domain: c.domain || parsedUrl.hostname,
+                            path: c.path || "/",
+                        }))
+                    )
+                    .catch(() => {});
+            }
+            if (authentication.type === "HEADERS" && authentication.headers) {
+                await page.setExtraHTTPHeaders(authentication.headers).catch(() => {});
+            }
+        }
+
+        // Navigate to target portal
+        await page.goto(url, { waitUntil: "domcontentloaded", timeout: timeoutMs });
+        try {
+            await page.waitForNetworkIdle({ idleTime: 500, timeout: 3500 }).catch(() => {});
+        } catch (_) {}
+
+        // Execute pre-scrape actions if present
+        if (Array.isArray(preScrapeActions) && preScrapeActions.length > 0) {
+            for (const action of preScrapeActions) {
+                try {
+                    const actType = (action.type || action.actionType || "").toUpperCase();
+                    if (actType === "CLICK" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: action.timeoutMs || 4000 });
+                        await page.click(action.selector);
+                    } else if (actType === "TYPE" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: action.timeoutMs || 4000 });
+                        await page.type(action.selector, action.value || "", { delay: 30 });
+                    } else if (actType === "WAIT_FOR" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: action.timeoutMs || 8000 });
+                    }
+                    if (action.delayMs > 0) {
+                        await new Promise((r) => setTimeout(r, Math.min(action.delayMs, 4000)));
+                    }
+                } catch (actErr) {
+                    if (action.optional === false) throw actErr;
+                }
+            }
+        }
+
+        // Fill Form Inputs (e.g. GSTIN, PAN, registration number)
+        if (Array.isArray(formInputs) && formInputs.length > 0) {
+            for (const input of formInputs) {
+                if (!input.selector || input.value === undefined || input.value === null) continue;
+                await page.waitForSelector(input.selector, { timeout: 6000 });
+
+                if (input.clearFirst !== false) {
+                    await page.click(input.selector, { clickCount: 3 }).catch(() => {});
+                    await page.keyboard.press("Backspace").catch(() => {});
+                }
+
+                if (input.actionType === "SELECT") {
+                    await page.select(input.selector, String(input.value));
+                } else {
+                    await page.type(input.selector, String(input.value), { delay: input.delayMs || 30 });
+                }
+
+                await new Promise((r) => setTimeout(r, 150));
+            }
+        }
+
+        // Locate and Screenshot Captcha DOM Element
+        const imageSelector = captchaConfig.imageSelector || "img[src*='captcha'], #imgCaptcha, #captchaImg";
+        await page.waitForSelector(imageSelector, { timeout: 8000 });
+
+        const captchaElement = await page.$(imageSelector);
+        if (!captchaElement) {
+            throw new Error(`Captcha element not found with selector: ${imageSelector}`);
+        }
+
+        // Capture screenshot of the exact visual captcha DOM node
+        const screenshotBuffer = await captchaElement.screenshot({
+            encoding: "binary",
+            type: "png",
+        });
+        const imageBase64 = Buffer.from(screenshotBuffer).toString("base64");
+
+        const sessionTtlSeconds = captchaConfig.sessionTimeoutSeconds || 90;
+
+        // Set auto-purge timer to prevent resource leaks
+        const timeoutTimer = setTimeout(() => {
+            purgeSession(sessionId).catch(() => {});
+        }, sessionTtlSeconds * 1000);
+
+        // Store active session in memory
+        activeSessions.set(sessionId, {
+            page,
+            timeoutTimer,
+            createdAt: Date.now(),
+            url,
+            captchaConfig,
+            fieldMappings,
+            collections,
+        });
+
+        return {
+            sessionId,
+            imageBase64: `data:image/png;base64,${imageBase64}`,
+            expiresInSeconds: sessionTtlSeconds,
+        };
+    } catch (err) {
+        await page.close().catch(() => {});
+        throw err;
+    }
+}
+
+/**
+ * 2. Handles HITL_SESSION_REFRESH:
+ *    Clicks the refresh button and verifies the visual MD5 hash of the captcha changed.
+ */
+export async function handleInteractiveSessionRefresh(payload) {
+    const { sessionId, captchaConfig = {} } = payload;
+    const session = activeSessions.get(sessionId);
+
+    if (!session || !session.page || session.page.isClosed()) {
+        throw new Error("Interactive session not found or already expired");
+    }
+
+    const { page } = session;
+    const cfg = { ...session.captchaConfig, ...captchaConfig };
+    const imageSelector = cfg.imageSelector || "img[src*='captcha'], #imgCaptcha";
+    const refreshSelector = cfg.refreshSelector;
+
+    if (!refreshSelector) {
+        throw new Error("refreshSelector is not configured for this captcha");
+    }
+
+    // 1. Snapshot current image hash and src attribute
+    const oldEl = await page.$(imageSelector);
+    if (!oldEl) {
+        throw new Error(`Captcha element not found with selector: ${imageSelector}`);
+    }
+
+    const oldBuffer = await oldEl.screenshot({ encoding: "binary" });
+    const oldHash = crypto.createHash("md5").update(oldBuffer).digest("hex");
+
+    const oldSrc = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        return el ? el.getAttribute("src") : null;
+    }, imageSelector);
+
+    // 2. Click the reload button
+    await page.waitForSelector(refreshSelector, { timeout: 3000 });
+    await page.click(refreshSelector);
+
+    // 3. Wait for src attribute change first
+    await page
+        .waitForFunction(
+            (sel, prevSrc) => {
+                const el = document.querySelector(sel);
+                return el && el.getAttribute("src") !== prevSrc;
+            },
+            { timeout: 3500 },
+            imageSelector,
+            oldSrc
+        )
+        .catch(() => {});
+
+    // 4. Verify visual pixel change via MD5 hash check
+    let newBuffer = null;
+    let retries = 0;
+
+    while (retries < 6) {
+        await new Promise((r) => setTimeout(r, 350));
+        const newEl = await page.$(imageSelector);
+        if (newEl) {
+            newBuffer = await newEl.screenshot({ encoding: "binary" });
+            const newHash = crypto.createHash("md5").update(newBuffer).digest("hex");
+            if (newHash !== oldHash) {
+                break; // Verified fresh captcha
+            }
+        }
+        retries++;
+    }
+
+    if (!newBuffer) {
+        newBuffer = await oldEl.screenshot({ encoding: "binary" });
+    }
+
+    const imageBase64 = Buffer.from(newBuffer).toString("base64");
+    return {
+        sessionId,
+        imageBase64: `data:image/png;base64,${imageBase64}`,
+    };
+}
+
+/**
+ * 3. Handles HITL_SESSION_SOLVE:
+ *    Types the captcha solution, clicks submit, and performs a post-submit race.
+ *    If captcha is invalid, keeps session alive and snaps new captcha for retry.
+ *    If success, extracts data and closes page.
+ */
+export async function handleInteractiveSessionSolve(payload) {
+    const { sessionId, captchaSolution, captchaConfig = {}, fieldMappings = [], collections = [] } = payload;
+    const session = activeSessions.get(sessionId);
+
+    if (!session || !session.page || session.page.isClosed()) {
+        throw new Error("Interactive session not found or already expired");
+    }
+
+    const { page } = session;
+    const cfg = { ...session.captchaConfig, ...captchaConfig };
+    const mappings = fieldMappings.length > 0 ? fieldMappings : session.fieldMappings || [];
+    const colls = collections.length > 0 ? collections : session.collections || [];
+
+    const inputSelector = cfg.inputSelector || "#captcha, input[name='captcha']";
+    const submitSelector = cfg.submitSelector || "button[type='submit']";
+    const successSelector = cfg.waitForAfterSubmit?.selector || ".table-responsive, table, .result-pane";
+    const errorSelector = cfg.errorDetection?.selector || ".alert-danger, .has-error, #error-msg, .ui-messages-error";
+    const invalidPattern = cfg.errorDetection?.invalidCaptchaPattern || "captcha.*(incorrect|invalid|wrong|mismatch|enter text)";
+
+    // 1. Type captcha solution
+    await page.waitForSelector(inputSelector, { timeout: 4000 });
+    await page.click(inputSelector, { clickCount: 3 }).catch(() => {});
+    await page.keyboard.press("Backspace").catch(() => {});
+    await page.type(inputSelector, String(captchaSolution).trim(), { delay: 35 });
+
+    // 2. Click submit button
+    await page.waitForSelector(submitSelector, { timeout: 4000 });
+    await page.click(submitSelector);
+
+    // 3. Post-Submit Race: Wait for Success Selector OR Error Selector
+    const matchedOutcome = await page
+        .waitForFunction(
+            (succ, err) => {
+                if (document.querySelector(succ)) return "SUCCESS";
+                const errEl = document.querySelector(err);
+                if (errEl && errEl.innerText && errEl.innerText.trim().length > 0) return "ERROR";
+                return null;
+            },
+            { timeout: cfg.waitForAfterSubmit?.timeoutMs || 15000 },
+            successSelector,
+            errorSelector
+        )
+        .then((handle) => handle.jsonValue())
+        .catch(() => "TIMEOUT");
+
+    // Case A: Success Result Page
+    if (matchedOutcome === "SUCCESS") {
+        const raw = {};
+        for (const mapping of mappings) {
+            let val = null;
+            const strategies = mapping.strategies || (mapping.strategy ? [mapping.strategy] : []);
+            for (const strat of strategies) {
+                val = await extractBrowserField(page, strat);
+                if (val !== null && val !== undefined && val !== "") break;
+            }
+
+            if (mapping.transforms && mapping.transforms.length > 0) {
+                val = runTransformPipeline(val, mapping.transforms);
+            }
+            if (mapping.type) {
+                val = castValueToType(val, mapping.type);
+            }
+            raw[mapping.field || mapping.key] = val;
+        }
+
+        // Clean up session and close page
+        await purgeSession(sessionId);
+
+        return {
+            status: "COMPLETED",
+            success: true,
+            data: raw,
+        };
+    }
+
+    // Case B: In-Page Error Banner Detected
+    if (matchedOutcome === "ERROR") {
+        const errorText = await page.evaluate((sel) => {
+            const el = document.querySelector(sel);
+            return el ? el.innerText.trim() : "";
+        }, errorSelector);
+
+        const regex = new RegExp(invalidPattern, "i");
+        const isCaptchaError = regex.test(errorText);
+
+        if (isCaptchaError) {
+            // Keep page alive! Reset TTL timer for retry
+            if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+            const retryTtlSeconds = cfg.sessionTimeoutSeconds || 90;
+            session.timeoutTimer = setTimeout(() => {
+                purgeSession(sessionId).catch(() => {});
+            }, retryTtlSeconds * 1000);
+
+            // Give the target portal 400ms to re-render the refreshed captcha image
+            await new Promise((r) => setTimeout(r, 400));
+            const imageSelector = cfg.imageSelector || "img[src*='captcha'], #imgCaptcha";
+            const newCaptchaEl = await page.$(imageSelector);
+            let newImageBase64 = null;
+
+            if (newCaptchaEl) {
+                const newBuffer = await newCaptchaEl.screenshot({ encoding: "binary", type: "png" });
+                newImageBase64 = `data:image/png;base64,${Buffer.from(newBuffer).toString("base64")}`;
+            }
+
+            return {
+                status: "INVALID_CAPTCHA",
+                success: false,
+                message: errorText || "The captcha entered was incorrect.",
+                canRetry: true,
+                newImageBase64,
+            };
+        } else {
+            // Business error (e.g. "No record found for this number")
+            await purgeSession(sessionId);
+            return {
+                status: "BUSINESS_ERROR",
+                success: false,
+                message: errorText || "Target portal returned an error.",
+                canRetry: false,
+            };
+        }
+    }
+
+    // Case C: Timeout
+    await purgeSession(sessionId);
+    return {
+        status: "TIMEOUT",
+        success: false,
+        message: "Target portal did not respond with results within the expected time window.",
+        canRetry: false,
+    };
+}
+
+/**
+ * 4. Handles HITL_SESSION_ABORT:
+ *    Explicit client abort or session abandonment.
+ */
+export async function handleInteractiveSessionAbort(payload) {
+    const { sessionId } = payload;
+    if (sessionId) {
+        await purgeSession(sessionId);
+    }
+    return { success: true, aborted: true };
+}

package/src/handlers/previewHandler.js

@@ -111,14 +111,66 @@ export async function handlePreviewPage(payload) {
  * Handles INSPECT_ELEMENT task: resolves DOM element coordinates or evaluates candidate selectors on the edge worker.
  */
 export async function handleInspectElement(payload) {
-    const { url, selector, strategyType, strategies, fingerprint, x, y, timeout = 20000 } = payload;
+    const { url, preScrapeActions, authentication, selector, strategyType, strategies, fingerprint, x, y, timeout = 20000 } = payload;
     const browser = await localBrowserManager.getBrowser();
     const page = await browser.newPage();
 
     try {
         await page.setViewport({ width: 1366, height: 900, deviceScaleFactor: 1 });
+
+        // Apply authentication if provided
+        if (authentication) {
+            if (authentication.type === "COOKIES" && Array.isArray(authentication.cookies)) {
+                const parsedUrl = new URL(url);
+                await page.setCookie(...authentication.cookies.map(c => ({
+                    name: c.name,
+                    value: c.value,
+                    domain: c.domain || parsedUrl.hostname,
+                    path: c.path || "/",
+                }))).catch(() => {});
+            }
+            if (authentication.type === "HEADERS" && authentication.headers) {
+                await page.setExtraHTTPHeaders(authentication.headers).catch(() => {});
+            }
+        }
+
         await page.goto(url, { waitUntil: "domcontentloaded", timeout });
-        await new Promise((r) => setTimeout(r, 1000));
+        try {
+            await page.waitForNetworkIdle({ idleTime: 500, timeout: 3500 }).catch(() => {});
+        } catch (_) {}
+        await page.evaluate(() => document.fonts?.ready).catch(() => {});
+        await new Promise((r) => setTimeout(r, 800));
+
+        // Execute pre-scrape actions if present
+        if (Array.isArray(preScrapeActions) && preScrapeActions.length > 0) {
+            for (const action of preScrapeActions) {
+                try {
+                    if (action.actionType === "CLICK" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: 4000 });
+                        await page.click(action.selector);
+                    } else if (action.actionType === "TYPE" && action.selector && action.value) {
+                        await page.waitForSelector(action.selector, { timeout: 4000 });
+                        await page.type(action.selector, action.value, { delay: 30 });
+                    } else if (action.actionType === "SCROLL") {
+                        const scrollPixels = parseInt(action.value, 10) || 500;
+                        await page.evaluate((px) => window.scrollBy(0, px), scrollPixels);
+                    } else if (action.actionType === "WAIT_FOR" && action.selector) {
+                        await page.waitForSelector(action.selector, { timeout: 8000 });
+                    } else if (action.actionType === "SELECT_OPTION" && action.selector && action.value) {
+                        await page.waitForSelector(action.selector, { timeout: 4000 });
+                        await page.select(action.selector, action.value);
+                    } else if (action.actionType === "PRESS_KEY" && action.value) {
+                        await page.keyboard.press(action.value);
+                    }
+                    if (action.delayMs && action.delayMs > 0) {
+                        await new Promise((r) => setTimeout(r, Math.min(action.delayMs, 5000)));
+                    }
+                } catch (actErr) {
+                    console.warn(`[WorkerInspect] Pre-scrape action ${action.actionType} (${action.selector}) skipped: ${actErr.message}`);
+                }
+            }
+            await new Promise((r) => setTimeout(r, 600));
+        }
 
         if (x !== undefined && y !== undefined) {
             const elementInfo = await page.evaluate((px, py) => {
@@ -129,8 +181,168 @@ export async function handleInspectElement(payload) {
                 const clientX = px - window.scrollX;
                 const clientY = py - window.scrollY;
 
-                const el = document.elementFromPoint(clientX, clientY);
-                if (!el) return null;
+                // ─── Step 1: Collect candidates using elementsFromPoint + surrounding offsets ───
+                const candidateNodes = new Set();
+                const sampleOffsets = [
+                    [0, 0],
+                    [-4, 0], [4, 0], [0, -4], [0, 4],
+                    [-8, 0], [8, 0], [0, -8], [0, 8],
+                ];
+
+                for (const [dx, dy] of sampleOffsets) {
+                    const cx = clientX + dx;
+                    const cy = clientY + dy;
+                    if (cx >= 0 && cy >= 0 && cx <= window.innerWidth && cy <= window.innerHeight) {
+                        if (typeof document.elementsFromPoint === "function") {
+                            const list = document.elementsFromPoint(cx, cy) || [];
+                            for (const node of list) {
+                                if (node && node.nodeType === 1) candidateNodes.add(node);
+                            }
+                        }
+                    }
+                }
+
+                if (candidateNodes.size === 0) {
+                    const single = document.elementFromPoint(clientX, clientY);
+                    if (single && single.nodeType === 1) candidateNodes.add(single);
+                }
+
+                const rawElements = Array.from(candidateNodes);
+                if (rawElements.length === 0) return null;
+
+                // ─── Step 2: Intelligent priority scoring ───
+                const scoreElement = (node) => {
+                    if (!node || node === document.body || node === document.documentElement) return -999999;
+                    const tag = node.tagName.toLowerCase();
+                    const cls = (typeof node.className === "string" ? node.className : "").toLowerCase();
+                    const id = (node.id || "").toLowerCase();
+                    const style = window.getComputedStyle ? window.getComputedStyle(node) : null;
+
+                    if (style) {
+                        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") {
+                            return -80000;
+                        }
+                    }
+
+                    const rect = node.getBoundingClientRect();
+                    const area = rect.width * rect.height;
+
+                    // Severe penalty for dimmer, overlay, backdrop, modal blocker containers
+                    const isDimmer =
+                        cls.includes("dimmer") ||
+                        cls.includes("backdrop") ||
+                        cls.includes("overlay") ||
+                        cls.includes("mask") ||
+                        cls.includes("blocker") ||
+                        id.includes("dimmer") ||
+                        id.includes("backdrop") ||
+                        id.includes("overlay");
+
+                    if (isDimmer) {
+                        return -50000;
+                    }
+
+                    // Severe penalty for giant viewport-covering containers
+                    if (rect.width >= window.innerWidth * 0.85 && rect.height >= window.innerHeight * 0.7) {
+                        if (["div", "section", "main", "body", "form"].includes(tag)) {
+                            return -40000;
+                        }
+                    }
+
+                    let score = 0;
+
+                    // Form controls (Inputs, Textareas, Selects) - Top Priority!
+                    if (tag === "input") {
+                        const inputType = (node.type || "text").toLowerCase();
+                        if (inputType === "hidden") return -10000;
+                        if (["submit", "button", "reset"].includes(inputType)) {
+                            score += 18000;
+                        } else {
+                            score += 20000;
+                        }
+                    } else if (tag === "textarea" || tag === "select" || node.getAttribute("contenteditable") === "true") {
+                        score += 20000;
+                    }
+                    // Captchas & Media
+                    else if (tag === "img") {
+                        const src = (node.src || "").toLowerCase();
+                        const alt = (node.getAttribute("alt") || "").toLowerCase();
+                        if (src.includes("captcha") || alt.includes("captcha") || id.includes("captcha") || cls.includes("captcha")) {
+                            score += 22000;
+                        } else {
+                            score += 15000;
+                        }
+                    } else if (tag === "canvas") {
+                        score += 16000;
+                    }
+                    // Interactive Buttons & Links
+                    else if (tag === "button" || node.getAttribute("role") === "button") {
+                        score += 17000;
+                    } else if (tag === "a" && (node.hasAttribute("href") || node.getAttribute("role") === "button")) {
+                        score += 16000;
+                    }
+                    // Labels
+                    else if (tag === "label") {
+                        score += 13000;
+                    }
+                    // Table cells & headers
+                    else if (tag === "td" || tag === "th") {
+                        score += 12000;
+                    }
+                    // Headings
+                    else if (["h1", "h2", "h3", "h4", "h5", "h6"].includes(tag)) {
+                        score += 11000;
+                    }
+                    // Text leaves
+                    else if (["span", "p", "strong", "b", "em", "i", "li", "small"].includes(tag)) {
+                        const txt = (node.innerText || node.textContent || "").trim();
+                        if (txt.length > 0 && node.children.length === 0) {
+                            score += 10000;
+                        } else {
+                            score += 7000;
+                        }
+                    }
+                    // Generic wrappers
+                    else if (["div", "form", "section", "article"].includes(tag)) {
+                        score += 2000;
+                    } else {
+                        score += 1000;
+                    }
+
+                    // Tightly-fitting area preference
+                    if (area > 0) {
+                        score -= Math.min(area / 100, 10000);
+                    }
+
+                    // Exact coordinate hit bonus
+                    if (clientX >= rect.left && clientX <= rect.right && clientY >= rect.top && clientY <= rect.bottom) {
+                        score += 1500;
+                    }
+
+                    return score;
+                };
+
+                rawElements.sort((a, b) => scoreElement(b) - scoreElement(a));
+
+                let el = rawElements[0];
+                if (!el || el === document.body || el === document.documentElement) {
+                    el = rawElements.find(n => n !== document.body && n !== document.documentElement) || document.body;
+                }
+
+                // ─── Step 3: Drill-down inspection ───
+                // If top-scoring element is a container, check if it directly contains an interactive control near click
+                if (el && ["div", "span", "label", "p", "form", "section"].includes(el.tagName.toLowerCase())) {
+                    const innerControls = Array.from(el.querySelectorAll('input:not([type="hidden"]), textarea, select, button, img, canvas'));
+                    for (const ctrl of innerControls) {
+                        const cRect = ctrl.getBoundingClientRect();
+                        const pad = 25;
+                        if (clientX >= cRect.left - pad && clientX <= cRect.right + pad &&
+                            clientY >= cRect.top - pad && clientY <= cRect.bottom + pad) {
+                            el = ctrl;
+                            break;
+                        }
+                    }
+                }
 
                 const rect = el.getBoundingClientRect();
                 const boundingRect = {
@@ -237,6 +449,34 @@ export async function handleInspectElement(payload) {
                     return "/" + parts.join("/");
                 };
 
+                // ─── Collect Alternates for quick switching ───
+                const alternates = [];
+                const seenAltKeys = new Set();
+                for (const cand of rawElements) {
+                    if (cand === el || cand === document.body || cand === document.documentElement) continue;
+                    const cScore = scoreElement(cand);
+                    if (cScore < 0) continue;
+                    const cTag = cand.tagName.toLowerCase();
+                    const cId = cand.id && /^[a-zA-Z][\w-]*$/.test(cand.id) ? `#${cand.id}` : "";
+                    const cCls = (cand.className && typeof cand.className === "string")
+                        ? cand.className.split(/\s+/).filter(c => c && /^[a-zA-Z_-][\w-]*$/.test(c))[0]
+                        : "";
+                    const altKey = `${cTag}${cId}${cCls ? `.${cCls}` : ""}`;
+                    if (seenAltKeys.has(altKey)) continue;
+                    seenAltKeys.add(altKey);
+
+                    const altSel = cId ? cId : (cCls ? `${cTag}.${cCls}` : cTag);
+                    const altTxt = (cand.innerText || cand.textContent || "").trim().slice(0, 35);
+                    alternates.push({
+                        tagName: cTag,
+                        selector: altSel,
+                        id: cand.id || null,
+                        text: altTxt,
+                        label: `<${cTag}${cId || (cCls ? `.${cCls}` : "")}> ${altTxt ? `"${altTxt}"` : ""}`.trim()
+                    });
+                    if (alternates.length >= 4) break;
+                }
+
                 // ─── Build ranked candidates ───
                 const candidates = [];
                 const seen = new Set();
@@ -252,7 +492,64 @@ export async function handleInspectElement(payload) {
                     addCandidate("css", `#${el.id}`, { specificity: "unique", label: "ID Selector" });
                 }
 
-                // 2. data-* and aria-* attributes
+                // 2. Form Name attribute (essential for inputs/forms)
+                const nameAttr = el.getAttribute("name");
+                if (nameAttr && /^[a-zA-Z0-9_\-\[\]:]+$/.test(nameAttr)) {
+                    const selName = `${el.tagName.toLowerCase()}[name="${nameAttr}"]`;
+                    const mc = countMatches(selName);
+                    addCandidate("css", selName, {
+                        specificity: mc === 1 ? "unique" : "high",
+                        label: `Form Name: ${nameAttr}`,
+                        matchCount: mc
+                    });
+                }
+
+                // 3. Form Placeholder attribute
+                const phAttr = el.getAttribute("placeholder");
+                if (phAttr && phAttr.length < 80) {
+                    const selPh = `${el.tagName.toLowerCase()}[placeholder="${phAttr.replace(/"/g, '\\"')}"]`;
+                    const mc = countMatches(selPh);
+                    addCandidate("css", selPh, {
+                        specificity: mc === 1 ? "unique" : "high",
+                        label: `Placeholder: ${phAttr.slice(0, 25)}`,
+                        matchCount: mc
+                    });
+                }
+
+                // 4. Input Type / Role attribute
+                const typeAttr = el.getAttribute("type");
+                if (typeAttr && typeAttr !== "text" && ["input", "button"].includes(el.tagName.toLowerCase())) {
+                    const selType = `${el.tagName.toLowerCase()}[type="${typeAttr}"]`;
+                    const mc = countMatches(selType);
+                    addCandidate("css", selType, {
+                        specificity: mc === 1 ? "unique" : "medium",
+                        label: `Input Type: ${typeAttr}`,
+                        matchCount: mc
+                    });
+                }
+
+                // 5. Image Alt / Captcha attribute
+                if (el.tagName.toLowerCase() === "img") {
+                    const altAttr = el.getAttribute("alt");
+                    if (altAttr && altAttr.length < 60) {
+                        const selAlt = `img[alt="${altAttr.replace(/"/g, '\\"')}"]`;
+                        const mc = countMatches(selAlt);
+                        addCandidate("css", selAlt, {
+                            specificity: mc === 1 ? "unique" : "high",
+                            label: `Image Alt: ${altAttr.slice(0, 25)}`,
+                            matchCount: mc
+                        });
+                    }
+                    const srcAttr = el.getAttribute("src");
+                    if (srcAttr && (srcAttr.toLowerCase().includes("captcha") || srcAttr.toLowerCase().includes("secur"))) {
+                        addCandidate("css", `img[src*="captcha"]`, {
+                            specificity: "high",
+                            label: "Captcha Source Pattern"
+                        });
+                    }
+                }
+
+                // 6. data-* and aria-* attributes
                 for (const attr of el.attributes) {
                     if ((attr.name.startsWith("data-") || attr.name.startsWith("aria-")) && attr.value && attr.value.length < 80) {
                         addCandidate("css", `${el.tagName.toLowerCase()}[${attr.name}="${attr.value}"]`, {
@@ -261,7 +558,7 @@ export async function handleInspectElement(payload) {
                     }
                 }
 
-                // 3. Shortest unique CSS path
+                // 7. Shortest unique CSS path
                 const shortUnique = buildShortUniqueSelector(el);
                 if (shortUnique) {
                     const mc = countMatches(shortUnique);
@@ -272,7 +569,7 @@ export async function handleInspectElement(payload) {
                     });
                 }
 
-                // 4. Class-based selectors (increasing combos until unique)
+                // 8. Class-based selectors (increasing combos until unique)
                 const classes = (el.className && typeof el.className === "string")
                     ? el.className.split(/\s+/).filter(c => c && /^[a-zA-Z_-][\w-]*$/.test(c))
                     : [];
@@ -287,7 +584,7 @@ export async function handleInspectElement(payload) {
                     if (mc === 1) break;
                 }
 
-                // 5. Table-specific selectors
+                // 9. Table-specific selectors
                 const tr = el.closest("tr");
                 if (tr && tr.parentElement) {
                     const rowIdx = Array.from(tr.parentElement.children).indexOf(tr) + 1;
@@ -303,11 +600,11 @@ export async function handleInspectElement(payload) {
                     }
                 }
 
-                // 6. Full structural CSS path
+                // 10. Full structural CSS path
                 const fullCss = buildCssPath(el, 8);
                 addCandidate("css", fullCss, { specificity: "unique", label: "Full CSS Path (Structural)" });
 
-                // 7. XPath — most reliable for scrapers
+                // 11. XPath — most reliable for scrapers
                 const xpath = buildXPath(el);
                 addCandidate("xpath", xpath, { specificity: "high", label: "XPath" });
 
@@ -481,6 +778,7 @@ export async function handleInspectElement(payload) {
                     candidates,
                     hierarchy,
                     boundingRect,
+                    alternates,
                     tableDetection,
                     repeatingDetection,
                 };
@@ -608,9 +906,34 @@ export async function handleInspectElement(payload) {
                         currH = currH.parentElement;
                     }
 
-                    const candidates = [
-                        { type: strategyType, value: matchedSelector, attribute: "text", matchCount: count }
-                    ];
+                    const candidates = [];
+                    const seen = new Set();
+                    const addCandidate = (type, value, extra = {}) => {
+                        if (!value || seen.has(value)) return;
+                        seen.add(value);
+                        const matchCount = type === "css" ? countMatches(value) : null;
+                        candidates.push({ type, value, attribute: "text", matchCount, ...extra });
+                    };
+
+                    addCandidate(strategyType, matchedSelector, { specificity: count === 1 ? "unique" : "medium", label: "Selected Query", matchCount: count });
+
+                    if (el.id && /^[a-zA-Z][\w-]*$/.test(el.id)) {
+                        addCandidate("css", `#${el.id}`, { specificity: "unique", label: "ID Selector" });
+                    }
+                    const nameAttr = el.getAttribute("name");
+                    if (nameAttr && /^[a-zA-Z0-9_\-\[\]:]+$/.test(nameAttr)) {
+                        addCandidate("css", `${el.tagName.toLowerCase()}[name="${nameAttr}"]`, { specificity: "unique", label: `Form Name: ${nameAttr}` });
+                    }
+                    const phAttr = el.getAttribute("placeholder");
+                    if (phAttr && phAttr.length < 80) {
+                        addCandidate("css", `${el.tagName.toLowerCase()}[placeholder="${phAttr.replace(/"/g, '\\"')}"]`, { specificity: "high", label: `Placeholder: ${phAttr.slice(0, 25)}` });
+                    }
+                    if (el.className && typeof el.className === "string") {
+                        const cls = el.className.split(/\s+/).filter(c => c && /^[a-zA-Z_-][\w-]*$/.test(c));
+                        if (cls.length > 0) {
+                            addCandidate("css", `${el.tagName.toLowerCase()}.${cls[0]}`, { specificity: "medium", label: "Class Selector" });
+                        }
+                    }
 
                     return {
                         found: true,