app-manager-edge-worker 1.2.0 → 1.2.1

package/README.md

@@ -203,6 +203,15 @@ 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "app-manager-edge-worker",
-  "version": "1.2.0",
+  "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.2.0";
+let workerVersion = "1.2.1";
 try {
     const pkg = require("../package.json");
     if (pkg?.version) workerVersion = pkg.version;

package/src/client.js

@@ -18,7 +18,7 @@ import fs from "fs";
 import { getWhatsAppHandler } from "./handlers/whatsappHandler.js";
 import { printBanner, logInfo, logSuccess, logWarn, logError, logJob } from "./banner.js";
 
-let workerPkgVersion = "1.2.0";
+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;

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,