app-manager-edge-worker 1.3.1 → 1.3.3

package/src/handlers/interactiveHandler.js

@@ -87,9 +87,9 @@ async function purgeSession(sessionId) {
 
     try {
         if (session.page && !session.page.isClosed()) {
-            await session.page.close().catch(() => {});
+            await session.page.close().catch(() => { });
         }
-    } catch (_) {}
+    } catch (_) { }
 
     activeSessions.delete(sessionId);
 }
@@ -163,9 +163,9 @@ async function locateElementInPageOrFrames(page, selectorList, timeoutMs = 15000
                 if (fEl) {
                     return { target: frame, element: fEl, matchedSelector: combinedSelector };
                 }
-            } catch (_) {}
+            } catch (_) { }
         }
-    } catch (_) {}
+    } catch (_) { }
 
     return null;
 }
@@ -217,10 +217,10 @@ export async function handleInteractiveSessionInit(payload) {
                             path: c.path || "/",
                         }))
                     )
-                    .catch(() => {});
+                    .catch(() => { });
             }
             if (authentication.type === "HEADERS" && authentication.headers) {
-                await page.setExtraHTTPHeaders(authentication.headers).catch(() => {});
+                await page.setExtraHTTPHeaders(authentication.headers).catch(() => { });
             }
         }
 
@@ -230,8 +230,8 @@ export async function handleInteractiveSessionInit(payload) {
 
         await page.goto(url, { waitUntil: navWaitUntil, timeout: navTimeout });
         try {
-            await page.waitForNetworkIdle({ idleTime: 500, timeout: 4000 }).catch(() => {});
-        } catch (_) {}
+            await page.waitForNetworkIdle({ idleTime: 500, timeout: 4000 }).catch(() => { });
+        } catch (_) { }
 
         // Execute pre-scrape actions if present
         if (Array.isArray(preScrapeActions) && preScrapeActions.length > 0) {
@@ -280,8 +280,8 @@ export async function handleInteractiveSessionInit(payload) {
                 const { target, element, matchedSelector } = located;
 
                 if (input.clearFirst !== false) {
-                    await element.click({ clickCount: 3 }).catch(() => {});
-                    await page.keyboard.press("Backspace").catch(() => {});
+                    await element.click({ clickCount: 3 }).catch(() => { });
+                    await page.keyboard.press("Backspace").catch(() => { });
                 }
 
                 if (input.actionType === "SELECT") {
@@ -290,36 +290,36 @@ export async function handleInteractiveSessionInit(payload) {
                     await element.type(String(input.value), { delay: input.delayMs || 30 });
                 }
 
-                // Explicitly dispatch input, change, keydown, keyup, and blur events, plus sync AngularJS ngModel if present
-                await target.evaluate((sel) => {
-                    const el = document.querySelector(sel);
-                    if (el) {
-                        el.dispatchEvent(new Event("input", { bubbles: true }));
-                        el.dispatchEvent(new Event("change", { bubbles: true }));
-                        el.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "Enter" }));
-                        el.dispatchEvent(new KeyboardEvent("keyup", { bubbles: true, key: "Enter" }));
-                        el.dispatchEvent(new Event("blur", { bubbles: true }));
-
-                        // AngularJS scope & ngModel synchronization
-                        if (window.angular) {
-                            try {
-                                const ngEl = window.angular.element(el);
-                                const ngModel = ngEl.controller("ngModel");
-                                if (ngModel) {
-                                    ngModel.$setViewValue(el.value);
-                                    ngModel.$render();
-                                    ngModel.$commitViewValue();
-                                }
-                                const scope = ngEl.scope();
-                                if (scope && !scope.$$phase) {
-                                    scope.$apply();
-                                }
-                            } catch (_) {}
+                    // Explicitly dispatch input, change, keydown, keyup, and blur events, plus sync AngularJS ngModel if present
+                    await target.evaluate((sel) => {
+                        const el = document.querySelector(sel);
+                        if (el) {
+                            el.dispatchEvent(new Event("input", { bubbles: true }));
+                            el.dispatchEvent(new Event("change", { bubbles: true }));
+                            el.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "Enter" }));
+                            el.dispatchEvent(new KeyboardEvent("keyup", { bubbles: true, key: "Enter" }));
+                            el.dispatchEvent(new Event("blur", { bubbles: true }));
+
+                            // AngularJS scope & ngModel synchronization
+                            if (window.angular) {
+                                try {
+                                    const ngEl = window.angular.element(el);
+                                    const ngModel = ngEl.controller("ngModel");
+                                    if (ngModel) {
+                                        ngModel.$setViewValue(el.value);
+                                        ngModel.$render();
+                                        ngModel.$commitViewValue();
+                                    }
+                                    const scope = ngEl.scope();
+                                    if (scope && !scope.$$phase) {
+                                        scope.$apply();
+                                    }
+                                } catch (_) { }
+                            }
                         }
-                    }
-                }, matchedSelector).catch(() => {});
+                }, matchedSelector).catch(() => { });
 
-                await page.keyboard.press("Tab").catch(() => {});
+                await page.keyboard.press("Tab").catch(() => { });
                 await new Promise((r) => setTimeout(r, 300));
             }
         }
@@ -338,632 +338,811 @@ export async function handleInteractiveSessionInit(payload) {
             "#captcha_image",
         ].filter(Boolean);
 
-        const locatedImage = await locateElementInPageOrFrames(page, candidateImageSelectors, imageTimeout);
-        if (!locatedImage || !locatedImage.element) {
-            const currentUrl = page.url();
-            const pageTitle = (await page.title().catch(() => "")) || "Untitled";
-            throw new Error(
-                `Captcha element not found with selector '${captchaConfig.imageSelector || candidateImageSelectors[0]}' on page "${pageTitle}" (${currentUrl}) after ${imageTimeout}ms`
-            );
-        }
+            const locatedImage = await locateElementInPageOrFrames(page, candidateImageSelectors, imageTimeout);
+            if (!locatedImage || !locatedImage.element) {
+                const currentUrl = page.url();
+                const pageTitle = (await page.title().catch(() => "")) || "Untitled";
+                throw new Error(
+                    `Captcha element not found with selector '${captchaConfig.imageSelector || candidateImageSelectors[0]}' on page "${pageTitle}" (${currentUrl}) after ${imageTimeout}ms`
+                );
+            }
 
-        const captchaElement = locatedImage.element;
-
-        // 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");
-
-        // Settle briefly for form state & portal validation UI
-        await new Promise((r) => setTimeout(r, 400));
-
-        // Capture full-page screenshot showing the filled inputs and revealed captcha
-        const pageScreenshotBuffer = await page.screenshot({
-            encoding: "binary",
-            fullPage: false,
-            type: "jpeg",
-            quality: 85,
-        });
-        const pageScreenshotBase64 = `data:image/jpeg;base64,${Buffer.from(pageScreenshotBuffer).toString("base64")}`;
-        const title = (await page.title().catch(() => "")) || "Interactive Portal Session";
-        const dimensions = await page
-            .evaluate(() => ({
-                width: document.documentElement.scrollWidth || window.innerWidth,
-                height: document.documentElement.scrollHeight || window.innerHeight,
-            }))
-            .catch(() => ({ width: 1366, height: 900 }));
-
-        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}`,
-            pageScreenshotBase64,
-            dimensions,
-            title,
-            expiresInSeconds: sessionTtlSeconds,
-        };
-    } catch (err) {
-        await page.close().catch(() => {});
-        throw err;
+            const captchaElement = locatedImage.element;
+
+            // 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");
+
+            // Settle briefly for form state & portal validation UI
+            await new Promise((r) => setTimeout(r, 400));
+
+            // Capture full-page screenshot showing the filled inputs and revealed captcha
+            const pageScreenshotBuffer = await page.screenshot({
+                encoding: "binary",
+                fullPage: false,
+                type: "jpeg",
+                quality: 85,
+            });
+            const pageScreenshotBase64 = `data:image/jpeg;base64,${Buffer.from(pageScreenshotBuffer).toString("base64")}`;
+            const title = (await page.title().catch(() => "")) || "Interactive Portal Session";
+            const dimensions = await page
+                .evaluate(() => ({
+                    width: document.documentElement.scrollWidth || window.innerWidth,
+                    height: document.documentElement.scrollHeight || window.innerHeight,
+                }))
+                .catch(() => ({ width: 1366, height: 900 }));
+
+            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}`,
+                pageScreenshotBase64,
+                dimensions,
+                title,
+                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);
+        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");
-    }
+        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;
-
-    const candidateImageSelectors = [
-        cfg.imageSelector,
-        "#imgCaptcha",
-        "#captchaImg",
-        "img[src*='captcha' i]",
-        "img[id*='captcha' i]",
-    ].filter(Boolean);
-
-    // 1. Snapshot current image hash and src attribute
-    const locatedOldImg = await locateElementInPageOrFrames(page, candidateImageSelectors, 8000);
-    if (!locatedOldImg || !locatedOldImg.element) {
-        throw new Error(`Captcha element not found with selector: ${imageSelector}`);
-    }
-    const oldEl = locatedOldImg.element;
-    const effectiveImageSelector = locatedOldImg.matchedSelector;
-
-    const oldBuffer = await oldEl.screenshot({ encoding: "binary" });
-    const oldHash = crypto.createHash("md5").update(oldBuffer).digest("hex");
-
-    const oldSrc = await locatedOldImg.target.evaluate((sel) => {
-        const el = document.querySelector(sel);
-        return el ? el.getAttribute("src") : null;
-    }, effectiveImageSelector);
-
-    // 2. Click the reload button with robust candidate fallbacks
-    const candidateSelectors = [
-        refreshSelector,
-        "button[ng-click*='refreshCaptcha' i]",
-        "button[ng-click*='captcha' i]",
-        "*[ng-click*='refreshCaptcha' i]",
-        "*[ng-click*='captcha' i]",
-        "#reloadCaptcha",
-        "#refreshCaptcha",
-        "a[title*='refresh' i]",
-        "button[title*='refresh' i]",
-        "a[title*='reload' i]",
-        "button[title*='reload' i]",
-        ".captcha-refresh",
-        ".reload-captcha",
-        ".glyphicon-refresh",
-        "i.fa-refresh",
-        "i.fa-arrows-rotate",
-    ].filter(Boolean);
-
-    let clicked = false;
-    for (const sel of candidateSelectors) {
-        try {
-            const locatedBtn = await locateElementInPageOrFrames(page, [sel], 500);
-            if (locatedBtn && locatedBtn.element) {
-                await locatedBtn.element.click();
-                clicked = true;
-                break;
-            }
-        } catch (_) {}
-    }
+        const { page } = session;
+        const cfg = { ...session.captchaConfig, ...captchaConfig };
+        const imageSelector = cfg.imageSelector || "img[src*='captcha'], #imgCaptcha";
+        const refreshSelector = cfg.refreshSelector;
 
-    if (!clicked) {
-        throw new Error(`Captcha refresh button not found on page (tried: ${refreshSelector || "standard reload selectors"})`);
-    }
+        const candidateImageSelectors = [
+            cfg.imageSelector,
+            "#imgCaptcha",
+            "#captchaImg",
+            "img[src*='captcha' i]",
+            "img[id*='captcha' i]",
+        ].filter(Boolean);
 
-    // 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
+        // 1. Snapshot current image hash and src attribute
+            const locatedOldImg = await locateElementInPageOrFrames(page, candidateImageSelectors, 8000);
+            if (!locatedOldImg || !locatedOldImg.element) {
+                throw new Error(`Captcha element not found with selector: ${imageSelector}`);
             }
-        }
-        retries++;
-    }
+            const oldEl = locatedOldImg.element;
+            const effectiveImageSelector = locatedOldImg.matchedSelector;
 
-    if (!newBuffer) {
-        newBuffer = await oldEl.screenshot({ encoding: "binary" });
-    }
-
-    const imageBase64 = Buffer.from(newBuffer).toString("base64");
+            const oldBuffer = await oldEl.screenshot({ encoding: "binary" });
+            const oldHash = crypto.createHash("md5").update(oldBuffer).digest("hex");
 
-    // Capture updated full page screenshot showing new captcha
-    const pageScreenshotBuffer = await page.screenshot({
-        encoding: "binary",
-        fullPage: false,
-        type: "jpeg",
-        quality: 85,
-    });
-    const pageScreenshotBase64 = `data:image/jpeg;base64,${Buffer.from(pageScreenshotBuffer).toString("base64")}`;
+                const oldSrc = await locatedOldImg.target.evaluate((sel) => {
+                    const el = document.querySelector(sel);
+                    return el ? el.getAttribute("src") : null;
+            }, effectiveImageSelector);
+
+            // 2. Click the reload button with robust candidate fallbacks
+            const candidateSelectors = [
+                refreshSelector,
+                "button[ng-click*='refreshCaptcha' i]",
+                "button[ng-click*='captcha' i]",
+                "*[ng-click*='refreshCaptcha' i]",
+                "*[ng-click*='captcha' i]",
+                "#reloadCaptcha",
+                "#refreshCaptcha",
+                "a[title*='refresh' i]",
+                "button[title*='refresh' i]",
+                "a[title*='reload' i]",
+                "button[title*='reload' i]",
+                ".captcha-refresh",
+                ".reload-captcha",
+                ".glyphicon-refresh",
+                "i.fa-refresh",
+                "i.fa-arrows-rotate",
+            ].filter(Boolean);
+
+            let clicked = false;
+            for (const sel of candidateSelectors) {
+                try {
+                        const locatedBtn = await locateElementInPageOrFrames(page, [sel], 500);
+                        if (locatedBtn && locatedBtn.element) {
+                            await locatedBtn.element.click();
+                            clicked = true;
+                            break;
+                        }
+                    } catch (_) { }
+                }
 
-    return {
-        sessionId,
-        imageBase64: `data:image/png;base64,${imageBase64}`,
-        pageScreenshotBase64,
-    };
-}
+    if (!clicked) {
+                    throw new Error(`Captcha refresh button not found on page (tried: ${refreshSelector || "standard reload selectors"})`);
+                }
 
-/**
- * 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 = [],
-        preservePageForInspection = false,
-    } = payload;
-    const session = activeSessions.get(sessionId);
+                // 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 (!session || !session.page || session.page.isClosed()) {
-        throw new Error("Interactive session not found or already expired");
-    }
+                if (!newBuffer) {
+                    newBuffer = await oldEl.screenshot({ encoding: "binary" });
+                }
 
-    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";
-    
-    // Broad default error selectors covering Indian gov and modern SPA patterns
-    const defaultBroadErrorSelector =
-        "p#alertMsg, #alertMsg, .alertMsg, .alert-danger, .alert-warning, " +
-        ".has-error, .text-danger, #error-msg, .error-message, .err-msg, " +
-        ".ui-messages-error, [class*='error-msg'], [class*='alert-message'], " +
-        ".invalid-feedback, .help-block.error, .form-error, [aria-invalid='true']";
-
-    const customRules = cfg.errorDetection?.rules || [];
-    const ruleSelectors = customRules.map((r) => r.selector).filter(Boolean);
-    const combinedErrorSelectors = [
-        cfg.errorDetection?.selector,
-        ...ruleSelectors,
-        defaultBroadErrorSelector,
-    ]
-        .filter(Boolean)
-        .join(", ");
-
-    const invalidPattern = cfg.errorDetection?.invalidCaptchaPattern || "captcha.*(incorrect|invalid|wrong|mismatch|enter text)";
-
-    // 1. Type captcha solution with robust candidate fallbacks & frame search
-    const solveTimeout = Math.max(cfg.inputTimeoutMs || 0, 15000);
-    const candidateInputSelectors = [
-        inputSelector,
-        "#fo-captcha",
-        "#captcha",
-        "input[name='cap']",
-        "input[name*='captcha' i]",
-        "input[id*='captcha' i]",
-        "input[placeholder*='captcha' i]",
-    ].filter(Boolean);
-
-    const locatedInput = await locateElementInPageOrFrames(page, candidateInputSelectors, solveTimeout);
-    if (!locatedInput || !locatedInput.element) {
-        throw new Error(`Captcha input field not found with selector: ${inputSelector}`);
-    }
+                const imageBase64 = Buffer.from(newBuffer).toString("base64");
+
+                // Capture updated full page screenshot showing new captcha
+                const pageScreenshotBuffer = await page.screenshot({
+                    encoding: "binary",
+                    fullPage: false,
+                    type: "jpeg",
+                    quality: 85,
+                });
+                const pageScreenshotBase64 = `data:image/jpeg;base64,${Buffer.from(pageScreenshotBuffer).toString("base64")}`;
+
+                // Reset auto-purge TTL timer to grant user full window to solve refreshed captcha
+                if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+                const sessionTtlSeconds = cfg.sessionTimeoutSeconds || 180;
+                session.timeoutTimer = setTimeout(() => {
+                    purgeSession(sessionId).catch(() => { });
+                }, sessionTtlSeconds * 1000);
+
+                return {
+                    sessionId,
+                    imageBase64: `data:image/png;base64,${imageBase64}`,
+                    pageScreenshotBase64,
+                };
+            }
 
-    await locatedInput.element.click({ clickCount: 3 }).catch(() => {});
-    await page.keyboard.press("Backspace").catch(() => {});
-    await locatedInput.element.type(String(captchaSolution).trim(), { delay: 35 });
+            /**
+             * 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 = [],
+                    preservePageForInspection = false,
+                } = payload;
+                const session = activeSessions.get(sessionId);
+
+                if (!session || !session.page || session.page.isClosed()) {
+                    throw new Error("Interactive session not found or already expired");
+                }
 
-    // Sync input events and AngularJS ngModel for captcha input
-    await locatedInput.target.evaluate((sel) => {
-        const el = document.querySelector(sel);
-        if (el) {
-            el.dispatchEvent(new Event("input", { bubbles: true }));
-            el.dispatchEvent(new Event("change", { bubbles: true }));
-            el.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "Enter" }));
-            el.dispatchEvent(new KeyboardEvent("keyup", { bubbles: true, key: "Enter" }));
-            el.dispatchEvent(new Event("blur", { bubbles: true }));
+                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";
+
+                // Broad default error selectors covering Indian gov and modern SPA patterns
+                const defaultBroadErrorSelector =
+                    "p#alertMsg, #alertMsg, .alertMsg, .alert-danger, .alert-warning, " +
+                    ".has-error, .text-danger, #error-msg, .error-message, .err-msg, " +
+                    ".ui-messages-error, [class*='error-msg'], [class*='alert-message'], " +
+                    ".invalid-feedback, .help-block.error, .form-error, [aria-invalid='true'], " +
+                    ".err, span.err, p.err, div.err, [class*='err-'], [class*='-error'], " +
+                    "[data-ng-bind*='ERR'], [data-ng-bind*='err'], [data-ng-show*='err'], " +
+                    "[data-ng-show*='w_gst'], [data-ng-if*='captcha'], [data-ng-show*='captcha'], [role='alert'], " +
+                    "[style*='color:red'], [style*='color: red']";
+
+                const customRules = cfg.errorDetection?.rules || [];
+                const ruleSelectors = customRules.map((r) => r.selector).filter(Boolean);
+                const combinedErrorSelectors = [
+                    cfg.errorDetection?.selector,
+                    ...ruleSelectors,
+                    defaultBroadErrorSelector,
+                ]
+                    .filter(Boolean)
+                    .join(", ");
+
+                const defaultCaptchaPattern =
+                    "captcha.*(incorrect|invalid|wrong|mismatch|enter|letters?|text|try again)|" +
+                    "(invalid|incorrect|wrong|mismatch).*captcha|" +
+                    "enter\\s*valid\\s*(letters?|characters?|code)|" +
+                    "letters?\\s*shown\\s*(below|in\\s*the\\s*image)|" +
+                    "characters?\\s*shown|" +
+                    "invalid_captcha|" +
+                    "verification\\s*code.*(invalid|wrong|incorrect)|" +
+                    "security\\s*code.*(invalid|wrong|incorrect)";
+
+                const invalidPattern = cfg.errorDetection?.invalidCaptchaPattern
+                    ? `${cfg.errorDetection.invalidCaptchaPattern}|${defaultCaptchaPattern}`
+                    : defaultCaptchaPattern;
+
+                // 1. Type captcha solution with robust candidate fallbacks & frame search
+                const solveTimeout = Math.max(cfg.inputTimeoutMs || 0, 15000);
+                const candidateInputSelectors = [
+                    inputSelector,
+                    "#fo-captcha",
+                    "#captcha",
+                    "input[name='cap']",
+                    "input[name*='captcha' i]",
+                    "input[id*='captcha' i]",
+                    "input[placeholder*='captcha' i]",
+                ].filter(Boolean);
+
+                const locatedInput = await locateElementInPageOrFrames(page, candidateInputSelectors, solveTimeout);
+                if (!locatedInput || !locatedInput.element) {
+                    throw new Error(`Captcha input field not found with selector: ${inputSelector}`);
+                }
 
-            if (window.angular) {
-                try {
-                    const ngEl = window.angular.element(el);
-                    const ngModel = ngEl.controller("ngModel");
-                    if (ngModel) {
-                        ngModel.$setViewValue(el.value);
-                        ngModel.$render();
-                        ngModel.$commitViewValue();
-                    }
-                    const scope = ngEl.scope();
-                    if (scope && !scope.$$phase) scope.$apply();
-                } catch (_) {}
-            }
-        }
-    }, locatedInput.matchedSelector).catch(() => {});
-
-    // 2. Click submit button with candidate fallbacks & frame search
-    const candidateSubmitSelectors = [
-        submitSelector,
-        "#lotsearch",
-        "button[type='submit']",
-        "input[type='submit']",
-        "button[id*='search' i]",
-        "button[id*='submit' i]",
-        "button.btn-primary",
-    ].filter(Boolean);
-
-    const locatedSubmit = await locateElementInPageOrFrames(page, candidateSubmitSelectors, solveTimeout);
-    if (!locatedSubmit || !locatedSubmit.element) {
-        throw new Error(`Submit button not found with selector: ${submitSelector}`);
-    }
+                await locatedInput.element.click({ clickCount: 3 }).catch(() => { });
+                await page.keyboard.press("Backspace").catch(() => { });
+                await locatedInput.element.type(String(captchaSolution).trim(), { delay: 35 });
 
-    await locatedSubmit.element.click();
+                // Sync input events and AngularJS ngModel for captcha input
+                await locatedInput.target.evaluate((sel) => {
+                    const el = document.querySelector(sel);
+                    if (el) {
+                        el.dispatchEvent(new Event("input", { bubbles: true }));
+                        el.dispatchEvent(new Event("change", { bubbles: true }));
+                        el.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "Enter" }));
+                        el.dispatchEvent(new KeyboardEvent("keyup", { bubbles: true, key: "Enter" }));
+                        el.dispatchEvent(new Event("blur", { bubbles: true }));
 
-    // 3. Post-Submit Race: Wait for Success Selector OR Error Selector
-    // In inspection mode, use a shorter safety window (5-7s) so users aren't stalled waiting on empty selectors
-    const safetyTimeoutMs = preservePageForInspection
-        ? Math.min(cfg.waitForAfterSubmit?.timeoutMs || 8000, 6000)
-        : (cfg.waitForAfterSubmit?.timeoutMs || 15000);
+                        if (window.angular) {
+                            try {
+                                const ngEl = window.angular.element(el);
+                                const ngModel = ngEl.controller("ngModel");
+                                if (ngModel) {
+                                    ngModel.$setViewValue(el.value);
+                                    ngModel.$render();
+                                    ngModel.$commitViewValue();
+                                }
+                                const scope = ngEl.scope();
+                                if (scope && !scope.$$phase) scope.$apply();
+                            } catch (_) { }
+                        }
+                    }
+                }, locatedInput.matchedSelector).catch(() => { });
+
+                // 2. Click submit button with candidate fallbacks & frame search
+                const candidateSubmitSelectors = [
+                    submitSelector,
+                    "#lotsearch",
+                    "button[type='submit']",
+                    "input[type='submit']",
+                    "button[id*='search' i]",
+                    "button[id*='submit' i]",
+                    "button.btn-primary",
+                ].filter(Boolean);
+
+                const locatedSubmit = await locateElementInPageOrFrames(page, candidateSubmitSelectors, solveTimeout);
+                if (!locatedSubmit || !locatedSubmit.element) {
+                    throw new Error(`Submit button not found with selector: ${submitSelector}`);
+                }
 
-    const matchedOutcome = await page
-        .waitForFunction(
-            (succ, err) => {
-                if (document.querySelector(succ)) return "SUCCESS";
-                try {
-                    const elements = document.querySelectorAll(err);
-                    for (const el of elements) {
-                        const txt = (el.innerText || el.textContent || "").trim();
-                        if (txt.length > 0) {
-                            const style = window.getComputedStyle(el);
-                            if (style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0") {
-                                return "ERROR";
-                            }
+                await locatedSubmit.element.click().catch(() => { });
+                // Also dispatch native click & submit events to ensure AngularJS/React/SPA form listeners fire
+                await locatedSubmit.target.evaluate((sel) => {
+                    const btn = document.querySelector(sel);
+                    if (btn) {
+                        try { btn.click(); } catch (_) { }
+                        if (btn.form) {
+                            try {
+                                btn.form.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+                            } catch (_) { }
                         }
                     }
-                } catch (e) {}
-                return null;
-            },
-            { timeout: safetyTimeoutMs },
-            successSelector,
-            combinedErrorSelectors
-        )
-        .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;
-            }
+                }, locatedSubmit.matchedSelector).catch(() => { });
+
+                // 3. Post-Submit Race: Wait for Success Selector OR Error Selector
+                // In inspection mode, use a shorter safety window (5-7s) so users aren't stalled waiting on empty selectors
+                const safetyTimeoutMs = preservePageForInspection
+                    ? Math.min(cfg.waitForAfterSubmit?.timeoutMs || 8000, 6000)
+                    : (cfg.waitForAfterSubmit?.timeoutMs || 15000);
+
+                const matchedOutcome = await page
+                    .waitForFunction(
+                        (succ, err) => {
+                            const isVisible = (el) => {
+                                if (!el) return false;
+                                const style = window.getComputedStyle(el);
+                                if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return false;
+                                const rects = el.getClientRects();
+                                if (rects.length === 0) return false;
+                                return rects[0].width > 0 || rects[0].height > 0;
+                            };
+
+                            const isRealError = (txt) => {
+                                if (!txt || txt.length < 3) return false;
+                                const lower = txt.trim().toLowerCase();
+                                if (lower.startsWith("loading") || lower.startsWith("please wait") || lower.startsWith("processing")) {
+                                    return false;
+                                }
+                                return true;
+                            };
 
-            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;
-        }
+                            // 1. Error selectors check (Must run FIRST to prevent false positives from generic table selectors)
+                            try {
+                                const elements = document.querySelectorAll(err);
+                                for (const el of elements) {
+                                    const txt = (el.innerText || el.textContent || "").trim();
+                                    if (isRealError(txt) && isVisible(el)) {
+                                        return "ERROR";
+                                    }
+                                }
+                            } catch (_) { }
 
-        if (preservePageForInspection) {
-            // Keep the page alive for visual inspection & testing
-            if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
-            const inspectTtl = 300; // 5 minutes for interactive element picking
-            session.timeoutTimer = setTimeout(() => {
-                purgeSession(sessionId).catch(() => {});
-            }, inspectTtl * 1000);
+                            // 2. Semantic error text scan across visible leaf elements
+                            try {
+                                const errorRegex = /\b(invalid\s*(gstin|uin|captcha|code|input|format|number|pan)|gstin.*invalid|does\s*not\s*exist|record\s*not\s*found|no\s*records?\s*found|incorrect\s*captcha|wrong\s*captcha|enter\s*valid\s*letters|enter\s*a\s*valid|not\s*registered|mandatory\s*field|action\s*failed)\b/i;
+                                const candidates = document.querySelectorAll("span, p, div, label, font, b, strong");
+                                for (const c of candidates) {
+                                    if (c.children.length === 0 || c.tagName === "P" || c.tagName === "SPAN") {
+                                        const txt = (c.innerText || c.textContent || "").trim();
+                                        if (txt.length >= 5 && txt.length < 250 && errorRegex.test(txt) && isRealError(txt)) {
+                                            if (isVisible(c)) {
+                                                return "ERROR";
+                                            }
+                                        }
+                                    }
+                                }
+                            } catch (_) { }
 
-            // Settle time for tables & styles
-            await new Promise((r) => setTimeout(r, 600));
+                            // 3. Success check: must be genuinely visible and contain substantive data
+                            try {
+                                const successElements = document.querySelectorAll(succ);
+                                for (const el of successElements) {
+                                    if (isVisible(el)) {
+                                        // Ignore empty 1-cell layout tables like captcha wrapper tables
+                                        if (el.tagName === "TABLE" && (el.innerText || "").trim().length < 15) {
+                                            continue;
+                                        }
+                                        return "SUCCESS";
+                                    }
+                                }
+                            } catch (_) { }
 
-            const snap = await captureInspectionSnapshot(page);
-            return {
-                status: "COMPLETED",
-                success: true,
-                data: raw,
-                ...snap,
-                sessionId,
-                isInspectionMode: true,
-            };
-        }
+                            return null;
+                        },
+                        { timeout: safetyTimeoutMs },
+                        successSelector,
+                        combinedErrorSelectors
+                    )
+                    .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;
+                        }
 
-        // Clean up session and close page
-        await purgeSession(sessionId);
+                        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;
+                    }
 
-        return {
-            status: "COMPLETED",
-            success: true,
-            data: raw,
-        };
-    }
+                    if (preservePageForInspection) {
+                        // Keep the page alive for visual inspection & testing
+                        if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+                        const inspectTtl = 300; // 5 minutes for interactive element picking
+                        session.timeoutTimer = setTimeout(() => {
+                            purgeSession(sessionId).catch(() => { });
+                        }, inspectTtl * 1000);
+
+                        // Settle time for tables & styles
+                        await new Promise((r) => setTimeout(r, 600));
+
+                        const snap = await captureInspectionSnapshot(page);
+                        return {
+                            status: "COMPLETED",
+                            success: true,
+                            data: raw,
+                            ...snap,
+                            sessionId,
+                            isInspectionMode: true,
+                        };
+                    }
 
-    // Evaluate error rules and messages if matchedOutcome === "ERROR" or if we are inspecting
-    let matchedRule = null;
-    let errorText = "";
+                    // Clean up session and close page
+                    await purgeSession(sessionId);
 
-    // 1. Check custom configured rules first
-    for (const rule of customRules) {
-        if (!rule.selector) continue;
-        const check = await page.evaluate((sel, pat) => {
-            try {
-                const els = document.querySelectorAll(sel);
-                for (const el of els) {
-                    const txt = (el.innerText || el.textContent || "").trim();
-                    if (txt) {
-                        const style = window.getComputedStyle(el);
-                        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") continue;
-                        if (!pat) return { matched: true, text: txt };
-                        const re = new RegExp(pat, "i");
-                        if (re.test(txt)) return { matched: true, text: txt };
-                    }
+                    return {
+                        status: "COMPLETED",
+                        success: true,
+                        data: raw,
+                    };
                 }
-            } catch (e) {}
-            return null;
-        }, rule.selector, rule.pattern);
-
-        if (check && check.matched) {
-            matchedRule = rule;
-            errorText = check.text;
-            break;
-        }
-    }
 
-    // 2. If no custom rule matched, extract text from combined error selectors
-    if (!matchedRule) {
-        errorText = await page.evaluate((sel) => {
-            try {
-                const els = document.querySelectorAll(sel);
-                for (const el of els) {
-                    const txt = (el.innerText || el.textContent || "").trim();
-                    if (txt) {
+                // Evaluate error rules and messages if matchedOutcome === "ERROR" or if we are inspecting or if timed out
+                let matchedRule = null;
+                let errorText = "";
+
+                const checkRulesAndText = await page.evaluate((rules, errorSelector) => {
+                    const isVisible = (el) => {
+                        if (!el) return false;
                         const style = window.getComputedStyle(el);
-                        if (style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0") {
-                            return txt;
+                        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return false;
+                        const rects = el.getClientRects();
+                        if (rects.length === 0) return false;
+                        return rects[0].width > 0 || rects[0].height > 0;
+                    };
+
+                    const isRealError = (txt) => {
+                        if (!txt || txt.length < 3) return false;
+                        const lower = txt.trim().toLowerCase();
+                        if (lower.startsWith("loading") || lower.startsWith("please wait") || lower.startsWith("processing")) {
+                            return false;
                         }
+                        return true;
+                    };
+
+                    // 1. Check custom rules with rule.selector
+                    for (const rule of rules) {
+                        if (!rule.selector) continue;
+                        try {
+                            const els = document.querySelectorAll(rule.selector);
+                            for (const el of els) {
+                                const txt = (el.innerText || el.textContent || "").trim();
+                                if (isRealError(txt) && isVisible(el)) {
+                                    if (!rule.pattern) return { matchedRuleId: rule.id, text: txt };
+                                    const re = new RegExp(rule.pattern, "i");
+                                    if (re.test(txt)) return { matchedRuleId: rule.id, text: txt };
+                                }
+                            }
+                        } catch (_) { }
                     }
-                }
-            } catch (e) {}
-            return "";
-        }, combinedErrorSelectors);
-    }
 
-    const regex = new RegExp(invalidPattern, "i");
-    const isCaptchaError = matchedRule
-        ? matchedRule.action === "RETRY_CAPTCHA"
-        : (Boolean(errorText) && regex.test(errorText));
+                    // 2. Extract visible text from combinedErrorSelectors
+                    let foundText = "";
+                    try {
+                        const els = document.querySelectorAll(errorSelector);
+                        for (const el of els) {
+                            const txt = (el.innerText || el.textContent || "").trim();
+                            if (isRealError(txt) && isVisible(el)) {
+                                foundText = txt;
+                                break;
+                            }
+                        }
+                    } catch (_) { }
+
+                    // 3. Semantic fallback if foundText is still empty
+                    if (!foundText) {
+                        const errorRegex = /\b(invalid\s*(gstin|uin|captcha|code|input|format|number|pan)|gstin.*invalid|does\s*not\s*exist|record\s*not\s*found|no\s*records?\s*found|incorrect\s*captcha|wrong\s*captcha|enter\s*valid\s*letters|enter\s*a\s*valid|not\s*registered|mandatory\s*field|action\s*failed)\b/i;
+                        const candidates = document.querySelectorAll("span, p, div, label, font, b, strong");
+                        for (const c of candidates) {
+                            if (c.children.length === 0 || c.tagName === "P" || c.tagName === "SPAN") {
+                                const txt = (c.innerText || c.textContent || "").trim();
+                                if (txt.length >= 5 && txt.length < 250 && errorRegex.test(txt) && isRealError(txt)) {
+                                    if (isVisible(c)) {
+                                        foundText = txt;
+                                        break;
+                                    }
+                                }
+                            }
+                        }
+                    }
 
-    // Check if new captcha image was rendered on page
-    const imageSelector = cfg.imageSelector || "img[src*='captcha'], #imgCaptcha";
-    let newImageBase64 = null;
-    try {
-        const newCaptchaEl = await page.$(imageSelector);
-        if (newCaptchaEl) {
-            const newBuffer = await newCaptchaEl.screenshot({ encoding: "binary", type: "png" });
-            newImageBase64 = `data:image/png;base64,${Buffer.from(newBuffer).toString("base64")}`;
-        }
-    } catch (e) {}
-
-    // CRITICAL FOR INSPECTOR: In inspection mode, NEVER purge the session on errors or timeout!
-    // Always snap the live DOM and return it so the user can inspect the red text and configure selectors
-    if (preservePageForInspection) {
-        if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
-        const inspectTtl = 300;
-        session.timeoutTimer = setTimeout(() => {
-            purgeSession(sessionId).catch(() => {});
-        }, inspectTtl * 1000);
-
-        const snap = await captureInspectionSnapshot(page);
-        const effectiveStatus = isCaptchaError
-            ? "INVALID_CAPTCHA"
-            : (errorText ? "BUSINESS_ERROR" : "INSPECTION_MODE");
-
-        return {
-            status: effectiveStatus,
-            success: true, // Allows frontend to render the inspection screenshot
-            errorCode: (matchedRule && matchedRule.id) || (isCaptchaError ? "INVALID_CAPTCHA" : (errorText ? "BUSINESS_ERROR" : "INSPECTION_MODE")),
-            message: (matchedRule && matchedRule.customMessage) || errorText || (matchedOutcome === "TIMEOUT" ? "Page updated (no success table found). You can now inspect elements or error messages." : "Page outcome revealed for inspection."),
-            newImageBase64,
-            matchedRule: matchedRule ? { id: matchedRule.id, name: matchedRule.name, action: matchedRule.action } : null,
-            sessionId,
-            isInspectionMode: true,
-            ...snap,
-        };
-    }
+                    // 4. If we found text, check if any custom rule matches this text by pattern (even if rule.selector didn't match!)
+                    let fallbackRuleId = null;
+                    if (foundText) {
+                        for (const rule of rules) {
+                            if (rule.pattern) {
+                                try {
+                                    const re = new RegExp(rule.pattern, "i");
+                                    if (re.test(foundText)) {
+                                        fallbackRuleId = rule.id;
+                                        break;
+                                    }
+                                } catch (_) { }
+                            }
+                        }
+                    }
 
-    // Runtime non-inspection mode:
-    if (isCaptchaError) {
-        if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
-        const retryTtlSeconds = cfg.sessionTimeoutSeconds || 90;
-        session.timeoutTimer = setTimeout(() => {
-            purgeSession(sessionId).catch(() => {});
-        }, retryTtlSeconds * 1000);
-
-        return {
-            status: "INVALID_CAPTCHA",
-            success: false,
-            message: (matchedRule && matchedRule.customMessage) || errorText || "The captcha entered was incorrect.",
-            canRetry: true,
-            newImageBase64,
-            errorCode: (matchedRule && matchedRule.id) || "INVALID_CAPTCHA",
-        };
-    }
+                    // 5. DOM-level captcha error detection: check if captcha input or form has invalid captcha state
+                    let hasDomCaptchaError = false;
+                    try {
+                        const capInput = document.querySelector("input[name='cap'], input[id*='captcha' i], input[name*='captcha' i], #fo-captcha");
+                        if (capInput) {
+                            const cls = capInput.className || "";
+                            if (cls.includes("invalid_captcha") || cls.includes("invalid-captcha") || cls.includes("ng-invalid-invalid_captcha")) {
+                                hasDomCaptchaError = true;
+                            }
+                        }
+                        const form = document.querySelector("form");
+                        if (form && !hasDomCaptchaError) {
+                            const formCls = form.className || "";
+                            if (formCls.includes("invalid_captcha") || formCls.includes("invalid-captcha") || formCls.includes("ng-invalid-invalid_captcha")) {
+                                hasDomCaptchaError = true;
+                            }
+                        }
+                        if (!hasDomCaptchaError) {
+                            const capErrSpan = document.querySelector("[data-ng-bind*='ERR_CAPTCHA'], [ng-bind*='ERR_CAPTCHA'], [data-ng-if*='invalid_captcha'], [ng-if*='invalid_captcha']");
+                            if (capErrSpan) {
+                                const s = window.getComputedStyle(capErrSpan);
+                                if (s.display !== "none" && s.visibility !== "hidden") {
+                                    hasDomCaptchaError = true;
+                                }
+                            }
+                        }
+                    } catch (_) { }
 
-    if (errorText || matchedRule) {
-        await purgeSession(sessionId);
-        return {
-            status: "BUSINESS_ERROR",
-            success: false,
-            errorCode: (matchedRule && matchedRule.id) || "BUSINESS_ERROR",
-            message: (matchedRule && matchedRule.customMessage) || errorText || "Target portal returned an error.",
-            canRetry: false,
-        };
-    }
+                    return {
+                        matchedRuleId: fallbackRuleId,
+                        text: foundText,
+                        hasDomCaptchaError,
+                    };
+                }, customRules, combinedErrorSelectors);
 
-    // Runtime Timeout
-    await purgeSession(sessionId);
-    return {
-        status: "TIMEOUT",
-        success: false,
-        message: "Target portal did not respond with results within the expected time window.",
-        canRetry: false,
-    };
-}
+                if (checkRulesAndText && checkRulesAndText.matchedRuleId) {
+                    matchedRule = customRules.find((r) => r.id === checkRulesAndText.matchedRuleId) || null;
+                }
+                errorText = (checkRulesAndText && checkRulesAndText.text) || "";
+
+                const regex = new RegExp(invalidPattern, "i");
+                const isCaptchaError =
+                    Boolean(checkRulesAndText?.hasDomCaptchaError) ||
+                    (matchedRule ? matchedRule.action === "RETRY_CAPTCHA" : false) ||
+                    (Boolean(errorText) && regex.test(errorText));
+
+                // If captcha error occurred, give target portal a brief window to load the refreshed captcha image
+                const imageSelector = cfg.imageSelector || "img[src*='captcha'], #imgCaptcha";
+                let newImageBase64 = null;
+                if (isCaptchaError) {
+                    try {
+                        const initialSrc = await page.$eval(imageSelector, (el) => el.src || el.getAttribute("src")).catch(() => null);
+                        await Promise.race([
+                            page.waitForFunction(
+                                (sel, old) => {
+                                    const el = document.querySelector(sel);
+                                    return el && (el.src || el.getAttribute("src")) !== old && el.complete;
+                                },
+                                { timeout: 1600 },
+                                imageSelector,
+                                initialSrc
+                            ).catch(() => { }),
+                            new Promise((r) => setTimeout(r, 650)),
+                        ]);
+                    } catch (_) { }
+                }
 
-/**
- * Capture full inspection snapshot helper
- */
-async function captureInspectionSnapshot(page) {
-    await new Promise((r) => setTimeout(r, 500));
-    const screenshotBuffer = await page.screenshot({
-        encoding: "binary",
-        fullPage: false,
-        type: "jpeg",
-        quality: 85,
-    });
-    const screenshotBase64 = `data:image/jpeg;base64,${Buffer.from(screenshotBuffer).toString("base64")}`;
-    const title = await page.title().catch(() => "");
-    const dimensions = await page
-        .evaluate(() => ({
-            width: document.documentElement.scrollWidth || window.innerWidth,
-            height: document.documentElement.scrollHeight || window.innerHeight,
-        }))
-        .catch(() => ({ width: 1366, height: 900 }));
-
-    return {
-        screenshotBase64,
-        dimensions,
-        title: title || "Inspection Page",
-    };
-}
+                try {
+                    const newCaptchaEl = await page.$(imageSelector);
+                    if (newCaptchaEl) {
+                        const newBuffer = await newCaptchaEl.screenshot({ encoding: "binary", type: "png" });
+                        newImageBase64 = `data:image/png;base64,${Buffer.from(newBuffer).toString("base64")}`;
+                    }
+                } catch (e) { }
+
+                // CRITICAL FOR INSPECTOR: In inspection mode, NEVER purge the session on errors or timeout!
+                // Always snap the live DOM and return it so the user can inspect the red text and configure selectors
+                if (preservePageForInspection) {
+                    if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+                    const inspectTtl = 300;
+                    session.timeoutTimer = setTimeout(() => {
+                        purgeSession(sessionId).catch(() => { });
+                    }, inspectTtl * 1000);
+
+                    const snap = await captureInspectionSnapshot(page);
+                    const effectiveStatus = isCaptchaError
+                        ? "INVALID_CAPTCHA"
+                        : (errorText ? "BUSINESS_ERROR" : "INSPECTION_MODE");
+
+                    return {
+                        status: effectiveStatus,
+                        success: true, // Allows frontend to render the inspection screenshot
+                        errorCode: (matchedRule && matchedRule.id) || (isCaptchaError ? "INVALID_CAPTCHA" : (errorText ? "BUSINESS_ERROR" : "INSPECTION_MODE")),
+                        message: (matchedRule && matchedRule.customMessage) || errorText || (matchedOutcome === "TIMEOUT" ? "Page updated (no success table found). You can now inspect elements or error messages." : "Page outcome revealed for inspection."),
+                        newImageBase64,
+                        matchedRule: matchedRule ? { id: matchedRule.id, name: matchedRule.name, action: matchedRule.action } : null,
+                        sessionId,
+                        isInspectionMode: true,
+                        ...snap,
+                    };
+                }
 
-/**
- * Force capture snapshot of the active interactive session's page
- */
-export async function handleInteractiveSessionSnapshot(payload) {
-    const { sessionId } = payload;
-    const session = activeSessions.get(sessionId);
+                // Runtime non-inspection mode:
+                if (isCaptchaError) {
+                    // For captcha errors: NEVER abort session! Keep the browser session alive and reset TTL timer
+                    if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+                    const retryTtlSeconds = cfg.sessionTimeoutSeconds || 180;
+                    session.timeoutTimer = setTimeout(() => {
+                        purgeSession(sessionId).catch(() => { });
+                    }, retryTtlSeconds * 1000);
+
+                    return {
+                        status: "INVALID_CAPTCHA",
+                        success: false,
+                        message: (matchedRule && matchedRule.customMessage) || errorText || "The captcha entered was incorrect. Please retry with the updated image.",
+                        canRetry: true,
+                        newImageBase64,
+                        errorCode: (matchedRule && matchedRule.id) || "INVALID_CAPTCHA",
+                        matchedRule: matchedRule ? { id: matchedRule.id, name: matchedRule.name, action: matchedRule.action } : null,
+                    };
+                }
 
-    if (!session || !session.page || session.page.isClosed()) {
-        throw new Error("Interactive session not found or already expired");
-    }
+                if (errorText || matchedRule) {
+                    // For business errors (e.g. invalid GSTIN, not found): abort and purge session immediately
+                    await purgeSession(sessionId);
+                    return {
+                        status: "BUSINESS_ERROR",
+                        success: false,
+                        errorCode: (matchedRule && matchedRule.id) || "BUSINESS_ERROR",
+                        message: (matchedRule && matchedRule.customMessage) || errorText || "Target portal returned an error.",
+                        canRetry: false,
+                        matchedRule: matchedRule ? { id: matchedRule.id, name: matchedRule.name, action: matchedRule.action } : null,
+                    };
+                }
 
-    const { page } = session;
-    if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
-    session.timeoutTimer = setTimeout(() => {
-        purgeSession(sessionId).catch(() => {});
-    }, 300 * 1000);
+                // Runtime Timeout
+                await purgeSession(sessionId);
+                return {
+                    status: "TIMEOUT",
+                    success: false,
+                    message: "Target portal did not respond with results within the expected time window.",
+                    canRetry: false,
+                };
+            }
 
-    const snap = await captureInspectionSnapshot(page);
-    return {
-        success: true,
-        sessionId,
-        ...snap,
-    };
-}
+            /**
+             * Capture full inspection snapshot helper
+             */
+            async function captureInspectionSnapshot(page) {
+                await new Promise((r) => setTimeout(r, 500));
+                const screenshotBuffer = await page.screenshot({
+                    encoding: "binary",
+                    fullPage: false,
+                    type: "jpeg",
+                    quality: 85,
+                });
+                const screenshotBase64 = `data:image/jpeg;base64,${Buffer.from(screenshotBuffer).toString("base64")}`;
+                const title = await page.title().catch(() => "");
+                const dimensions = await page
+                    .evaluate(() => ({
+                        width: document.documentElement.scrollWidth || window.innerWidth,
+                        height: document.documentElement.scrollHeight || window.innerHeight,
+                    }))
+                    .catch(() => ({ width: 1366, height: 900 }));
+
+                return {
+                    screenshotBase64,
+                    dimensions,
+                    title: title || "Inspection Page",
+                };
+            }
 
-/**
- * 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 };
-}
+            /**
+             * Force capture snapshot of the active interactive session's page
+             */
+            export async function handleInteractiveSessionSnapshot(payload) {
+                const { sessionId } = payload;
+                const session = activeSessions.get(sessionId);
 
-/**
- * 5. Handles HITL_SESSION_EXTRACT:
- *    Extracts fields directly from an active interactive session's live page.
- */
-export async function handleInteractiveSessionExtract(payload) {
-    const { sessionId, 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");
+                }
 
-    if (!session || !session.page || session.page.isClosed()) {
-        throw new Error("Interactive session not found or already expired");
-    }
+                const { page } = session;
+                if (session.timeoutTimer) clearTimeout(session.timeoutTimer);
+                session.timeoutTimer = setTimeout(() => {
+                    purgeSession(sessionId).catch(() => { });
+                }, 300 * 1000);
+
+                const snap = await captureInspectionSnapshot(page);
+                return {
+                    success: true,
+                    sessionId,
+                    ...snap,
+                };
+            }
 
-    const { page } = session;
-    const raw = {};
+            /**
+             * 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 };
+            }
 
-    for (const mapping of fieldMappings) {
-        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;
-        }
+            /**
+             * 5. Handles HITL_SESSION_EXTRACT:
+             *    Extracts fields directly from an active interactive session's live page.
+             */
+            export async function handleInteractiveSessionExtract(payload) {
+                const { sessionId, fieldMappings = [], collections = [] } = payload;
+                const session = activeSessions.get(sessionId);
 
-        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;
-    }
+                if (!session || !session.page || session.page.isClosed()) {
+                    throw new Error("Interactive session not found or already expired");
+                }
 
-    return {
-        success: true,
-        data: raw,
-    };
-}
+                const { page } = session;
+                const raw = {};
+
+                for (const mapping of fieldMappings) {
+                    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;
+                }
+
+                return {
+                    success: true,
+                    data: raw,
+                };
+            }