explorbot 0.1.32-beta.1 → 0.2.1

package/dist/src/explorer.js

@@ -8,68 +8,195 @@ import { createTest } from 'codeceptjs/lib/mocha/test';
 import dedent from 'dedent';
 import { ActionResult } from "./action-result.js";
 import Action from './action.js';
-import { visuallyAnnotateContainers } from "./ai/researcher/coordinates.js";
-import { RequestStore } from "./api/request-store.js";
 import { XhrCapture } from "./api/xhr-capture.js";
 import { ConfigParser } from './config.js';
-import { KnowledgeTracker } from './knowledge-tracker.js';
-import { PlaywrightRecorder } from "./playwright-recorder.js";
-import { Reporter } from "./reporter.js";
-import { StateManager } from './state-manager.js';
 import { TestResult } from "./test-plan.js";
-import { BrowserRecoveryError, isFatalBrowserError, isNavigationTransitionError } from "./utils/browser-errors.js";
-import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from "./utils/html.js";
+import { BrowserRecoveryError, browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from "./utils/browser-errors.js";
 import { createDebug, log, tag } from './utils/logger.js';
-import { waitForPageReadiness } from "./utils/page-readiness.js";
-import { WebElement } from "./utils/web-element.js";
+import { sleep, waitForPageReadiness } from "./utils/page-readiness.js";
 const debugLog = createDebug('explorbot:explorer');
 const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
+const RECOVERY_NAVIGATION = { waitUntil: 'domcontentloaded', timeout: 10000 };
 class Explorer {
-    aiProvider;
-    playwrightHelper;
-    isStarted = false;
-    isSharedBrowser = false;
-    actor;
-    stateManager;
-    knowledgeTracker;
     config;
-    userResolveFn = null;
     options;
+    stateManager;
+    knowledgeTracker;
     reporter;
-    otherTabs = [];
-    _activeTest = null;
+    requestStore;
+    playwrightRecorder;
+    playwrightHelper;
+    _actor;
+    started = false;
+    isSharedBrowser = false;
     xhrCapture = null;
-    requestStore = null;
-    playwrightRecorder = new PlaywrightRecorder();
+    _activeTest = null;
     observedTestPages = new Set();
     testPageErrorHandler = null;
     testConsoleHandler = null;
     testDialogHandler = null;
-    constructor(config, aiProvider, options) {
+    constructor(config, options, deps) {
         this.config = config;
-        this.aiProvider = aiProvider;
         this.options = options;
+        this.stateManager = deps.stateManager;
+        this.knowledgeTracker = deps.knowledgeTracker;
+        this.reporter = deps.reporter;
+        this.requestStore = deps.requestStore;
+        this.playwrightRecorder = deps.playwrightRecorder;
         this.initializeContainer();
-        this.stateManager = new StateManager({ incognito: this.options?.incognito });
-        this.knowledgeTracker = new KnowledgeTracker();
-        this.reporter = new Reporter(config.reporter, this.stateManager);
     }
-    initializeContainer() {
-        try {
-            // Use project root for output directory, not current working directory
-            const configParser = ConfigParser.getInstance();
-            const configPath = configParser.getConfigPath();
-            const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
-            global.output_dir = path.join(projectRoot, 'output', 'states');
-            global.codecept_dir = projectRoot;
-            configParser.validateConfig(this.config);
-            const codeceptConfig = this.convertToCodeceptConfig(this.config);
-            codeceptjs.container.create(codeceptConfig, {});
+    get actor() {
+        return this._actor;
+    }
+    get page() {
+        const page = this.playwrightHelper?.page;
+        if (!page || page.isClosed?.())
+            return null;
+        return page;
+    }
+    get activeTest() {
+        return this._activeTest;
+    }
+    async start() {
+        if (this.started)
+            return;
+        await codeceptjs.recorder.start();
+        await codeceptjs.container.started(null);
+        storeListener();
+        stepsListener();
+        codeceptjs.recorder.retry({
+            retries: this.config.action?.retries || 3,
+            when: (err) => !!err?.message?.includes?.('context'),
+        });
+        this.playwrightHelper = codeceptjs.container.helpers('Playwright');
+        if (!this.playwrightHelper) {
+            throw new Error('Playwright helper not available');
         }
-        catch (error) {
-            log(`❌ Failed to initialize container: ${error}`);
-            throw error;
+        await this.connectOrLaunchBrowser();
+        const hasSession = this.options?.session && existsSync(this.options.session);
+        await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+        await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
+        this.attachXhrCapture();
+        if (hasSession) {
+            tag('info').log(`Session restored from ${path.relative(process.cwd(), this.options.session)}`);
+        }
+        this._actor = codeceptjs.container.support('I');
+        this.started = true;
+        this.listenToStateChanged();
+        codeceptjs.event.dispatcher.emit('global.before');
+        tag('success').log('Browser started, ready to explore');
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        await this.stopCaptures();
+        if (this.options?.session && this.playwrightHelper?.browserContext) {
+            const dir = path.dirname(this.options.session);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            await this.playwrightHelper.browserContext.storageState({ path: this.options.session });
+            debugLog(`Session saved to ${path.relative(process.cwd(), this.options.session)}`);
+        }
+        codeceptjs.event.dispatcher.emit('global.after');
+        codeceptjs.event.dispatcher.emit('global.result');
+        if (!this.isSharedBrowser) {
+            await Promise.all([this.reporter.finishRun(), this.playwrightHelper._stopBrowser(), codeceptjs.recorder.stop()]);
+            return;
+        }
+        tag('info').log('Closing browser context (persistent browser stays running)');
+        await this.closeBrowserContext();
+        this.playwrightHelper.browser = null;
+        this.playwrightHelper.isRunning = false;
+        await Promise.all([this.reporter.finishRun(), codeceptjs.recorder.stop()]);
+    }
+    action() {
+        return new Action(this._actor, this.stateManager, this.playwrightRecorder, (fn) => this.runWithRecovery('action', fn));
+    }
+    async visit(url, opts = {}) {
+        return this.runWithRecovery('visit', async () => {
+            const action = await this.visitOnce(url);
+            if (opts.screenshot)
+                return action.capturePageState({ includeScreenshot: true });
+            return action.getActionResult() ?? action.capturePageState();
+        });
+    }
+    async capture(opts = {}) {
+        return this.action().capturePageState({ includeScreenshot: opts.screenshot });
+    }
+    async withPage(fn) {
+        return this.runWithRecovery('page operation', () => fn(this.playwrightHelper.page));
+    }
+    async recover(error) {
+        if (error)
+            return this.recoverFromExecutionError(error);
+        if (this.page) {
+            this.watchActiveTestPage();
+            return { ok: true, action: 'continue', message: 'Page is available' };
+        }
+        if (!(await this.recoverOrRestart())) {
+            return { ok: false, action: 'stop', message: 'Browser page could not be recovered' };
         }
+        this.watchActiveTestPage();
+        return { ok: true, action: 'continue', recovered: true, message: 'Browser page was recovered' };
+    }
+    async beginTest(test) {
+        if (!this.page && !(await this.recoverOrRestart())) {
+            return { started: false, stop: async () => { } };
+        }
+        this._activeTest = test;
+        test.start();
+        await this.reporter.reportTestStart(test);
+        await this.closeOtherTabs();
+        this.stateManager.otherTabs = [];
+        const codeceptjsTest = toCodeceptjsTest(test);
+        const stepHandler = (step, status, error, log) => {
+            if (!step.toCode)
+                return;
+            if (step?.name?.startsWith('grab'))
+                return;
+            if (step?.name?.startsWith('save'))
+                return;
+            test.addStep(step.toCode(), step.duration, status, error, log);
+            if (!this.stateManager.getCurrentState())
+                return;
+            const lastScreenshot = ActionResult.fromState(this.stateManager.getCurrentState()).screenshotFile;
+            test.setActiveNoteScreenshot(lastScreenshot);
+        };
+        this.watchActiveTestPage();
+        const onStepPassed = (step) => stepHandler(step, 'passed');
+        const onStepFailed = (step, error) => {
+            stepHandler(step, 'failed', error?.message || String(error), error?.stack);
+        };
+        const onTestAfter = () => {
+            codeceptjs.event.dispatcher.off('step.passed', onStepPassed);
+            codeceptjs.event.dispatcher.off('step.failed', onStepFailed);
+            codeceptjs.event.dispatcher.off('test.after', onTestAfter);
+            this.unwatchActiveTestPages();
+        };
+        codeceptjs.event.dispatcher.emit('test.before', codeceptjsTest);
+        codeceptjs.event.dispatcher.emit('test.start', codeceptjsTest);
+        codeceptjs.event.dispatcher.on('step.passed', onStepPassed);
+        codeceptjs.event.dispatcher.on('step.failed', onStepFailed);
+        codeceptjs.event.dispatcher.on('test.after', onTestAfter);
+        return { started: true, stop: (meta) => this.finishTest(test, meta) };
+    }
+    async openTab() {
+        const oldPage = this.playwrightHelper?.page;
+        if (!oldPage)
+            return;
+        await this.activateNewPage(oldPage.context());
+        await oldPage.close();
+        this.stateManager.otherTabs = [];
+        debugLog('Opened fresh tab, closed previous tab');
+    }
+    initializeContainer() {
+        const configParser = ConfigParser.getInstance();
+        const projectRoot = configParser.getProjectRoot();
+        global.output_dir = configParser.getStatesDir();
+        global.codecept_dir = projectRoot;
+        configParser.validateConfig(this.config);
+        codeceptjs.container.create(this.convertToCodeceptConfig(this.config), {});
     }
     convertToCodeceptConfig(config) {
         const playwrightConfig = { ...config.playwright };
@@ -113,105 +240,11 @@ class Explorer {
             },
         };
         if (this.config.stepsFile) {
-            const configPath = ConfigParser.getInstance().getConfigPath();
-            const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
+            const projectRoot = ConfigParser.getInstance().getProjectRoot();
             codeceptConfig.include = { I: path.resolve(projectRoot, this.config.stepsFile) };
         }
         return codeceptConfig;
     }
-    getConfig() {
-        if (!this.config) {
-            throw new Error('Configuration not loaded. Call run() first.');
-        }
-        return this.config;
-    }
-    getConfigPath() {
-        const configParser = ConfigParser.getInstance();
-        return configParser.getConfigPath();
-    }
-    getAIProvider() {
-        return this.aiProvider;
-    }
-    getStateManager() {
-        return this.stateManager;
-    }
-    getCurrentUrl() {
-        return this.stateManager.getCurrentState().url || '?';
-    }
-    getKnowledgeTracker() {
-        return this.knowledgeTracker;
-    }
-    getReporter() {
-        return this.reporter;
-    }
-    getRequestStore() {
-        return this.requestStore;
-    }
-    async extractCookies() {
-        if (!this.playwrightHelper?.browserContext)
-            return {};
-        try {
-            const cookies = await this.playwrightHelper.browserContext.cookies();
-            if (!cookies.length)
-                return {};
-            const cookieString = cookies.map((c) => `${c.name}=${c.value}`).join('; ');
-            return { Cookie: cookieString };
-        }
-        catch {
-            return {};
-        }
-    }
-    setupXhrCapture(reuseRequestStore = false) {
-        const configParser = ConfigParser.getInstance();
-        const outputDir = configParser.getOutputDir();
-        if (!reuseRequestStore || !this.requestStore) {
-            this.requestStore = new RequestStore(outputDir);
-        }
-        const baseUrl = this.config.playwright.url;
-        this.xhrCapture = new XhrCapture(this.requestStore, baseUrl);
-        this.xhrCapture.attach(this.playwrightHelper.page);
-    }
-    async start() {
-        if (this.isStarted) {
-            return;
-        }
-        if (!this.config) {
-            await this.initializeContainer();
-        }
-        await codeceptjs.recorder.start();
-        await codeceptjs.container.started(null);
-        storeListener();
-        stepsListener();
-        codeceptjs.recorder.retry({
-            retries: this.config.action?.retries || 3,
-            when: (err) => {
-                if (!err || typeof err.message !== 'string') {
-                    return false;
-                }
-                // ignore context errors
-                return err.message.includes('context');
-            },
-        });
-        this.playwrightHelper = codeceptjs.container.helpers('Playwright');
-        if (!this.playwrightHelper) {
-            throw new Error('Playwright helper not available');
-        }
-        await this.connectOrLaunchBrowser();
-        const hasSession = this.options?.session && existsSync(this.options.session);
-        await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
-        await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
-        this.setupXhrCapture();
-        if (hasSession) {
-            tag('info').log(`Session restored from ${path.relative(process.cwd(), this.options.session)}`);
-        }
-        const I = codeceptjs.container.support('I');
-        this.actor = I;
-        this.isStarted = true;
-        this.listenToStateChanged();
-        codeceptjs.event.dispatcher.emit('global.before');
-        tag('success').log('Browser started, ready to explore');
-        return I;
-    }
     async connectOrLaunchBrowser() {
         const { getAliveEndpoint } = await import('./browser-server.js');
         const endpoint = await getAliveEndpoint();
@@ -240,11 +273,12 @@ class Explorer {
             contextOptions.storageState = this.options.session;
         return contextOptions;
     }
-    createAction() {
-        return new Action(this.actor, this.stateManager, this.playwrightRecorder);
+    attachXhrCapture() {
+        this.xhrCapture = new XhrCapture(this.requestStore, this.config.playwright.url);
+        this.xhrCapture.attach(this.playwrightHelper.page);
     }
-    async runWithBrowserRecovery(label, operation) {
-        if (!(await this.ensurePageAvailable())) {
+    async runWithRecovery(label, operation) {
+        if (!this.page && !(await this.recoverOrRestart())) {
             throw new Error(`Browser page is unavailable before ${label}`);
         }
         try {
@@ -259,18 +293,15 @@ class Explorer {
                     return await operation();
                 }
                 catch (retryError) {
-                    if (!isNavigationTransitionError(retryError) && !this.isFatalBrowserError(retryError))
+                    if (!isNavigationTransitionError(retryError) && !isFatalBrowserError(retryError))
                         throw retryError;
                     recoveryError = retryError;
                 }
             }
-            if (!this.isFatalBrowserError(recoveryError))
+            if (!isFatalBrowserError(recoveryError))
                 throw recoveryError;
             tag('warning').log(`${label}: browser page is unavailable, recovering...`);
-            let recovered = await this.recoverFromBrowserError();
-            if (!recovered)
-                recovered = await this.restartBrowser();
-            if (!recovered)
+            if (!(await this.recoverOrRestart()))
                 throw new BrowserRecoveryError(label, recoveryError, false);
             if (!(await this.waitForPageReadiness()))
                 throw new BrowserRecoveryError(label, recoveryError, true);
@@ -278,38 +309,20 @@ class Explorer {
                 return await operation();
             }
             catch (retryError) {
-                if (this.isFatalBrowserError(retryError)) {
+                if (isFatalBrowserError(retryError)) {
                     throw new BrowserRecoveryError(label, retryError, true);
                 }
                 throw retryError;
             }
         }
     }
-    async capturePageState(opts = {}) {
-        return this.runWithBrowserRecovery('capturePageState', () => this.createAction().capturePageState(opts));
-    }
-    async capturePageWithScreenshot() {
-        return this.capturePageState({ includeScreenshot: true });
-    }
-    async executeAction(code) {
-        return this.runWithBrowserRecovery('executeAction', () => this.createAction().execute(code));
-    }
-    async attemptAction(code, originalMessage, experience = true) {
-        return this.runWithBrowserRecovery('attemptAction', () => this.createAction().attempt(code, originalMessage, experience));
-    }
-    getPlaywrightRecorder() {
-        return this.playwrightRecorder;
-    }
-    async visit(url) {
-        return this.runWithBrowserRecovery('visit', () => this.visitOnce(url));
-    }
     async visitOnce(url) {
         await this.closeOtherTabs();
         const serializedUrl = JSON.stringify(url);
         const currentState = this.stateManager.getCurrentState();
         const actionResult = currentState ? ActionResult.fromState(currentState) : new ActionResult({ url });
         const { statePush = false, wait, waitForElement, code } = this.knowledgeTracker.getStateParameters(actionResult, ['statePush', 'wait', 'waitForElement', 'code']);
-        const action = this.createAction();
+        const action = new Action(this._actor, this.stateManager, this.playwrightRecorder);
         if (statePush) {
             await action.execute(`I.executeScript(() => { window.history.pushState({}, '', ${serializedUrl}); window.dispatchEvent(new PopStateEvent('popstate')); })`);
         }
@@ -318,7 +331,7 @@ class Explorer {
                 await action.execute(`I.amOnPage(${serializedUrl})`);
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
+                const msg = browserErrorMessage(err);
                 if (!RECOVERABLE_NAVIGATION_ERRORS.test(msg))
                     throw err;
                 tag('warning').log(`Navigation warning (continuing after load): ${msg.split('\n')[0]}`);
@@ -339,119 +352,94 @@ class Explorer {
         }
         return action;
     }
-    async annotateElements() {
-        return this.runWithBrowserRecovery('annotateElements', async () => {
-            const { elements } = await annotatePageElements(this.playwrightHelper.page);
-            return elements;
-        });
-    }
-    async visuallyAnnotateElements(opts) {
-        return this.runWithBrowserRecovery('visuallyAnnotateElements', () => visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []));
-    }
-    async getEidxInContainer(containerCss) {
-        const page = this.playwrightHelper.page;
-        try {
-            const selector = containerCss ? `${containerCss} [${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]` : `[${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]`;
-            const elements = await page.locator(selector).all();
-            const result = [];
-            for (const el of elements) {
-                const attr = await el.getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx);
-                if (attr)
-                    result.push(attr);
-            }
-            return result;
-        }
-        catch (error) {
-            if (this.isFatalBrowserError(error)) {
-                tag('warning').log(`getEidxInContainer: ${error instanceof Error ? error.message : error}`);
-                await this.recoverFromBrowserError();
-            }
-            return [];
-        }
-    }
-    async getEidxByLocator(locator, container) {
-        try {
-            const page = this.playwrightHelper.page;
-            const base = container ? page.locator(container) : page;
-            const el = locator.startsWith('//') ? base.locator(`xpath=${locator}`) : base.locator(locator);
-            return await el.first().getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx);
-        }
-        catch (error) {
-            if (this.isFatalBrowserError(error)) {
-                tag('warning').log(`getEidxByLocator: ${error instanceof Error ? error.message : error}`);
-                await this.recoverFromBrowserError();
-            }
-            return null;
+    async recoverFromExecutionError(error) {
+        const message = browserErrorMessage(error);
+        tag('error').log(`Browser execution error: ${message}`);
+        if (error instanceof Error && error.name === 'AbortError') {
+            return { ok: false, action: 'stop', message };
         }
-    }
-    async reload() {
-        await this.closeOtherTabs();
-        await this.playwrightHelper.page.reload();
-    }
-    resolveBrowserUrl(url) {
-        if (!url)
-            return null;
-        try {
-            return new URL(url).toString();
+        if (error instanceof BrowserRecoveryError) {
+            return { ok: false, action: 'stop', recovered: error.recovered, message: error.message };
         }
-        catch { }
-        const baseUrl = this.config.playwright?.url || this.config.web?.url;
-        if (!baseUrl)
-            return null;
-        try {
-            return new URL(url, baseUrl).toString();
+        if (!isFatalBrowserError(error)) {
+            return {
+                ok: true,
+                action: 'continue',
+                message: `Previous execution error: ${message}. Investigate the current state and choose a different approach.`,
+            };
         }
-        catch {
-            return null;
+        if (!(await this.recoverOrRestart())) {
+            return { ok: false, action: 'stop', recovered: false, message: `Browser could not be recovered after fatal error: ${message}` };
         }
+        this.watchActiveTestPage();
+        return {
+            ok: true,
+            action: 'continue',
+            recovered: true,
+            message: dedent `
+        Browser was recovered after a fatal page error.
+        Continue from the restored page.
+        The interrupted browser action is not product evidence.
+        Inspect the restored page and retry the current step when it is still required.
+      `,
+        };
     }
-    isFatalBrowserError(error) {
-        return isFatalBrowserError(error);
+    async recoverOrRestart() {
+        if (await this.recoverPage())
+            return true;
+        return this.restartBrowser();
     }
-    async recoverFromBrowserError() {
+    async recoverPage() {
         try {
-            if (!this.playwrightHelper?.page || this.playwrightHelper.page.isClosed?.()) {
+            if (!this.page) {
                 const context = this.playwrightHelper?.browserContext;
                 if (!context)
-                    return await this.restartBrowser();
-                const page = await context.newPage();
-                await page.bringToFront();
-                await this.playwrightHelper._setPage(page);
-                this.bindFrameNavigated(page);
-                if (this.xhrCapture) {
-                    this.xhrCapture.attach(this.playwrightHelper.page);
-                }
+                    return false;
+                await this.activateNewPage(context);
             }
             const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
             if (url) {
                 tag('warning').log(`Browser error detected, recovering by navigating to ${url}`);
-                await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
+                await this.playwrightHelper.page.goto(url, RECOVERY_NAVIGATION);
                 return this.waitForPageReadiness();
             }
             tag('warning').log('Browser error detected, reloading page');
-            await this.playwrightHelper.page.reload({ waitUntil: 'domcontentloaded', timeout: 10000 });
+            await this.playwrightHelper.page.reload(RECOVERY_NAVIGATION);
             return this.waitForPageReadiness();
         }
         catch (err) {
-            tag('error').log(`Browser recovery failed: ${err instanceof Error ? err.message : err}`);
+            tag('error').log(`Browser recovery failed: ${browserErrorMessage(err)}`);
             return false;
         }
     }
+    async activateNewPage(context) {
+        const page = await context.newPage();
+        await page.bringToFront();
+        await this.playwrightHelper._setPage(page);
+        this.bindFrameNavigated(page);
+        this.xhrCapture?.attach(page);
+    }
+    async stopCaptures() {
+        if (this.xhrCapture && this.playwrightHelper?.page) {
+            this.xhrCapture.detach(this.playwrightHelper.page);
+        }
+        await this.playwrightRecorder.stop();
+    }
+    async closeBrowserContext() {
+        if (!this.playwrightHelper.browserContext)
+            return;
+        await this.playwrightHelper.browserContext.close().catch((err) => {
+            debugLog('Failed to close browser context:', err);
+        });
+        this.playwrightHelper.browserContext = null;
+    }
     async restartBrowser() {
         if (!this.playwrightHelper)
             return false;
         const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
         try {
-            if (this.xhrCapture && this.playwrightHelper.page) {
-                this.xhrCapture.detach(this.playwrightHelper.page);
-            }
-            await this.playwrightRecorder.stop();
-            if (this.playwrightHelper.browserContext) {
-                await this.playwrightHelper.browserContext.close().catch((err) => {
-                    debugLog('Failed to close browser context before restart:', err);
-                });
-                this.playwrightHelper.browserContext = null;
-            }
+            await this.stopCaptures();
+            await this.closeBrowserContext();
             if (!this.isSharedBrowser) {
                 await this.playwrightHelper._stopBrowser().catch((err) => {
                     debugLog('Failed to stop browser before restart:', err);
@@ -460,10 +448,10 @@ class Explorer {
             await this.connectOrLaunchBrowser();
             await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
             await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
-            this.setupXhrCapture(true);
+            this.attachXhrCapture();
             this.listenToStateChanged();
             if (url) {
-                await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
+                await this.playwrightHelper.page.goto(url, RECOVERY_NAVIGATION);
                 if (!(await this.waitForPageReadiness()))
                     return false;
             }
@@ -471,14 +459,25 @@ class Explorer {
             return true;
         }
         catch (err) {
-            tag('error').log(`Browser restart failed: ${err instanceof Error ? err.message : err}`);
+            tag('error').log(`Browser restart failed: ${browserErrorMessage(err)}`);
             return false;
         }
     }
-    async switchToMainFrame() {
-        if (this.playwrightHelper.frame) {
-            debugLog('Switching to main frame');
-            await this.playwrightHelper.switchTo();
+    resolveBrowserUrl(url) {
+        if (!url)
+            return null;
+        try {
+            return new URL(url).toString();
+        }
+        catch { }
+        const baseUrl = this.config.playwright?.url || this.config.web?.url;
+        if (!baseUrl)
+            return null;
+        try {
+            return new URL(url, baseUrl).toString();
+        }
+        catch {
+            return null;
         }
     }
     async waitForPageReadiness() {
@@ -491,219 +490,96 @@ class Explorer {
         });
         return true;
     }
-    async isInsideIframe() {
-        if (this.playwrightHelper.frame)
-            return true;
-        try {
-            const page = this.playwrightHelper.page;
-            if (!page)
-                return false;
-            return await page.evaluate(() => window.top !== window.self);
-        }
-        catch (error) {
-            if (this.isFatalBrowserError(error)) {
-                tag('warning').log(`isInsideIframe: ${error instanceof Error ? error.message : error}`);
-                await this.recoverFromBrowserError();
-            }
-            return false;
-        }
-    }
-    getCurrentIframeInfo() {
-        if (!this.playwrightHelper?.frame)
-            return null;
-        return 'iframe context active';
-    }
-    hasOtherTabs() {
-        return this.otherTabs.length > 0;
-    }
-    getOtherTabsInfo() {
-        return [...this.otherTabs];
-    }
-    clearOtherTabsInfo() {
-        this.otherTabs = [];
-    }
-    setUserResolve(userResolveFn) {
-        this.userResolveFn = userResolveFn;
-    }
     listenToStateChanged() {
-        if (!this.playwrightHelper) {
-            debugLog('Playwright helper not available for state monitoring');
+        const page = this.playwrightHelper?.page;
+        if (!page) {
+            debugLog('Playwright page not available for state monitoring');
             return;
         }
-        try {
-            const page = this.playwrightHelper.page;
-            if (!page) {
-                debugLog('Playwright page not available for state monitoring');
+        const initialPage = page;
+        const context = page.context();
+        context.on('page', async (newPage) => {
+            if (newPage === initialPage)
                 return;
-            }
-            const initialPage = page;
-            const context = this.playwrightHelper.page.context();
-            context.on('page', async (newPage) => {
-                if (newPage === initialPage) {
-                    return;
-                }
-                try {
-                    if (newPage.url() === 'about:blank') {
-                        await newPage.waitForURL(/^(?!about:blank$)/, { timeout: 5000 }).catch(() => { });
-                    }
-                    await newPage.waitForLoadState('domcontentloaded', { timeout: 5000 });
-                    const url = await newPage.url();
-                    const title = await newPage.title().catch(() => 'Unknown');
-                    this.otherTabs.push({ url, title });
-                    if (url !== 'about:blank') {
-                        tag('info').log(`New browser tab opened: ${url}`);
-                    }
-                    debugLog(`New tab detected: ${url} - ${title}`);
-                }
-                catch (error) {
-                    debugLog('Failed to get new tab info:', error);
-                    this.otherTabs.push({ url: 'unknown', title: 'unknown' });
-                }
-            });
-            this.bindFrameNavigated(page);
-            debugLog('Listening for automatic state changes');
-        }
-        catch (error) {
-            debugLog('Failed to set up state change monitoring:', error);
-        }
-    }
-    async stop() {
-        if (!this.isStarted) {
-            return;
-        }
-        if (this.xhrCapture && this.playwrightHelper?.page) {
-            this.xhrCapture.detach(this.playwrightHelper.page);
-        }
-        await this.playwrightRecorder.stop();
-        if (this.options?.session && this.playwrightHelper?.browserContext) {
-            const dir = path.dirname(this.options.session);
-            if (!existsSync(dir))
-                mkdirSync(dir, { recursive: true });
-            await this.playwrightHelper.browserContext.storageState({ path: this.options.session });
-            debugLog(`Session saved to ${path.relative(process.cwd(), this.options.session)}`);
-        }
-        codeceptjs.event.dispatcher.emit('global.after');
-        codeceptjs.event.dispatcher.emit('global.result');
-        if (this.isSharedBrowser) {
-            tag('info').log('Closing browser context (persistent browser stays running)');
             try {
-                if (this.playwrightHelper.browserContext) {
-                    await this.playwrightHelper.browserContext.close();
-                    this.playwrightHelper.browserContext = null;
+                if (newPage.url() === 'about:blank') {
+                    await newPage.waitForURL(/^(?!about:blank$)/, { timeout: 5000 }).catch(() => { });
                 }
+                await newPage.waitForLoadState('domcontentloaded', { timeout: 5000 });
+                const url = await newPage.url();
+                const title = await newPage.title().catch(() => 'Unknown');
+                this.stateManager.otherTabs.push({ url, title });
+                if (url !== 'about:blank') {
+                    tag('info').log(`New browser tab opened: ${url}`);
+                }
+                debugLog(`New tab detected: ${url} - ${title}`);
             }
-            catch (err) {
-                debugLog('Failed to close browser context:', err);
+            catch (error) {
+                debugLog('Failed to get new tab info:', error);
+                this.stateManager.otherTabs.push({ url: 'unknown', title: 'unknown' });
             }
-            this.playwrightHelper.browser = null;
-            this.playwrightHelper.isRunning = false;
-            await Promise.all([this.reporter.finishRun(), codeceptjs.recorder.stop()]);
-        }
-        else {
-            await Promise.all([this.reporter.finishRun(), this.playwrightHelper._stopBrowser(), codeceptjs.recorder.stop()]);
-        }
-    }
-    get activeTest() {
-        return this._activeTest;
+        });
+        this.bindFrameNavigated(page);
+        debugLog('Listening for automatic state changes');
     }
-    async startTest(test) {
-        this._activeTest = test;
-        test.start();
-        await this.reporter.reportTestStart(test);
-        await this.closeOtherTabs();
-        this.otherTabs = [];
-        if (!(await this.ensurePageAvailable()))
-            return false;
-        const codeceptjsTest = toCodeceptjsTest(test);
-        const stepHandler = (step, status, error, log) => {
-            if (!step.toCode)
-                return;
-            if (step?.name?.startsWith('grab'))
-                return;
-            if (step?.name?.startsWith('save'))
-                return;
-            test.addStep(step.toCode(), step.duration, status, error, log);
-            if (!this.stateManager.getCurrentState())
+    bindFrameNavigated(page) {
+        page.on('framenavigated', async (frame) => {
+            if (frame !== page.mainFrame())
                 return;
-            const lastScreenshot = ActionResult.fromState(this.stateManager.getCurrentState()).screenshotFile;
-            test.setActiveNoteScreenshot(lastScreenshot);
-        };
-        this.watchActiveTestPage();
-        const onStepPassed = (step) => stepHandler(step, 'passed');
-        const onStepFailed = (step, error) => {
-            stepHandler(step, 'failed', error?.message || String(error), error?.stack);
-        };
-        const onTestAfter = () => {
-            codeceptjs.event.dispatcher.off('step.passed', onStepPassed);
-            codeceptjs.event.dispatcher.off('step.failed', onStepFailed);
-            codeceptjs.event.dispatcher.off('test.after', onTestAfter);
-            this.unwatchActiveTestPages();
-        };
-        codeceptjs.event.dispatcher.emit('test.before', codeceptjsTest);
-        codeceptjs.event.dispatcher.emit('test.start', codeceptjsTest);
-        codeceptjs.event.dispatcher.on('step.passed', onStepPassed);
-        codeceptjs.event.dispatcher.on('step.failed', onStepFailed);
-        codeceptjs.event.dispatcher.on('test.after', onTestAfter);
-        return true;
+            const newUrl = await frame.url();
+            let newTitle = '';
+            try {
+                newTitle = await frame.title();
+            }
+            catch (error) {
+                debugLog('Failed to get page title:', error);
+            }
+            this.stateManager.updateStateFromBasic(newUrl, newTitle, 'navigation');
+            await sleep(500);
+        });
     }
-    async ensurePageAvailable() {
-        const page = this.playwrightHelper?.page;
-        if (page && !page.isClosed?.()) {
-            this.watchActiveTestPage(page);
-            return true;
+    async closeOtherTabs() {
+        if (!this.playwrightHelper)
+            return;
+        const context = this.playwrightHelper.page.context();
+        const pages = context.pages();
+        if (pages.length <= 1)
+            return;
+        debugLog(`Found ${pages.length} tabs, cleaning up to keep only the first one`);
+        const firstPage = pages[0];
+        const tabsToClose = pages.slice(1);
+        for (const page of tabsToClose) {
+            await page.close();
+            debugLog(`Closed extra tab: ${await page.url()}`);
         }
-        const recovered = await this.recoverFromBrowserError();
-        if (!recovered)
-            return false;
-        this.watchActiveTestPage();
-        return true;
-    }
-    async ensureActiveTestPageAvailable() {
-        return this.ensurePageAvailable();
+        await firstPage.bringToFront();
+        await this.playwrightHelper._setPage(firstPage);
+        debugLog(`Cleaned up tabs, now focused on: ${await firstPage.url()}`);
     }
-    async handleExecutionError(error) {
-        const message = error instanceof Error ? error.message : String(error);
-        tag('error').log(`Browser execution error: ${message}`);
-        if (error instanceof Error && error.name === 'AbortError') {
-            return {
-                action: 'stop',
-                message,
-            };
+    async finishTest(test, meta) {
+        this.unwatchActiveTestPages();
+        this._activeTest = null;
+        const lastScreenshot = this.stateManager.getCurrentState()?.screenshotFile;
+        if (lastScreenshot) {
+            meta ||= {};
+            meta.screenshotFile = lastScreenshot;
         }
-        if (error instanceof BrowserRecoveryError) {
-            return {
-                action: 'stop',
-                recovered: error.recovered,
-                message: error.message,
-            };
+        await this.reporter.reportTest(test, meta);
+        const codeceptjsTest = toCodeceptjsTest(test);
+        if (test.isSuccessful) {
+            codeceptjsTest.state = 'passed';
+            codeceptjs.event.dispatcher.emit('test.passed', codeceptjsTest);
         }
-        if (!this.isFatalBrowserError(error)) {
-            return {
-                action: 'continue',
-                message: `Previous execution error: ${message}. Investigate the current state and choose a different approach.`,
-            };
+        else if (test.isSkipped) {
+            codeceptjsTest.state = 'skipped';
+            codeceptjs.event.dispatcher.emit('test.skipped', codeceptjsTest);
         }
-        let recovered = await this.recoverFromBrowserError();
-        if (!recovered)
-            recovered = await this.restartBrowser();
-        if (!recovered) {
-            return {
-                action: 'stop',
-                recovered: false,
-                message: `Browser could not be recovered after fatal error: ${message}`,
-            };
+        else {
+            codeceptjsTest.state = 'failed';
+            codeceptjs.event.dispatcher.emit('test.failed', codeceptjsTest);
         }
-        this.watchActiveTestPage();
-        return {
-            action: 'continue',
-            recovered: true,
-            message: dedent `
-        Browser was recovered after a fatal page error.
-        Continue from the restored page.
-        The interrupted browser action is not product evidence.
-        Inspect the restored page and retry the current step when it is still required.
-      `,
-        };
+        codeceptjs.event.dispatcher.emit('test.finish', codeceptjsTest);
+        codeceptjs.event.dispatcher.emit('test.after', codeceptjsTest);
     }
     watchActiveTestPage(page = this.playwrightHelper?.page) {
         if (!this._activeTest)
@@ -730,31 +606,6 @@ class Explorer {
         page.on('dialog', this.testDialogHandler);
         this.observedTestPages.add(page);
     }
-    async stopTest(test, meta) {
-        this.unwatchActiveTestPages();
-        this._activeTest = null;
-        const lastScreenshot = this.stateManager.getCurrentState()?.screenshotFile;
-        if (lastScreenshot) {
-            meta ||= {};
-            meta.screenshotFile = lastScreenshot;
-        }
-        await this.reporter.reportTest(test, meta);
-        const codeceptjsTest = toCodeceptjsTest(test);
-        if (test.isSuccessful) {
-            codeceptjsTest.state = 'passed';
-            codeceptjs.event.dispatcher.emit('test.passed', codeceptjsTest);
-        }
-        else if (test.isSkipped) {
-            codeceptjsTest.state = 'skipped';
-            codeceptjs.event.dispatcher.emit('test.skipped', codeceptjsTest);
-        }
-        else {
-            codeceptjsTest.state = 'failed';
-            codeceptjs.event.dispatcher.emit('test.failed', codeceptjsTest);
-        }
-        codeceptjs.event.dispatcher.emit('test.finish', codeceptjsTest);
-        codeceptjs.event.dispatcher.emit('test.after', codeceptjsTest);
-    }
     unwatchActiveTestPages() {
         for (const page of this.observedTestPages) {
             if (this.testPageErrorHandler)
@@ -766,94 +617,6 @@ class Explorer {
         }
         this.observedTestPages.clear();
     }
-    async hasPlaywrightLocator(locatorFn, opts = {}) {
-        try {
-            const pwLocator = locatorFn(this.playwrightHelper.page);
-            const count = await pwLocator.count();
-            if (opts.multiple ? count === 0 : count !== 1)
-                return false;
-            if (opts.contents) {
-                const html = await pwLocator.first().innerHTML();
-                if (!html?.trim())
-                    return false;
-            }
-            if (opts.success)
-                await opts.success(pwLocator);
-            return true;
-        }
-        catch (error) {
-            if (this.isFatalBrowserError(error)) {
-                tag('warning').log(`hasPlaywrightLocator: ${error instanceof Error ? error.message : error}`);
-                await this.recoverFromBrowserError();
-            }
-            return false;
-        }
-    }
-    async playwrightLocatorCount(locatorFn) {
-        try {
-            const pwLocator = locatorFn(this.playwrightHelper.page);
-            return await pwLocator.count();
-        }
-        catch (error) {
-            if (this.isFatalBrowserError(error)) {
-                tag('warning').log(`playwrightLocatorCount: ${error instanceof Error ? error.message : error}`);
-                await this.recoverFromBrowserError();
-            }
-            throw error;
-        }
-    }
-    bindFrameNavigated(page) {
-        page.on('framenavigated', async (frame) => {
-            if (frame !== page.mainFrame())
-                return;
-            const newUrl = await frame.url();
-            let newTitle = '';
-            try {
-                newTitle = await frame.title();
-            }
-            catch (error) {
-                debugLog('Failed to get page title:', error);
-            }
-            this.stateManager.updateStateFromBasic(newUrl, newTitle, 'navigation');
-            await new Promise((resolve) => setTimeout(resolve, 500));
-        });
-    }
-    async openFreshTab() {
-        if (!this.playwrightHelper?.page)
-            return;
-        const oldPage = this.playwrightHelper.page;
-        const context = oldPage.context();
-        const newPage = await context.newPage();
-        await oldPage.close();
-        await newPage.bringToFront();
-        await this.playwrightHelper._setPage(newPage);
-        this.otherTabs = [];
-        this.bindFrameNavigated(newPage);
-        if (this.xhrCapture) {
-            this.xhrCapture.attach(newPage);
-        }
-        debugLog('Opened fresh tab, closed previous tab');
-    }
-    async closeOtherTabs() {
-        if (!this.playwrightHelper) {
-            return;
-        }
-        const context = this.playwrightHelper.page.context();
-        const pages = context.pages();
-        if (pages.length <= 1) {
-            return;
-        }
-        debugLog(`Found ${pages.length} tabs, cleaning up to keep only the first one`);
-        const firstPage = pages[0];
-        const tabsToClose = pages.slice(1);
-        for (const page of tabsToClose) {
-            await page.close();
-            debugLog(`Closed extra tab: ${await page.url()}`);
-        }
-        await firstPage.bringToFront();
-        await this.playwrightHelper._setPage(firstPage);
-        debugLog(`Cleaned up tabs, now focused on: ${await firstPage.url()}`);
-    }
 }
 function toCodeceptjsTest(test) {
     const parent = {
@@ -868,58 +631,4 @@ function toCodeceptjsTest(test) {
     codeceptjsTest._explorbotTest = test;
     return codeceptjsTest;
 }
-const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
-const ANNOTATABLE_ROLES = new Set(['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem']);
-function parseAriaRefs(ariaSnapshot) {
-    const entries = [];
-    for (const line of ariaSnapshot.split('\n')) {
-        const match = line.match(REF_LINE_PATTERN);
-        if (!match)
-            continue;
-        if (!ANNOTATABLE_ROLES.has(match[2]))
-            continue;
-        entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
-    }
-    return entries;
-}
-export async function annotatePageElements(page) {
-    const ariaSnapshot = await page.locator('body').ariaSnapshot({ mode: 'ai' });
-    const refEntries = parseAriaRefs(ariaSnapshot);
-    const byRole = new Map();
-    for (const { role, name, ref } of refEntries) {
-        let list = byRole.get(role);
-        if (!list) {
-            list = [];
-            byRole.set(role, list);
-        }
-        list.push({ name, ref });
-    }
-    const elements = [];
-    for (const [role, entries] of byRole) {
-        try {
-            const rawList = await page.getByRole(role).evaluateAll((domElements, [data, extractFnStr, config]) => {
-                const extract = new Function(`return ${extractFnStr}`)();
-                const results = [];
-                let ariaIdx = 0;
-                for (const el of domElements) {
-                    if (ariaIdx >= data.length)
-                        break;
-                    el.setAttribute(config.attrs.eidx, data[ariaIdx].ref);
-                    const elData = extract(el, config);
-                    if (elData)
-                        results.push(elData);
-                    ariaIdx++;
-                }
-                return results;
-            }, [entries, getElementDataExtractorSource(), ELEMENT_EXTRACTION_CONFIG]);
-            for (const raw of rawList) {
-                elements.push(WebElement.fromRawData(raw, role));
-            }
-        }
-        catch {
-            debugLog(`Failed to annotate role=${role}`);
-        }
-    }
-    return { ariaSnapshot, elements };
-}
 export default Explorer;