explorbot 0.2.0 → 0.2.2

package/src/explorer.ts

@@ -1,31 +1,26 @@
 import { existsSync, mkdirSync } from 'node:fs';
-import path, { join } from 'node:path';
+import path from 'node:path';
 // @ts-ignore
 import * as codeceptjs from 'codeceptjs';
 import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
 import dedent from 'dedent';
-import type { BrowserContextOptions } from 'playwright';
+import type { BrowserContextOptions, Page } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
-import { AIProvider } from './ai/provider.js';
-import { visuallyAnnotateContainers } from './ai/researcher/coordinates.ts';
-import { RequestStore } from './api/request-store.ts';
+import type { RequestStore } from './api/request-store.ts';
 import { XhrCapture } from './api/xhr-capture.ts';
 import type { ExplorbotConfig } from './config.js';
 import { ConfigParser } from './config.js';
-import type { ExperienceTracker } from './experience-tracker.js';
-import { KnowledgeTracker } from './knowledge-tracker.js';
-import { PlaywrightRecorder } from './playwright-recorder.ts';
-import { Reporter } from './reporter.ts';
-import { StateManager } from './state-manager.js';
+import type { KnowledgeTracker } from './knowledge-tracker.js';
+import type { PlaywrightRecorder } from './playwright-recorder.ts';
+import type { Reporter } from './reporter.ts';
+import type { StateManager } from './state-manager.js';
 import { Test, TestResult } from './test-plan.ts';
 import { BrowserRecoveryError, browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from './utils/browser-errors.ts';
-import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './utils/html.ts';
 import { createDebug, log, tag } from './utils/logger.js';
 import { sleep, waitForPageReadiness } from './utils/page-readiness.ts';
-import { WebElement } from './utils/web-element.ts';
 
 declare global {
   namespace NodeJS {
@@ -43,66 +38,219 @@ declare namespace CodeceptJS {
 
 const debugLog = createDebug('explorbot:explorer');
 const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
-
-interface TabInfo {
-  url: string;
-  title: string;
-}
-
-interface BrowserExecutionErrorResult {
-  action: 'continue' | 'stop';
-  message: string;
-  recovered?: boolean;
-}
+const RECOVERY_NAVIGATION = { waitUntil: 'domcontentloaded', timeout: 10000 } as const;
 
 class Explorer {
-  private aiProvider: AIProvider;
-  playwrightHelper: any;
-  public isStarted = false;
+  private config: ExplorbotConfig;
+  private options?: ExplorerOptions;
+  private stateManager: StateManager;
+  private knowledgeTracker: KnowledgeTracker;
+  private reporter: Reporter;
+  private requestStore: RequestStore;
+  private playwrightRecorder: PlaywrightRecorder;
+  private playwrightHelper: any;
+  private _actor!: CodeceptJS.I;
+  private started = false;
   private isSharedBrowser = false;
-  actor!: CodeceptJS.I;
-  private stateManager!: StateManager;
-  private knowledgeTracker!: KnowledgeTracker;
-  config: ExplorbotConfig;
-  private options?: { show?: boolean; headless?: boolean; incognito?: boolean; session?: string };
-  private reporter!: Reporter;
-  private otherTabs: TabInfo[] = [];
-  private _activeTest: Test | null = null;
   private xhrCapture: XhrCapture | null = null;
-  private requestStore: RequestStore | null = null;
-  private playwrightRecorder: PlaywrightRecorder = new PlaywrightRecorder();
+  private _activeTest: Test | null = null;
   private observedTestPages = new Set<any>();
   private testPageErrorHandler: ((error: Error) => void) | null = null;
   private testConsoleHandler: ((message: any) => void) | null = null;
   private testDialogHandler: ((dialog: any) => void) | null = null;
+  private eventDispatcher = codeceptjs.event.dispatcher;
 
-  constructor(config: ExplorbotConfig, aiProvider: AIProvider, options: { show?: boolean; headless?: boolean; incognito?: boolean; session?: string } | undefined, experienceTracker: ExperienceTracker, knowledgeTracker: KnowledgeTracker) {
+  constructor(config: ExplorbotConfig, options: ExplorerOptions | undefined, deps: ExplorerDeps) {
     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.knowledgeTracker = knowledgeTracker;
-    this.stateManager = new StateManager(experienceTracker, knowledgeTracker);
-    this.reporter = new Reporter(config.reporter, this.stateManager);
   }
 
-  private initializeContainer() {
-    try {
-      // Use project root for output directory, not current working directory
-      const configParser = ConfigParser.getInstance();
-      const projectRoot = configParser.getProjectRoot();
-      (global as any).output_dir = path.join(projectRoot, 'output', 'states');
-      (global as any).codecept_dir = projectRoot;
+  get actor(): CodeceptJS.I {
+    return this._actor;
+  }
+
+  get page(): Page | null {
+    const page = this.playwrightHelper?.page;
+    if (!page || page.isClosed?.()) return null;
+    return page;
+  }
+
+  get activeTest(): Test | null {
+    return this._activeTest;
+  }
 
-      configParser.validateConfig(this.config);
+  async start(): Promise<void> {
+    if (this.started) return;
 
-      const codeceptConfig = this.convertToCodeceptConfig(this.config);
+    await codeceptjs.recorder.start();
+    await codeceptjs.container.started(null);
+    storeListener();
+    stepsListener();
 
-      codeceptjs.container.create(codeceptConfig, {});
-    } catch (error) {
-      log(`❌ Failed to initialize container: ${error}`);
-      throw error;
+    codeceptjs.recorder.retry({
+      retries: this.config.action?.retries || 3,
+      when: (err: any) => !!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.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(): Promise<void> {
+    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(): Action {
+    return new Action(this._actor, this.stateManager, this.playwrightRecorder, (fn) => this.runWithRecovery('action', fn));
+  }
+
+  async visit(url: string, opts: CaptureOpts = {}): Promise<ActionResult> {
+    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: CaptureOpts = {}): Promise<ActionResult> {
+    return this.action().capturePageState({ includeScreenshot: opts.screenshot });
+  }
+
+  async withPage<T>(fn: (page: Page) => Promise<T>): Promise<T> {
+    return this.runWithRecovery('page operation', () => fn(this.playwrightHelper.page));
+  }
+
+  async recover(error?: unknown): Promise<Recovery> {
+    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: Test): Promise<TestRun> {
+    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: any, status?: string, error?: string, log?: string) => {
+      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: any) => stepHandler(step, 'passed');
+    const onStepFailed = (step: any, error: any) => {
+      stepHandler(step, 'failed', error?.message || String(error), error?.stack);
+    };
+    const onTestAfter = () => {
+      this.eventDispatcher.off('step.passed', onStepPassed);
+      this.eventDispatcher.off('step.failed', onStepFailed);
+      this.eventDispatcher.off('test.after', onTestAfter);
+      this.unwatchActiveTestPages();
+    };
+
+    this.eventDispatcher.emit('test.before', codeceptjsTest);
+    this.eventDispatcher.emit('test.start', codeceptjsTest);
+    this.eventDispatcher.on('step.passed', onStepPassed);
+    this.eventDispatcher.on('step.failed', onStepFailed);
+    this.eventDispatcher.on('test.after', onTestAfter);
+
+    return { started: true, stop: (meta) => this.finishTest(test, meta) };
+  }
+
+  async openTab(): Promise<void> {
+    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');
+  }
+
+  private initializeContainer() {
+    const configParser = ConfigParser.getInstance();
+    const projectRoot = configParser.getProjectRoot();
+    (global as any).output_dir = configParser.getStatesDir();
+    (global as any).codecept_dir = projectRoot;
+
+    configParser.validateConfig(this.config);
+
+    codeceptjs.container.create(this.convertToCodeceptConfig(this.config), {});
   }
 
   private convertToCodeceptConfig(config: ExplorbotConfig): any {
@@ -160,99 +308,6 @@ class Explorer {
     return codeceptConfig;
   }
 
-  public getConfig(): ExplorbotConfig {
-    return this.config;
-  }
-
-  public getAIProvider(): AIProvider {
-    return this.aiProvider;
-  }
-
-  public getStateManager(): StateManager {
-    return this.stateManager;
-  }
-
-  public getKnowledgeTracker(): KnowledgeTracker {
-    return this.knowledgeTracker;
-  }
-
-  public getReporter(): Reporter {
-    return this.reporter;
-  }
-
-  public getRequestStore(): RequestStore | null {
-    return this.requestStore;
-  }
-
-  async extractCookies(): Promise<Record<string, string>> {
-    if (!this.playwrightHelper?.browserContext) return {};
-    try {
-      const cookies = await this.playwrightHelper.browserContext.cookies();
-      if (!cookies.length) return {};
-      const cookieString = cookies.map((c: any) => `${c.name}=${c.value}`).join('; ');
-      return { Cookie: cookieString };
-    } catch {
-      return {};
-    }
-  }
-
-  private setupXhrCapture(reuseRequestStore = false): void {
-    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;
-    }
-
-    await codeceptjs.recorder.start();
-    await codeceptjs.container.started(null);
-    storeListener();
-    stepsListener();
-
-    codeceptjs.recorder.retry({
-      retries: this.config.action?.retries || 3,
-      when: (err: any) => {
-        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;
-  }
-
   private async connectOrLaunchBrowser(): Promise<void> {
     const { getAliveEndpoint } = await import('./browser-server.js');
     const endpoint = await getAliveEndpoint();
@@ -284,12 +339,13 @@ class Explorer {
     return contextOptions;
   }
 
-  createAction() {
-    return new Action(this.actor, this.stateManager, this.playwrightRecorder);
+  private attachXhrCapture(): void {
+    this.xhrCapture = new XhrCapture(this.requestStore, this.config.playwright.url);
+    this.xhrCapture.attach(this.playwrightHelper.page);
   }
 
-  async runWithBrowserRecovery<T>(label: string, operation: () => Promise<T>): Promise<T> {
-    if (!(await this.ensurePageAvailable())) {
+  private async runWithRecovery<T>(label: string, operation: () => Promise<T>): Promise<T> {
+    if (!this.page && !(await this.recoverOrRestart())) {
       throw new Error(`Browser page is unavailable before ${label}`);
     }
 
@@ -304,23 +360,21 @@ class Explorer {
         try {
           return await operation();
         } catch (retryError) {
-          if (!isNavigationTransitionError(retryError) && !this.isFatalBrowserError(retryError)) throw retryError;
+          if (!isNavigationTransitionError(retryError) && !isFatalBrowserError(retryError)) throw retryError;
           recoveryError = retryError;
         }
       }
 
-      if (!this.isFatalBrowserError(recoveryError)) throw 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) throw new BrowserRecoveryError(label, recoveryError, false);
+      if (!(await this.recoverOrRestart())) throw new BrowserRecoveryError(label, recoveryError, false);
       if (!(await this.waitForPageReadiness())) throw new BrowserRecoveryError(label, recoveryError, true);
 
       try {
         return await operation();
       } catch (retryError) {
-        if (this.isFatalBrowserError(retryError)) {
+        if (isFatalBrowserError(retryError)) {
           throw new BrowserRecoveryError(label, retryError, true);
         }
         throw retryError;
@@ -328,31 +382,7 @@ class Explorer {
     }
   }
 
-  async capturePageState(opts: { includeScreenshot?: boolean } = {}): Promise<ActionResult> {
-    return this.runWithBrowserRecovery('capturePageState', () => this.createAction().capturePageState(opts));
-  }
-
-  async capturePageWithScreenshot(): Promise<ActionResult> {
-    return this.capturePageState({ includeScreenshot: true });
-  }
-
-  async executeAction(code: string): Promise<Action> {
-    return this.runWithBrowserRecovery('executeAction', () => this.createAction().execute(code));
-  }
-
-  async attemptAction(code: string, originalMessage?: string): Promise<boolean> {
-    return this.runWithBrowserRecovery('attemptAction', () => this.createAction().attempt(code, originalMessage));
-  }
-
-  getPlaywrightRecorder(): PlaywrightRecorder {
-    return this.playwrightRecorder;
-  }
-
-  async visit(url: string) {
-    return this.runWithBrowserRecovery('visit', () => this.visitOnce(url));
-  }
-
-  private async visitOnce(url: string) {
+  private async visitOnce(url: string): Promise<Action> {
     await this.closeOtherTabs();
 
     const serializedUrl = JSON.stringify(url);
@@ -361,7 +391,7 @@ class Explorer {
 
     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')); })`);
@@ -394,94 +424,65 @@ class Explorer {
     return action;
   }
 
-  async annotateElements(): Promise<WebElement[]> {
-    return this.runWithBrowserRecovery('annotateElements', async () => {
-      const { elements } = await annotatePageElements(this.playwrightHelper.page);
-      return elements;
-    });
-  }
-
-  async visuallyAnnotateElements(opts?: { containers?: Array<{ css: string; label: string }> }): Promise<number> {
-    return this.runWithBrowserRecovery('visuallyAnnotateElements', () => visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []));
-  }
+  private async recoverFromExecutionError(error: unknown): Promise<Recovery> {
+    const message = browserErrorMessage(error);
+    tag('error').log(`Browser execution error: ${message}`);
 
-  async getEidxInContainer(containerCss: string | null): Promise<string[]> {
-    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: string[] = [];
-      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: ${browserErrorMessage(error)}`);
-        await this.recoverFromBrowserError();
-      }
-      return [];
+    if (error instanceof Error && error.name === 'AbortError') {
+      return { ok: false, action: 'stop', message };
     }
-  }
 
-  async getEidxByLocator(locator: string, container?: string | null): Promise<string | null> {
-    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: ${browserErrorMessage(error)}`);
-        await this.recoverFromBrowserError();
-      }
-      return null;
+    if (error instanceof BrowserRecoveryError) {
+      return { ok: false, action: 'stop', recovered: error.recovered, message: error.message };
     }
-  }
-
-  private resolveBrowserUrl(url?: string): string | null {
-    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;
+    if (!isFatalBrowserError(error)) {
+      return {
+        ok: true,
+        action: 'continue',
+        message: `Previous execution error: ${message}. Investigate the current state and choose a different approach.`,
+      };
+    }
 
-    try {
-      return new URL(url, baseUrl).toString();
-    } 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: unknown): boolean {
-    return isFatalBrowserError(error);
+  private async recoverOrRestart(): Promise<boolean> {
+    if (await this.recoverPage()) return true;
+    return this.restartBrowser();
   }
 
-  async recoverFromBrowserError(): Promise<boolean> {
+  private async recoverPage(): Promise<boolean> {
     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);
-        }
+        if (!context) 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: ${browserErrorMessage(err)}`);
@@ -489,24 +490,37 @@ class Explorer {
     }
   }
 
-  async restartBrowser(): Promise<boolean> {
+  private async activateNewPage(context: any): Promise<void> {
+    const page = await context.newPage();
+    await page.bringToFront();
+    await this.playwrightHelper._setPage(page);
+    this.bindFrameNavigated(page);
+    this.xhrCapture?.attach(page);
+  }
+
+  private async stopCaptures(): Promise<void> {
+    if (this.xhrCapture && this.playwrightHelper?.page) {
+      this.xhrCapture.detach(this.playwrightHelper.page);
+    }
+    await this.playwrightRecorder.stop();
+  }
+
+  private async closeBrowserContext(): Promise<void> {
+    if (!this.playwrightHelper.browserContext) return;
+    await this.playwrightHelper.browserContext.close().catch((err: unknown) => {
+      debugLog('Failed to close browser context:', err);
+    });
+    this.playwrightHelper.browserContext = null;
+  }
+
+  private async restartBrowser(): Promise<boolean> {
     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: unknown) => {
-          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: unknown) => {
@@ -517,11 +531,11 @@ 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;
       }
 
@@ -533,10 +547,19 @@ class Explorer {
     }
   }
 
-  async switchToMainFrame() {
-    if (this.playwrightHelper.frame) {
-      debugLog('Switching to main frame');
-      await this.playwrightHelper.switchTo();
+  private resolveBrowserUrl(url?: string): string | null {
+    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;
     }
   }
 
@@ -551,238 +574,112 @@ class Explorer {
     return true;
   }
 
-  async isInsideIframe(): Promise<boolean> {
-    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: ${browserErrorMessage(error)}`);
-        await this.recoverFromBrowserError();
-      }
-      return false;
-    }
-  }
-
-  getCurrentIframeInfo(): string | null {
-    if (!this.playwrightHelper?.frame) return null;
-    return 'iframe context active';
-  }
-
-  hasOtherTabs(): boolean {
-    return this.otherTabs.length > 0;
-  }
-
-  getOtherTabsInfo(): TabInfo[] {
-    return [...this.otherTabs];
-  }
-
-  clearOtherTabsInfo(): void {
-    this.otherTabs = [];
-  }
-
   private listenToStateChanged(): void {
-    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;
     }
+    const initialPage = page;
+    const context = page.context();
 
-    try {
-      const page = this.playwrightHelper.page;
-      if (!page) {
-        debugLog('Playwright page not available for state monitoring');
-        return;
-      }
-      const initialPage = page;
-      const context = this.playwrightHelper.page.context();
+    context.on('page', async (newPage: any) => {
+      if (newPage === initialPage) return;
 
-      context.on('page', async (newPage: any) => {
-        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');
 
-        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.stateManager.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.stateManager.otherTabs.push({ url: 'unknown', title: 'unknown' });
+      }
+    });
 
-      this.bindFrameNavigated(page);
+    this.bindFrameNavigated(page);
 
-      debugLog('Listening for automatic state changes');
-    } catch (error) {
-      debugLog('Failed to set up state change monitoring:', error);
-    }
+    debugLog('Listening for automatic state changes');
   }
 
-  async stop(): Promise<void> {
-    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)}`);
-    }
+  private bindFrameNavigated(page: any): void {
+    page.on('framenavigated', async (frame: any) => {
+      if (frame !== page.mainFrame()) return;
 
-    codeceptjs.event.dispatcher.emit('global.after');
-    codeceptjs.event.dispatcher.emit('global.result');
+      const newUrl = await frame.url();
+      let newTitle = '';
 
-    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;
-        }
-      } catch (err) {
-        debugLog('Failed to close browser context:', err);
+        newTitle = await frame.title();
+      } catch (error) {
+        debugLog('Failed to get page title:', error);
       }
-      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(): Test | null {
-    return this._activeTest;
-  }
-
-  async startTest(test: Test): Promise<boolean> {
-    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: any, status?: string, error?: string, log?: string) => {
-      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);
+      this.stateManager.updateStateFromBasic(newUrl, newTitle, 'navigation');
 
-      if (!this.stateManager.getCurrentState()) return;
+      await sleep(500);
+    });
+  }
 
-      const lastScreenshot = ActionResult.fromState(this.stateManager.getCurrentState()!).screenshotFile;
-      test.setActiveNoteScreenshot(lastScreenshot);
-    };
+  private async closeOtherTabs(): Promise<void> {
+    if (!this.playwrightHelper) return;
 
-    this.watchActiveTestPage();
+    const context = this.playwrightHelper.page.context();
+    const pages = context.pages();
 
-    const onStepPassed = (step: any) => stepHandler(step, 'passed');
-    const onStepFailed = (step: any, error: any) => {
-      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();
-    };
+    if (pages.length <= 1) return;
 
-    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);
+    debugLog(`Found ${pages.length} tabs, cleaning up to keep only the first one`);
 
-    return true;
-  }
+    const firstPage = pages[0];
+    const tabsToClose = pages.slice(1);
 
-  async ensurePageAvailable(): Promise<boolean> {
-    const page = this.playwrightHelper?.page;
-    if (page && !page.isClosed?.()) {
-      this.watchActiveTestPage(page);
-      return true;
+    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 handleExecutionError(error: unknown): Promise<BrowserExecutionErrorResult> {
-    const message = browserErrorMessage(error);
-    tag('error').log(`Browser execution error: ${message}`);
-
-    if (error instanceof Error && error.name === 'AbortError') {
-      return {
-        action: 'stop',
-        message,
-      };
-    }
+    await firstPage.bringToFront();
+    await this.playwrightHelper._setPage(firstPage);
 
-    if (error instanceof BrowserRecoveryError) {
-      return {
-        action: 'stop',
-        recovered: error.recovered,
-        message: error.message,
-      };
-    }
+    debugLog(`Cleaned up tabs, now focused on: ${await firstPage.url()}`);
+  }
 
-    if (!this.isFatalBrowserError(error)) {
-      return {
-        action: 'continue',
-        message: `Previous execution error: ${message}. Investigate the current state and choose a different approach.`,
-      };
+  private async finishTest(test: Test, meta?: Record<string, string>): Promise<void> {
+    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);
 
-    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}`,
-      };
+    if (test.isSuccessful) {
+      codeceptjsTest.state = 'passed';
+      this.eventDispatcher.emit('test.passed', codeceptjsTest);
+    } else if (test.isSkipped) {
+      codeceptjsTest.state = 'skipped';
+      this.eventDispatcher.emit('test.skipped', codeceptjsTest);
+    } else {
+      codeceptjsTest.state = 'failed';
+      this.eventDispatcher.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.
-      `,
-    };
+    this.eventDispatcher.emit('test.finish', codeceptjsTest);
+    this.eventDispatcher.emit('test.after', codeceptjsTest);
   }
 
-  watchActiveTestPage(page = this.playwrightHelper?.page): void {
+  private watchActiveTestPage(page = this.playwrightHelper?.page): void {
     if (!this._activeTest) return;
     if (!page) return;
     if (this.observedTestPages.has(page)) return;
@@ -806,32 +703,6 @@ class Explorer {
     this.observedTestPages.add(page);
   }
 
-  async stopTest(test: Test, meta?: Record<string, string>) {
-    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);
-  }
-
   private unwatchActiveTestPages(): void {
     for (const page of this.observedTestPages) {
       if (this.testPageErrorHandler) page.off('pageerror', this.testPageErrorHandler);
@@ -840,87 +711,6 @@ class Explorer {
     }
     this.observedTestPages.clear();
   }
-
-  async playwrightLocatorCount(locatorFn: (page: any) => any): Promise<number> {
-    try {
-      const pwLocator = locatorFn(this.playwrightHelper.page);
-      return await pwLocator.count();
-    } catch (error) {
-      if (this.isFatalBrowserError(error)) {
-        tag('warning').log(`playwrightLocatorCount: ${browserErrorMessage(error)}`);
-        await this.recoverFromBrowserError();
-      }
-      throw error;
-    }
-  }
-
-  private bindFrameNavigated(page: any): void {
-    page.on('framenavigated', async (frame: any) => {
-      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 sleep(500);
-    });
-  }
-
-  async openFreshTab(): Promise<void> {
-    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');
-  }
-
-  private async closeOtherTabs(): Promise<void> {
-    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: Test): any {
@@ -938,63 +728,35 @@ function toCodeceptjsTest(test: Test): any {
   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: string): Array<{ role: string; name: string; ref: string }> {
-  const entries: Array<{ role: string; name: string; ref: string }> = [];
-  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 interface ExplorerOptions {
+  show?: boolean;
+  headless?: boolean;
+  incognito?: boolean;
+  session?: string;
 }
 
-export async function annotatePageElements(page: any): Promise<{ ariaSnapshot: string; elements: WebElement[] }> {
-  const ariaSnapshot: string = await page.locator('body').ariaSnapshot({ mode: 'ai' });
-  const refEntries = parseAriaRefs(ariaSnapshot);
+export interface ExplorerDeps {
+  stateManager: StateManager;
+  knowledgeTracker: KnowledgeTracker;
+  reporter: Reporter;
+  requestStore: RequestStore;
+  playwrightRecorder: PlaywrightRecorder;
+}
 
-  const byRole = new Map<string, Array<{ name: string; ref: string }>>();
-  for (const { role, name, ref } of refEntries) {
-    let list = byRole.get(role);
-    if (!list) {
-      list = [];
-      byRole.set(role, list);
-    }
-    list.push({ name, ref });
-  }
+export interface Recovery {
+  ok: boolean;
+  action: 'continue' | 'stop';
+  message: string;
+  recovered?: boolean;
+}
 
-  const elements: WebElement[] = [];
-  for (const [role, entries] of byRole) {
-    try {
-      const rawList = await page.getByRole(role).evaluateAll(
-        (domElements: Element[], [data, extractFnStr, config]: [Array<{ name: string; ref: string }>, string, typeof ELEMENT_EXTRACTION_CONFIG]) => {
-          const extract = new Function(`return ${extractFnStr}`)() as (el: Element) => any;
-          const results: any[] = [];
-          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}`);
-    }
-  }
+export interface TestRun {
+  started: boolean;
+  stop(meta?: Record<string, string>): Promise<void>;
+}
 
-  return { ariaSnapshot, elements };
+export interface CaptureOpts {
+  screenshot?: boolean;
 }
 
 export default Explorer;