explorbot 0.3.1 → 0.3.4

package/dist/src/ai/provider.js

@@ -31,6 +31,15 @@ function createHarmonyChannelFallbackTool() {
     });
 }
 let telemetryRegistered = false;
+let beforeExitFlushHooked = false;
+let activeOtelSdk = null;
+export async function flushTelemetry() {
+    const sdk = activeOtelSdk;
+    activeOtelSdk = null;
+    if (!sdk)
+        return;
+    await sdk.shutdown().catch((error) => debugLog(`Telemetry flush failed: ${error instanceof Error ? error.message : error}`));
+}
 const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
 function extractCachedTokens(usage) {
     if (!usage)
@@ -105,6 +114,9 @@ export class Provider {
             throw new AiError(`AI connection failed: ${error.message}`);
         }
     }
+    async stop() {
+        await flushTelemetry();
+    }
     getModelForAgent(agentName) {
         if (!agentName) {
             return this.config.model;
@@ -251,7 +263,12 @@ export class Provider {
             spanProcessors: [processor],
             instrumentations: [],
         });
+        activeOtelSdk = this.otelSdk;
         void this.otelSdk.start();
+        if (!beforeExitFlushHooked) {
+            process.on('beforeExit', () => void flushTelemetry());
+            beforeExitFlushHooked = true;
+        }
         if (!telemetryRegistered) {
             registerTelemetry(new OpenTelemetry());
             telemetryRegistered = true;
@@ -293,7 +310,7 @@ export class Provider {
     }
     async invokeConversation(conversation, tools, options = {}) {
         const response = tools ? await this.generateWithTools(conversation.messages, conversation.model, tools, options) : await this.chat(conversation.messages, conversation.model, options);
-        const responseMessages = response.response?.messages || [];
+        const responseMessages = response.responseMessages || [];
         if (responseMessages.length > 0) {
             conversation.messages.push(...responseMessages);
             tag('debug').log('Added', responseMessages.length, 'messages from response');

package/dist/src/ai/researcher/deep-analysis.js

@@ -1,14 +1,16 @@
 import dedent from 'dedent';
 import { ActionResult } from '../../action-result.js';
 import { executionController } from "../../execution-controller.js";
-import { detectFocusArea, diffAriaSnapshots } from "../../utils/aria.js";
+import { diffAriaSnapshots } from "../../utils/aria.js";
 import { extractCodeBlocks } from "../../utils/code-extractor.js";
 import { tag } from '../../utils/logger.js';
 import { mdq } from "../../utils/markdown-query.js";
+import { truncate } from "../../utils/strings.js";
 import { getCachedResearch, getPreviousResearch, saveResearch } from "./cache.js";
 import { debugLog } from "./mixin.js";
 import { parseResearchSections } from "./parser.js";
 const DEFAULT_MAX_EXPANDABLE_CLICKS = 10;
+const MAX_HTML_DIFF_CHARS = 20_000;
 export function WithDeepAnalysis(Base) {
     return class extends Base {
         async performDeepAnalysis(state, result) {
@@ -60,7 +62,7 @@ export function WithDeepAnalysis(Base) {
             this._appendExtendedResearch(result, expandedSections, navigationLinks);
         }
         async researchOverlay(current, previous, pageStateHash) {
-            const focusArea = detectFocusArea(current.ariaSnapshot);
+            const focusArea = current.overlay;
             if (!focusArea.detected || !focusArea.name)
                 return null;
             if (focusArea.type !== 'dialog' && focusArea.type !== 'modal')
@@ -430,6 +432,8 @@ export function WithDeepAnalysis(Base) {
 
         `;
             }
+            const cleanedParts = await diff.cleanedHtmlParts();
+            const htmlChanges = truncate(cleanedParts.map((p) => `[Container: ${p.container}]\n${p.subtree}`).join('\n\n'), MAX_HTML_DIFF_CHARS);
             const prompt = dedent `
         ${intro}
         Analyze the changes and produce a UI map section.
@@ -438,7 +442,7 @@ export function WithDeepAnalysis(Base) {
         ${diff.ariaChanged || 'none'}
 
         HTML changes:
-        ${diff.htmlParts.map((p) => `[Container: ${p.container}]\n${p.subtree}`).join('\n\n') || 'none'}
+        ${htmlChanges || 'none'}
         ${alreadyHint}
 
         Respond with a SINGLE section in this format:

package/dist/src/ai/researcher/sections.js

@@ -93,7 +93,6 @@ export function WithSections(Base) {
         - Do not copy global toolbar, navigation, list, or detail elements into this section unless they are descendants of this section container.
         - Every element with eidx inside this section's container MUST appear in the table.
         - Every row needs CSS; ARIA may be "-" for icon-only buttons.
-        - ARIA locator JSON uses keys "role" and "text" (NOT "name").
         - Elements marked data-explorbot-hit="covered" or "offscreen" are not directly actionable; describe the covering or focused UI first.
         - In split-pane pages, entity detail panels are active detail context; include close/back/pin controls in the detail panel section when present.
         </rules>

package/dist/src/ai/researcher.js

@@ -345,7 +345,6 @@ export class Researcher extends ResearcherBase {
       - If an element has data-explorbot-hit="covered" or "offscreen", do not present it as directly actionable. Prefer the overlay, drawer, dialog, or focused section covering it, and mention what must be dismissed or revealed first.
       - Every element with an eidx attribute MUST appear in exactly one matching UI map section — describe icon-only buttons by their visual role.
       - Every UI map row needs a CSS selector; ARIA may be "-" for icon-only buttons, CSS must never be "-".
-      - ARIA locator JSON uses keys "role" and "text" (NOT "name").
       - Mark elements with likely hover interactions (title, aria-describedby, menu items with submenus) as "(hover)".
       </rules>
 

package/dist/src/ai/rules.js

@@ -67,7 +67,6 @@ const locatorStrategyRule = dedent `
 
   <bad_aria_locator_example>
   { "role": "button", "text": "" }  // INVALID - empty text is useless, use "-" instead
-  { "role": "button", "name": "Save" }  // WRONG key - use "text", not "name"
   </bad_aria_locator_example>
 
   NEVER include \`eidx\` attribute in any locator (ARIA, CSS, XPath). It is an internal annotation.

package/dist/src/ai/tester.d.ts

@@ -33,6 +33,7 @@ export declare class Tester extends TaskAgent implements Agent {
     lastAnalyzedStateHash: string | null;
     stalledIterations: number;
     readonly MAX_STALLED_ITERATIONS = 3;
+    skipResearch: (err: Error) => string;
     constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any);
     getNavigator(): Navigator;
     setPilot(pilot: Pilot): void;

package/dist/src/ai/tester.js

@@ -9,7 +9,6 @@ import { Observability } from "../observability.js";
 import { normalizeUrl } from "../state-manager.js";
 import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
-import { detectFocusArea } from "../utils/aria.js";
 import { ErrorPageError, isErrorPage } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
@@ -52,6 +51,12 @@ export class Tester extends TaskAgent {
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
     MAX_STALLED_ITERATIONS = 3;
+    skipResearch = (err) => {
+        if (err.name === 'AbortError')
+            throw err;
+        tag('warning').log(`Research skipped: ${err.message}`);
+        return '';
+    };
     constructor(deps, researcher, navigator, agentTools) {
         super(deps);
         this.requestStore = deps.requestStore;
@@ -466,7 +471,7 @@ export class Tester extends TaskAgent {
         this.previousUrl = currentUrl;
         this.previousStateHash = currentStateHash;
         let context = '';
-        const focusArea = detectFocusArea(currentState.ariaSnapshot);
+        const focusArea = currentState.overlay;
         const focusedElement = currentState.focusedElement;
         if (focusedElement) {
             const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
@@ -513,14 +518,7 @@ export class Tester extends TaskAgent {
             const alreadySeenUiMap = this.seenUiMapUrls.has(currentUrl);
             let research = '';
             if (!alreadySeenUiMap) {
-                try {
-                    research = await this.researcher.research(currentState);
-                }
-                catch (err) {
-                    if (!(err instanceof ErrorPageError))
-                        throw err;
-                    tag('warning').log(`Research skipped: ${err.message}`);
-                }
+                research = await this.researcher.research(currentState).catch(this.skipResearch);
             }
             this.pageStateHash = currentStateHash;
             this.pageActionResult = currentState;
@@ -560,7 +558,7 @@ export class Tester extends TaskAgent {
             return context;
         }
         if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
-            const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash);
+            const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash).catch(this.skipResearch);
             if (overlaySection) {
                 context += dedent `
 

package/dist/src/ai/tools.d.ts

@@ -1,3 +1,4 @@
+import type { ExecutedStep } from '../action.js';
 import { ActionResult, type PageDiff } from '../action-result.js';
 import { type ExperienceTracker } from '../experience-tracker.js';
 import { type Task } from '../test-plan.js';
@@ -62,6 +63,7 @@ export declare function successToolResult(action: string, data?: Record<string,
 }): Record<string, any>;
 export declare function isMajorPageChange(pageDiff: PageDiff): boolean;
 export declare function hasFailedRequest(pageDiff: PageDiff): boolean;
+export declare function formatExecutedSteps(steps: ExecutedStep[], requestedCount?: number): string;
 export declare function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null): Promise<Record<string, any>>;
 export declare function withdrawVisionTools(tools: Record<string, any>): void;
 export declare function clickFailureSuggestion(attempts: Array<{

package/dist/src/ai/tools.js

@@ -343,16 +343,17 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     if (action.lastError) {
                         const message = errorText(action.lastError);
                         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
-                        let formSuggestion = 'Look into error message and identify which commands passed and which failed. Continue execution using step-by-step approach using click() and form() tools.';
+                        let formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
                         if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
                             const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
                             if (disambiguated) {
                                 formSuggestion = `Multiple elements matched. Add step.opts({ elementIndex: ${disambiguated.position} }) to the failing command. Fallback locator: ${disambiguated.xpath}`;
                             }
                         }
-                        return failedToolResult('form', `Form execution FAILED! ${message}`, {
+                        return failedToolResult('form', `Form execution FAILED! ${message}\n${formatExecutedSteps(action.executedSteps, codeLines.length)}`, {
                             ...toolResult,
                             code: codeBlock,
+                            attempts: action.executedSteps,
                             suggestion: formSuggestion,
                         }, action.lastError);
                     }
@@ -369,6 +370,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                         ...toolResult,
                         message: `Form completed successfully with ${lines.length} commands.`,
                         commandsExecuted: lines.length,
+                        attempts: action.executedSteps,
                         code: codeBlock,
                         suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
                     }, action);
@@ -698,18 +700,24 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                     const actionResult = ActionResult.fromState(currentState);
                     const experience = renderExperienceRecipes(explorer.activeTest?.getAppliedExperience(actionResult) ?? []);
                     const success = await navigator.resolveState(instruction, actionResult, { experience });
+                    const attempts = navigator.executedSteps;
+                    let stepReport = '';
+                    if (attempts.length)
+                        stepReport = `\n${formatExecutedSteps(attempts)}`;
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, instruction);
                     if (success) {
                         return successToolResult('interact', {
                             ...toolResult,
-                            message: `Successfully executed: ${instruction}`,
+                            message: `Successfully executed: ${instruction}${stepReport}`,
+                            attempts,
                         });
                     }
                     let reason = '';
                     if (navigator.lastFailureReason)
                         reason = `: ${navigator.lastFailureReason}`;
-                    return failedToolResult('interact', `Failed to execute: ${instruction}${reason}`, {
+                    return failedToolResult('interact', `Failed to execute: ${instruction}${reason}${stepReport}`, {
                         ...toolResult,
+                        attempts,
                         suggestion: 'The action could not be completed. Try a different instruction or use more specific element descriptions.',
                     });
                 }
@@ -1071,6 +1079,15 @@ export function isMajorPageChange(pageDiff) {
 export function hasFailedRequest(pageDiff) {
     return (pageDiff.requests ?? []).some((request) => request.status >= 400);
 }
+export function formatExecutedSteps(steps, requestedCount = steps.length) {
+    if (!steps.length)
+        return `No command ran of ${requestedCount} requested.`;
+    const lines = steps.map((step) => `  ${step.success ? 'OK' : 'FAILED'} ${step.command}`);
+    const notRun = requestedCount - steps.length;
+    if (notRun > 0)
+        lines.push(`  NOT RUN ${notRun} more`);
+    return lines.join('\n');
+}
 function hasObservablePageChange(data) {
     if (!data?.pageDiff)
         return false;

package/dist/src/commands/exit-command.js

@@ -9,7 +9,7 @@ export class ExitCommand extends BaseCommand {
     aliases = ['quit'];
     async execute(_args) {
         await this.explorBot.printSessionAnalysis();
-        await this.explorBot.getExplorer().stop();
+        await this.explorBot.stop();
         if (Stats.hasActivity()) {
             await new Promise((resolve) => {
                 const { unmount } = render(React.createElement(StatusPane, {

package/dist/src/commands/init-command.js

@@ -1,15 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
-import dedent from 'dedent';
 import { ConfigParser, PROVIDERS } from "../config.js";
 import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from "../global-config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { log, tag } from '../utils/logger.js';
 import { relativeToCwd } from "../utils/next-steps.js";
-function defaultConfigTemplate() {
+function defaultConfigTemplate(provider, esm) {
+    let moduleExport = 'module.exports = config;';
+    if (esm)
+        moduleExport = 'export default config;';
     return `// 'provider/model-id' uses a bundled provider.
-// It is also possible to import provider as a module from Vercel AI SDK.  
+// It is also possible to import provider as a module from Vercel AI SDK.
 // https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 
 const config = {
@@ -19,7 +21,7 @@ const config = {
   },
 
   ai: {
-${modelLines('openrouter')}
+${modelLines(provider)}
   },
 
   reporter: {
@@ -32,16 +34,17 @@ ${modelLines('openrouter')}
   },
 };
 
-export default config;
+${moduleExport}
 `;
 }
-const DEFAULT_ENV_TEMPLATE = dedent `
-# AI provider API keys
-OPENROUTER_API_KEY=
-
-# OPENAI_API_KEY=
-# ANTHROPIC_API_KEY=
-# GROQ_API_KEY=
+function envTemplate(provider) {
+    const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
+        if (name === provider)
+            return `${envKey}=`;
+        return `# ${envKey}=`;
+    });
+    return `# AI provider API keys
+${keyLines.join('\n')}
 
 # Langfuse Tracing
 LANGFUSE_SECRET_KEY=
@@ -49,10 +52,11 @@ LANGFUSE_PUBLIC_KEY=
 LANGFUSE_BASE_URL=
 
 # Testomat.io API key to publish run results
-TESTOMATIO=
-`;
+TESTOMATIO=`;
+}
 export async function runInit(options) {
-    if (options.global || options.provider) {
+    const localRequested = !!(options.configPath || options.path);
+    if (options.global || (options.provider && !localRequested)) {
         await runGlobalInit(options);
         return;
     }
@@ -61,8 +65,12 @@ export async function runInit(options) {
         return;
     }
     const choice = await renderInitWizard('choose');
-    if (choice === 'local')
-        runInitCommand(options);
+    if (choice !== 'local')
+        return;
+    const provider = await renderLocalProviderWizard();
+    if (!provider)
+        return;
+    runInitCommand({ ...options, provider });
 }
 export function writeGlobalConfig(provider, apiKey) {
     if (!PROVIDERS[provider]) {
@@ -87,7 +95,7 @@ export function writeGlobalConfig(provider, apiKey) {
     tag('substep').log(chalk.yellow(`${getCliName()} sites`));
 }
 export function runInitCommand(options) {
-    const configPath = options.configPath ?? './explorbot.config.js';
+    const provider = options.provider || 'openrouter';
     const force = options.force ?? false;
     const customPath = options.path;
     const originalCwd = process.cwd();
@@ -100,13 +108,15 @@ export function runInitCommand(options) {
         process.chdir(dir);
         log(`Working in directory: ${relativeToCwd(dir)}`);
     }
+    const configName = 'explorbot.config.js';
+    const configPath = options.configPath ?? `./${configName}`;
     try {
         let outPath = resolve(configPath);
         if (existsSync(outPath) && statSync(outPath).isDirectory()) {
-            outPath = join(outPath, 'explorbot.config.js');
+            outPath = join(outPath, configName);
         }
         else if (!extname(outPath)) {
-            outPath = join(outPath, 'explorbot.config.js');
+            outPath = join(outPath, configName);
         }
         const dir = dirname(outPath);
         if (!existsSync(dir)) {
@@ -118,23 +128,28 @@ export function runInitCommand(options) {
             log('Use --force to overwrite existing file');
             process.exit(1);
         }
-        writeFileSync(outPath, defaultConfigTemplate(), 'utf8');
+        const esm = extname(outPath) !== '.js' || isModuleProject(dirname(outPath));
+        writeFileSync(outPath, defaultConfigTemplate(provider, esm), 'utf8');
         log(`Created config file: ${relativeToCwd(outPath)}`);
         const envPath = resolve(process.cwd(), '.env');
         if (!existsSync(envPath)) {
-            writeFileSync(envPath, `${DEFAULT_ENV_TEMPLATE}\n`, 'utf8');
+            writeFileSync(envPath, `${envTemplate(provider)}\n`, 'utf8');
             log(`Created env file: ${relativeToCwd(envPath)}`);
         }
         else {
             log(`Env file already exists: ${relativeToCwd(envPath)}`);
         }
+        const missing = missingRoles(provider);
+        if (missing.length) {
+            tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
+        }
         log('');
         log('Next steps:');
         log('1. Configure AI provider in .env');
         log('2. Set AI models config file');
         log('3. Set web application URL in the config file');
         log('4. Add initial knowledge (how to authorize to the application, etc.)');
-        tag('substep').log(chalk.yellow(`${getCliName()} learn * 'to aurhorize use these credentials: admin@example.com / secret123'`));
+        tag('substep').log(chalk.yellow(`${getCliName()} learn * 'to authorize use these credentials: admin@example.com / secret123'`));
         tag('substep').log('You can use ${env.LOGIN} and ${env.PASSWORD} to reference environment variables.');
         log('5. Launch application on a relative URL');
         tag('substep').log(chalk.yellow(`${getCliName()} start /dashboard`));
@@ -187,6 +202,23 @@ async function renderInitWizard(mode) {
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
+async function renderLocalProviderWizard() {
+    const [{ render }, React, InitWizard] = await Promise.all([import('ink'), import('react'), import('../components/InitWizard.js').then((m) => m.default)]);
+    return new Promise((resolve) => {
+        const finish = (provider) => {
+            unmount();
+            resolve(provider);
+        };
+        const { unmount } = render(React.createElement(InitWizard, {
+            mode: 'local',
+            globalConfigExists: !!findGlobalConfig(),
+            onLocal: () => finish(null),
+            onComplete: () => finish(null),
+            onCancel: () => finish(null),
+            onLocalProvider: (provider) => finish(provider),
+        }), { exitOnCtrlC: false, patchConsole: false });
+    });
+}
 function modelLines(provider) {
     const recommended = ConfigParser.recommendedModels()[provider] || {};
     const roles = [
@@ -216,9 +248,27 @@ ${modelLines(provider)}
   },
 };
 
-export default config;
+module.exports = config;
 `;
 }
+function isModuleProject(configDir) {
+    let currentDir = resolve(configDir);
+    while (true) {
+        const packagePath = join(currentDir, 'package.json');
+        if (existsSync(packagePath)) {
+            try {
+                return JSON.parse(readFileSync(packagePath, 'utf8')).type === 'module';
+            }
+            catch {
+                return false;
+            }
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir)
+            return false;
+        currentDir = parentDir;
+    }
+}
 function missingRoles(provider) {
     const recommended = ConfigParser.recommendedModels()[provider] || {};
     return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);

package/dist/src/components/InitWizard.d.ts

@@ -1,10 +1,11 @@
 import React from 'react';
 interface InitWizardProps {
-    mode: 'choose' | 'global';
+    mode: 'choose' | 'global' | 'local';
     globalConfigExists: boolean;
     onLocal: () => void;
     onComplete: () => void;
     onCancel: () => void;
+    onLocalProvider?: (provider: string) => void;
 }
 declare const InitWizard: React.FC<InitWizardProps>;
 export default InitWizard;

package/dist/src/components/InitWizard.js

@@ -7,7 +7,7 @@ import { ConfigParser, PROVIDERS, createModel } from '../config.js';
 import { globalDir } from '../global-config.js';
 import InputReadline from './InputReadline.js';
 const PROVIDER_NAMES = Object.keys(PROVIDERS);
-const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel }) => {
+const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, onLocalProvider }) => {
     const [step, setStep] = useState(mode === 'choose' ? 'target' : 'provider');
     const [targetIndex, setTargetIndex] = useState(0);
     const [providerIndex, setProviderIndex] = useState(0);
@@ -67,8 +67,12 @@ const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel })
                 setProviderIndex((index) => Math.max(0, index - 1));
             if (key.downArrow)
                 setProviderIndex((index) => Math.min(PROVIDER_NAMES.length - 1, index + 1));
-            if (key.return)
-                setStep('key');
+            if (key.return) {
+                if (mode === 'local')
+                    onLocalProvider?.(provider);
+                else
+                    setStep('key');
+            }
             return;
         }
         if (status)
@@ -121,7 +125,7 @@ const InitWizard = ({ mode, globalConfigExists, onLocal, onComplete, onCancel })
         React.createElement(Box, { marginTop: 1 },
             React.createElement(Text, { dimColor: true },
                 "Config goes to ",
-                globalDir(),
+                mode === 'local' ? 'the current directory' : globalDir(),
                 " | ",
                 step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm',
                 " | Ctrl+C: exit"))));

package/dist/src/explorbot.js

@@ -114,6 +114,7 @@ export class ExplorBot {
     async stop() {
         this.agents.quartermaster?.stop();
         await this.explorer?.stop();
+        await this.provider?.stop();
     }
     async visitInitialState() {
         await this.visit(this.options.from || '/');

package/dist/src/explorer.js

@@ -203,6 +203,7 @@ class Explorer {
         const projectRoot = configParser.getProjectRoot();
         global.output_dir = configParser.getStatesDir();
         global.codecept_dir = projectRoot;
+        global.codeceptjs = codeceptjs;
         configParser.validateConfig(this.config);
         codeceptjs.container.create(this.convertToCodeceptConfig(this.config), {});
     }

package/dist/src/knowledge-tracker.d.ts

@@ -17,7 +17,9 @@ export declare class KnowledgeTracker {
     renderRelevantKnowledge(state: ActionResult): string;
     renderRelevantContext(state: ActionResult): string;
     renderApplicationSpec(state: ActionResult): string;
-    addKnowledge(urlPattern: string, description: string): {
+    addKnowledge(urlPattern: string, description: string, opts?: {
+        replace?: boolean;
+    }): {
         filename: string;
         filePath: string;
         isNewFile: boolean;

package/dist/src/knowledge-tracker.js

@@ -73,7 +73,7 @@ export class KnowledgeTracker {
     renderApplicationSpec(state) {
         return this.applicationSpec?.renderFor(state) || '';
     }
-    addKnowledge(urlPattern, description) {
+    addKnowledge(urlPattern, description, opts) {
         const configParser = ConfigParser.getInstance();
         const configPath = configParser.getConfigPath();
         if (!configPath) {
@@ -102,11 +102,11 @@ export class KnowledgeTracker {
             const existingDescription = parsed.content.trim();
             // Append new knowledge with separator
             let newContent;
-            if (existingDescription) {
-                newContent = `${existingDescription}\n\n---\n\n${description}`;
+            if (opts?.replace || !existingDescription) {
+                newContent = description;
             }
             else {
-                newContent = description;
+                newContent = `${existingDescription}\n\n---\n\n${description}`;
             }
             const fileContent = matter.stringify(newContent, frontmatter);
             writeFileSync(filePath, fileContent, 'utf8');

package/dist/src/state-manager.d.ts

@@ -1,6 +1,7 @@
 import { ActionResult, type FocusedElement } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
+import { Overlay } from './utils/overlay.js';
 export interface Link {
     title: string;
     url: string;
@@ -40,6 +41,7 @@ export interface WebPageState {
     focusedElement?: FocusedElement | null;
     links?: Link[];
     verifications?: Record<string, boolean>;
+    overlay?: Overlay;
 }
 export interface StateTransition {
     /** Previous state (null if this is the first state) */

package/dist/src/state-manager.js

@@ -1,6 +1,6 @@
 import { ActionResult } from './action-result.js';
-import { detectFocusArea } from './utils/aria.js';
 import { createDebug, tag } from './utils/logger.js';
+import { Overlay } from './utils/overlay.js';
 import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 const debugLog = createDebug('explorbot:state');
@@ -114,8 +114,8 @@ export class StateManager {
         return newState;
     }
     hasDialogAppeared(previousState, newState) {
-        const prevFocus = detectFocusArea(previousState?.ariaSnapshot ?? null);
-        const newFocus = detectFocusArea(newState.ariaSnapshot ?? null);
+        const prevFocus = previousState?.overlay ?? Overlay.fromAria(previousState?.ariaSnapshot ?? null);
+        const newFocus = newState.overlay ?? Overlay.fromAria(newState.ariaSnapshot ?? null);
         return !prevFocus.detected && newFocus.detected;
     }
     /**

package/dist/src/utils/aria.js

@@ -569,7 +569,7 @@ export function parseAriaLocator(ariaStr) {
     const trimmed = ariaStr.trim();
     if (trimmed === '-' || trimmed === '' || trimmed === '"-"')
         return null;
-    const match = trimmed.match(/\{\s*["']?role["']?\s*:\s*['"]([^'"]+)['"]\s*,\s*["']?text["']?\s*:\s*['"]([^'"]*)['"]\s*\}/);
+    const match = trimmed.match(/\{\s*["']?role["']?\s*:\s*['"]([^'"]+)['"]\s*,\s*["']?(?:text|name)["']?\s*:\s*['"]([^'"]*)['"]\s*\}/);
     if (!match)
         return null;
     return { role: match[1], text: match[2] };

package/dist/src/utils/html.d.ts

@@ -14,7 +14,6 @@ export declare const HTML_SELECTORS: {
     readonly interactiveControl: "button, a[href], input, select, textarea, [role=\"button\"], [role=\"link\"], [role=\"checkbox\"], [role=\"radio\"], [role=\"switch\"], [role=\"tab\"], [role=\"menuitem\"]";
     readonly labelLike: "h1, h2, h3, h4, h5, h6, legend, caption, label, [role=\"heading\"], [class*=\"title\"], [class*=\"label\"], [class*=\"header\"], [class*=\"name\"]";
     readonly semanticContextContainer: "section, article, form, fieldset, li, tr, td, th, [role=\"group\"], [role=\"tabpanel\"], [role=\"region\"], [class*=\"card\"], [class*=\"panel\"], [class*=\"item\"], [class*=\"usage\"], [class*=\"group\"]";
-    readonly semanticOverlays: readonly ["[role=\"dialog\"]", "[role=\"listbox\"]", "[role=\"menu\"]", "[role=\"tooltip\"]:not([style*=\"display: none\"]):not([style*=\"visibility: hidden\"])"];
 };
 export declare const HTML_VISIBILITY_LIMITS: {
     readonly maxViewportOverlayRatio: 0.95;
@@ -67,7 +66,9 @@ export type VisibleOverlayExtractionConfig = {
     interactiveContentSelector: string;
     limits: typeof HTML_EXTRACTION_LIMITS;
     overlaySelectors: readonly string[];
+    overlaySemanticSelector: string;
     visibilityLimits: typeof HTML_VISIBILITY_LIMITS;
+    geometryFallback?: boolean;
 };
 export type ComponentScopeExtractionConfig = {
     eidxAttr: string;