explorbot 0.0.5 → 0.1.1

package/dist/src/ai/tools.js

@@ -274,7 +274,7 @@ export function createCodeceptJSTools(explorer, task) {
         I.selectOption({"role":"combobox","text":"Category"}, 'Technology')
 
         Do not submit form - use verify() first to check fields were filled correctly, then click() to submit.
-        Do not use: wait functions, amOnPage, reloadPage, saveScreenshot
+        Do not use: wait functions, amOnPage, reloadPage, saveScreenshot        
       `,
             inputSchema: z.object({
                 codeBlock: z.string().describe('Valid CodeceptJS code starting with I. Can contain multiple commands separated by newlines.'),
@@ -301,7 +301,11 @@ export function createCodeceptJSTools(explorer, task) {
                     const previousState = ActionResult.fromState(stateManager.getCurrentState());
                     const formLocator = codeLines[0] || 'form';
                     const action = explorer.createAction();
+                    const wasInIframe = await explorer.isInsideIframe();
                     await action.attempt(codeBlock, explanation);
+                    if (action.lastError && !wasInIframe && (await explorer.isInsideIframe())) {
+                        await explorer.switchToMainFrame();
+                    }
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, formLocator);
                     if (action.lastError) {
                         const message = action.lastError ? String(action.lastError) : 'Unknown error';
@@ -331,7 +335,7 @@ export function createCodeceptJSTools(explorer, task) {
                         message: `Form completed successfully with ${lines.length} commands.`,
                         commandsExecuted: lines.length,
                         code: codeBlock,
-                        suggestion: 'Verify the form was filled in correctly using see() tool. Submit if needed by using click() tool.',
+                        suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
                     });
                 }
                 catch (error) {

package/dist/src/commands/add-rule-command.js

@@ -5,8 +5,7 @@ import React from 'react';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
 export class AddRuleCommand extends BaseCommand {
-    name = 'rules:add';
-    aliases = ['add-rule'];
+    name = 'add-rule';
     description = 'Create a rule file for an agent';
     suggestions = ['/add-rule researcher check-tooltips'];
     async execute(args) {

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

@@ -1,3 +1,4 @@
+import { Command } from 'commander';
 export class BaseCommand {
     aliases = [];
     options = [];
@@ -10,4 +11,15 @@ export class BaseCommand {
     matches(commandName) {
         return this.name === commandName || this.aliases.includes(commandName);
     }
+    parseArgs(args) {
+        const cmd = new Command();
+        cmd.exitOverride();
+        for (const opt of this.options) {
+            cmd.option(opt.flags, opt.description);
+        }
+        cmd.argument('[args...]');
+        const argv = (args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || []).map((s) => s.replace(/^["']|["']$/g, ''));
+        cmd.parse(argv, { from: 'user' });
+        return { opts: cmd.opts(), args: cmd.args };
+    }
 }

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

@@ -8,13 +8,20 @@ export class ContextCommand extends BaseCommand {
     name = 'context';
     description = 'Show page context summary (URL, headings, experience, knowledge, ARIA, HTML, research)';
     suggestions = ['context:aria', 'context:html', 'context:knowledge', 'context:experience', 'context:data'];
+    options = [
+        { flags: '--visual', description: 'Include annotated screenshot' },
+        { flags: '--screenshot', description: 'Include annotated screenshot' },
+        { flags: '--full', description: 'Show full context with HTML' },
+        { flags: '--attached', description: 'Show attached context mode' },
+    ];
     async execute(args) {
         const explorer = this.explorBot.getExplorer();
         const state = explorer.getStateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to show context for');
         }
-        const isVisual = args.includes('--visual') || args.includes('--screenshot');
+        const { opts } = this.parseArgs(args);
+        const isVisual = !!(opts.visual || opts.screenshot);
         await explorer.annotateElements();
         if (isVisual) {
             const cachedResearch = Researcher.getCachedResearch(state);
@@ -25,10 +32,10 @@ export class ContextCommand extends BaseCommand {
         const experienceTracker = explorer.getStateManager().getExperienceTracker();
         const knowledgeTracker = this.explorBot.getKnowledgeTracker();
         let mode = 'compact';
-        if (args.includes('--full')) {
+        if (opts.full) {
             mode = 'full';
         }
-        else if (args.includes('--attached')) {
+        else if (opts.attached) {
             mode = 'attached';
         }
         const contextData = {

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

@@ -2,7 +2,6 @@ import { BaseCommand } from './base-command.js';
 export class DrillCommand extends BaseCommand {
     name = 'drill';
     description = 'Drill all components on current page to learn interactions';
-    aliases = ['bosun'];
     suggestions = ['/research - to see UI map first', '/navigate <page> - to go to another page'];
     async execute(args) {
         const knowledgePath = this.parseKnowledgeArg(args);

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

@@ -1,6 +1,8 @@
+import { existsSync, readdirSync } from 'node:fs';
 import figureSet from 'figures';
 import path from 'node:path';
 import { getStyles } from '../ai/planner/styles.js';
+import { ConfigParser } from "../config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { jsonToTable } from '../utils/markdown-parser.js';
 import { tag } from '../utils/logger.js';
@@ -14,12 +16,11 @@ export class ExploreCommand extends BaseCommand {
     testsRun = 0;
     completedPlans = [];
     async execute(args) {
-        const maxTestsMatch = args.match(/--max-tests\s+(\d+)/);
-        if (maxTestsMatch) {
-            this.maxTests = Number.parseInt(maxTestsMatch[1], 10);
-            args = args.replace(/--max-tests\s+\d+/, '').trim();
+        const { opts, args: remaining } = this.parseArgs(args);
+        if (opts.maxTests) {
+            this.maxTests = Number.parseInt(opts.maxTests, 10);
         }
-        const feature = args.trim() || undefined;
+        const feature = remaining.join(' ') || undefined;
         const mainUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url;
         await this.runAllStyles(mainUrl, feature);
         const mainPlan = this.explorBot.getCurrentPlan();
@@ -56,6 +57,7 @@ export class ExploreCommand extends BaseCommand {
             await this.explorBot.visit(mainUrl);
         const savedPath = this.explorBot.savePlans(this.completedPlans);
         this.printResults(savedPath);
+        this.printRerunSuggestions();
     }
     async runAllStyles(pageUrl, feature, parentPlan, completedPlans) {
         let fresh = true;
@@ -72,7 +74,7 @@ export class ExploreCommand extends BaseCommand {
         }
     }
     printResults(savedPath) {
-        const allTests = this.completedPlans.flatMap((plan) => plan.tests.filter((t) => t.status !== 'pending').map((test) => ({ test, planTitle: plan.title })));
+        const allTests = this.completedPlans.flatMap((plan) => plan.tests.filter((t) => t.startTime != null).map((test) => ({ test, planTitle: plan.title })));
         if (allTests.length === 0)
             return;
         const hasSubPages = this.completedPlans.length > 1;
@@ -107,6 +109,19 @@ export class ExploreCommand extends BaseCommand {
             tag('info').log(`Re-run tests: ${getCliName()} test ${relativePath} <index>`);
         }
     }
+    printRerunSuggestions() {
+        const testsDir = ConfigParser.getInstance().getTestsDir();
+        if (!existsSync(testsDir))
+            return;
+        const testFiles = readdirSync(testsDir).filter((f) => f.endsWith('.js'));
+        if (testFiles.length === 0)
+            return;
+        for (const file of testFiles) {
+            tag('info').log(`Generated: ${file}`);
+        }
+        tag('info').log(`List tests: ${getCliName()} runs`);
+        tag('info').log(`Re-run with healing: ${getCliName()} rerun <filename> [index]`);
+    }
     isLimitReached() {
         return this.maxTests != null && this.testsRun >= this.maxTests;
     }

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

@@ -16,7 +16,14 @@ export class FreesailCommand extends BaseCommand {
         { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
     ];
     async execute(args) {
-        const { strategy, scope, maxTests } = parseArgs(args);
+        const { opts } = this.parseArgs(args);
+        let strategy;
+        if (opts.deep)
+            strategy = 'deep';
+        if (opts.shallow)
+            strategy = 'shallow';
+        const scope = opts.scope;
+        const maxTests = opts.maxTests ? Number.parseInt(opts.maxTests, 10) : undefined;
         await this.explorBot.visitInitialState();
         let testsRun = 0;
         await loop(async (ctx) => {
@@ -60,24 +67,3 @@ export class FreesailCommand extends BaseCommand {
         }, { maxAttempts: Number.POSITIVE_INFINITY });
     }
 }
-function parseArgs(args) {
-    const parts = args.trim().split(/\s+/);
-    let strategy;
-    let scope;
-    let maxTests;
-    for (let i = 0; i < parts.length; i++) {
-        if (parts[i] === '--deep')
-            strategy = 'deep';
-        if (parts[i] === '--shallow')
-            strategy = 'shallow';
-        if (parts[i] === '--scope' && parts[i + 1]) {
-            scope = parts[i + 1];
-            i++;
-        }
-        if (parts[i] === '--max-tests' && parts[i + 1]) {
-            maxTests = Number.parseInt(parts[i + 1], 10);
-            i++;
-        }
-    }
-    return { strategy, scope, maxTests };
-}

package/dist/src/commands/index.js

@@ -22,7 +22,9 @@ import { PlanEditCommand } from './plan-edit-command.js';
 import { PlanLoadCommand } from './plan-load-command.js';
 import { PlanReloadCommand } from './plan-reload-command.js';
 import { PlanSaveCommand } from './plan-save-command.js';
+import { RerunCommand } from './rerun-command.js';
 import { ResearchCommand } from './research-command.js';
+import { RunsCommand } from './runs-command.js';
 import { StartCommand } from './start-command.js';
 import { StatusCommand } from "./status-command.js";
 import { TestCommand } from './test-command.js';
@@ -53,6 +55,8 @@ const commandClasses = [
     ContextExperienceCommand,
     ContextDataCommand,
     TestCommand,
+    RunsCommand,
+    RerunCommand,
     StatusCommand,
     DebugCommand,
     ExitCommand,

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

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import { log, tag } from '../utils/logger.js';
 import dedent from 'dedent';
+import chalk from 'chalk';
 import { getCliName } from "../utils/cli-name.js";
 const DEFAULT_CONFIG_TEMPLATE = `import { createOpenRouter } from '@openrouter/ai-sdk-provider';
 // import { '<your provider here>' } from '<your provider package here>';
@@ -21,11 +22,11 @@ const config = {
 
   ai: {
     // fast model with tool calling capabilities
-    model: openrouter('<your base model here>'),
+    model: openrouter('openai/gpt-oss-20b:nitro'),
     // vision model for screenshot analysis
-    visionModel: openrouter('<your vision model here>'),
+    visionModel: openrouter('meta-llama/llama-4-scout-17b-16e-instruct'),
     // agentic model for decision making
-    agenticModel: openrouter('<your agentic model here>'),
+    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
   },
 };
 
@@ -95,9 +96,10 @@ export function runInitCommand(options) {
         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(`${getCliName()} learn * 'to aurhorize use these credentials: admin@example.com / secret123'`);
+        tag('substep').log(chalk.yellow(`${getCliName()} learn * 'to aurhorize 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(`${getCliName()} start /dashboard`);
+        tag('substep').log(chalk.yellow(`${getCliName()} start /dashboard`));
         if (!existsSync('./output')) {
             mkdirSync('./output', { recursive: true });
             log('Created directory: ./output');

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

@@ -5,7 +5,8 @@ export class PathCommand extends BaseCommand {
     description = 'Display ASCII graph of navigation paths during the session';
     options = [{ flags: '--links', description: 'Show outgoing links from each page' }];
     async execute(args) {
-        const showLinks = args.includes('--links');
+        const { opts } = this.parseArgs(args);
+        const showLinks = !!opts.links;
         const stateManager = this.explorBot.getExplorer().getStateManager();
         const history = stateManager.getStateHistory();
         if (history.length === 0) {

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

@@ -1,3 +1,6 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import figureSet from 'figures';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
 export class PlanCommand extends BaseCommand {
@@ -8,28 +11,52 @@ export class PlanCommand extends BaseCommand {
         { flags: '--fresh', description: 'Regenerate plan from scratch' },
         { flags: '--clear', description: 'Clear plan before regenerating' },
         { flags: '--style <name>', description: 'Planning style (normal, curious, psycho, performer)' },
+        { flags: '--focus <feature>', description: 'Focus area for test planning' },
     ];
     async execute(args) {
-        const clear = args.includes('--clear');
-        const fresh = args.includes('--fresh') || clear;
-        const styleMatch = args.match(/--style\s+(\S+)/);
-        const style = styleMatch?.[1];
-        const focus = args
-            .replace('--clear', '')
-            .replace('--fresh', '')
-            .replace(/--style\s+\S+/, '')
-            .trim();
-        if (clear) {
+        const { opts, args: remaining } = this.parseArgs(args);
+        const focus = opts.focus || remaining.join(' ') || undefined;
+        if (opts.clear) {
             this.explorBot.clearPlan();
             tag('success').log('Plan cleared');
         }
         if (focus) {
             tag('info').log(`Planning focus: ${focus}`);
         }
-        await this.explorBot.plan(focus || undefined, { fresh, style });
+        await this.explorBot.plan(focus, { fresh: !!(opts.fresh || opts.clear), style: opts.style });
         const plan = this.explorBot.getCurrentPlan();
         if (!plan?.tests.length) {
             throw new Error('No test scenarios in the current plan.');
         }
+        this.printPlanSummary();
+        this.updateSuggestions();
+    }
+    printPlanSummary() {
+        const suite = this.explorBot.getSuite();
+        const plan = this.explorBot.getCurrentPlan();
+        if (suite && suite.automatedTestCount > 0) {
+            const names = suite.getAutomatedTestNames();
+            console.log(`\n${chalk.bold.cyan(`Already implemented (${names.length} tests)`)}`);
+            for (let i = 0; i < names.length; i++) {
+                console.log(`  ${chalk.dim(`${i + 1}.`)} ${chalk.green(figureSet.pointer)} ${names[i]}`);
+            }
+        }
+        if (plan?.tests.length) {
+            console.log(`\n${chalk.bold.cyan(`New test scenarios (${plan.tests.length})`)}`);
+            for (let i = 0; i < plan.tests.length; i++) {
+                const t = plan.tests[i];
+                console.log(`  ${chalk.dim(`${i + 1}.`)} ${chalk.green(figureSet.pointer)} ${t.scenario} ${chalk.dim(`[${t.priority}]`)}`);
+            }
+        }
+    }
+    updateSuggestions() {
+        this.suggestions = ['/test - to launch first test', '/test * - to launch all tests'];
+        const suite = this.explorBot.getSuite();
+        if (suite && suite.automatedTestCount > 0) {
+            for (const f of suite.getAutomatedTestFiles()) {
+                this.suggestions.push(`/rerun ${path.relative(process.cwd(), f)} - re-run automated tests`);
+            }
+        }
+        this.suggestions.push('Edit the plan in file and call /plan:reload to update it');
     }
 }

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

@@ -0,0 +1,42 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ConfigParser } from "../config.js";
+import { tag } from "../utils/logger.js";
+import { BaseCommand } from './base-command.js';
+export class RerunCommand extends BaseCommand {
+    name = 'rerun';
+    description = 'Re-run generated tests with AI auto-healing';
+    tuiEnabled = true;
+    async execute(args) {
+        const { args: remaining } = this.parseArgs(args);
+        const filename = remaining[0];
+        const indexArg = remaining[1];
+        if (!filename) {
+            tag('error').log('Usage: /rerun <filename> [index]');
+            return;
+        }
+        let filePath = resolve(filename);
+        if (!existsSync(filePath)) {
+            filePath = resolve(ConfigParser.getInstance().getTestsDir(), filename);
+        }
+        const testIndices = indexArg ? parseTestIndices(indexArg) : undefined;
+        await this.explorBot.agentRerunner().rerun(filePath, { testIndices });
+    }
+}
+function parseTestIndices(input) {
+    if (input === '*' || input === 'all')
+        return [];
+    const indices = new Set();
+    for (const part of input.split(',')) {
+        const trimmed = part.trim();
+        const range = trimmed.match(/^(\d+)-(\d+)$/);
+        if (range) {
+            for (let i = Number.parseInt(range[1]); i <= Number.parseInt(range[2]); i++)
+                indices.add(i - 1);
+        }
+        else {
+            indices.add(Number.parseInt(trimmed) - 1);
+        }
+    }
+    return [...indices].sort((a, b) => a - b);
+}

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

@@ -6,11 +6,17 @@ export class ResearchCommand extends BaseCommand {
     name = 'research';
     description = 'Research current page or navigate to URI and research. Use --deep to explore interactive elements by clicking them. Use --data to include page data.';
     suggestions = ['/navigate <page> - to go to another page', '/plan <feature> - to plan testing'];
+    options = [
+        { flags: '--data', description: 'Include page data' },
+        { flags: '--deep', description: 'Explore interactive elements by clicking them' },
+        { flags: '--no-fix', description: 'Skip fixing research issues' },
+    ];
     async execute(args) {
-        const includeData = args.includes('--data');
-        const enableDeep = args.includes('--deep');
-        const noFix = args.includes('--no-fix');
-        const target = args.replace('--data', '').replace('--deep', '').replace('--no-fix', '').trim();
+        const { opts, args: remaining } = this.parseArgs(args);
+        const includeData = !!opts.data;
+        const enableDeep = !!opts.deep;
+        const noFix = !!opts.noFix;
+        const target = remaining.join(' ');
         if (target) {
             await this.explorBot.agentNavigator().visit(target);
         }

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

@@ -0,0 +1,22 @@
+import * as codeceptjs from 'codeceptjs';
+import { ConfigParser } from "../config.js";
+import { dryRunTestFile, loadTestSuites, printTestList } from "../utils/test-files.js";
+import { BaseCommand } from './base-command.js';
+export class RunsCommand extends BaseCommand {
+    name = 'runs';
+    description = 'List generated test files and their scenarios';
+    tuiEnabled = true;
+    async execute(args) {
+        if (!this.explorBot.isExploring) {
+            codeceptjs.container.create({ helpers: {} }, {});
+        }
+        const { args: remaining } = this.parseArgs(args);
+        const filePath = remaining[0];
+        if (filePath) {
+            await dryRunTestFile(filePath);
+            return;
+        }
+        const suites = loadTestSuites(ConfigParser.getInstance().getTestsDir());
+        printTestList(suites);
+    }
+}

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

@@ -2,7 +2,6 @@ import { BaseCommand } from './base-command.js';
 import { ExploreCommand } from './explore-command.js';
 export class StartCommand extends BaseCommand {
     name = 'start';
-    aliases = ['sail'];
     description = 'Start web exploration';
     suggestions = ['/navigate <page> - to go to another page', '/research - to analyze', '/plan <feature> - to plan testing'];
     async execute(args) {

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

@@ -24,10 +24,10 @@ export class TestCommand extends BaseCommand {
             toExecute.push(...requirePlan().getPendingTests());
         }
         else if (args.match(/^[\d,\-\s]+$/)) {
-            const pending = requirePlan().getPendingTests();
-            const indices = parseTestIndices(args, pending.length);
+            const visible = requirePlan().tests.filter((t) => t.enabled);
+            const indices = parseTestIndices(args, visible.length);
             for (const idx of indices) {
-                toExecute.push(pending[idx]);
+                toExecute.push(visible[idx]);
             }
         }
         else {

package/dist/src/components/App.js

@@ -206,6 +206,14 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
                 setShowPlanEditor(true);
                 return;
             }
+            if (key.upArrow) {
+                setTaskScrollOffset((prev) => Math.max(0, prev - 1));
+                return;
+            }
+            if (key.downArrow) {
+                setTaskScrollOffset((prev) => prev + 1);
+                return;
+            }
         }
         if (!showInput && !showPlanEditor) {
             if (key.upArrow) {

package/dist/src/config.js

@@ -100,6 +100,9 @@ export class ConfigParser {
     getPlansDir() {
         return outputPath('plans');
     }
+    getTestsDir() {
+        return outputPath('tests');
+    }
     // For testing purposes only
     static resetForTesting() {
         if (ConfigParser.instance) {

package/dist/src/explorbot.js

@@ -14,6 +14,7 @@ import { Planner } from "./ai/planner.js";
 import { AIProvider } from "./ai/provider.js";
 import { Quartermaster } from "./ai/quartermaster.js";
 import { Researcher } from "./ai/researcher.js";
+import { Rerunner } from "./ai/rerunner.js";
 import { Tester } from "./ai/tester.js";
 import { createAgentTools } from "./ai/tools.js";
 import { ConfigParser } from "./config.js";
@@ -84,7 +85,7 @@ export class ExplorBot {
         await this.explorer.openFreshTab();
     }
     getCurrentState() {
-        return this.explorer.getStateManager().getCurrentState();
+        return this.explorer?.getStateManager().getCurrentState() ?? null;
     }
     getExplorer() {
         return this.explorer;
@@ -202,6 +203,21 @@ export class ExplorBot {
             return new Historian(ai, experienceTracker, reporter, explorer.getStateManager());
         }));
     }
+    agentRerunner() {
+        if (!this.agents.rerunner) {
+            this.agents.rerunner = this.createAgent(({ ai, explorer }) => {
+                const researcher = this.agentResearcher();
+                const navigator = this.agentNavigator();
+                const tools = createAgentTools({ explorer, researcher, navigator });
+                return new Rerunner(explorer, ai, tools);
+            });
+            const qm = this.agentQuartermaster();
+            if (qm)
+                this.agents.rerunner.setQuartermaster(qm);
+            this.agents.rerunner.setHistorian(this.agentHistorian());
+        }
+        return this.agents.rerunner;
+    }
     agentBosun() {
         return (this.agents.bosun ||= this.createAgent(({ ai, explorer }) => {
             const researcher = this.agentResearcher();
@@ -243,6 +259,9 @@ export class ExplorBot {
     getCurrentPlan() {
         return this.currentPlan;
     }
+    getSuite() {
+        return this.agentPlanner().getSuite();
+    }
     getPlanFeature() {
         return this.planFeature;
     }

package/dist/src/explorer.js

@@ -15,6 +15,7 @@ import { StateManager } from './state-manager.js';
 import { RequestStore } from "./api/request-store.js";
 import { XhrCapture } from "./api/xhr-capture.js";
 import { createDebug, log, tag } from './utils/logger.js';
+import { WebElement, extractElementData } from "./utils/web-element.js";
 const debugLog = createDebug('explorbot:explorer');
 const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 class Explorer {
@@ -243,19 +244,8 @@ class Explorer {
         return action;
     }
     async annotateElements() {
-        const page = this.playwrightHelper.page;
-        const roles = ['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem'];
-        let idx = 1;
-        for (const role of roles) {
-            const elements = await page.getByRole(role).all();
-            for (const el of elements) {
-                await el.evaluate((node, i) => {
-                    node.setAttribute('data-explorbot-eidx', String(i));
-                }, idx);
-                idx++;
-            }
-        }
-        return idx - 1;
+        const { elements } = await annotatePageElements(this.playwrightHelper.page);
+        return elements;
     }
     async visuallyAnnotateElements(opts) {
         return visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []);
@@ -269,7 +259,7 @@ class Explorer {
             for (const el of elements) {
                 const attr = await el.getAttribute('data-explorbot-eidx');
                 if (attr)
-                    result.push(Number.parseInt(attr, 10));
+                    result.push(attr);
             }
             return result;
         }
@@ -286,8 +276,7 @@ class Explorer {
             const page = this.playwrightHelper.page;
             const base = container ? page.locator(container) : page;
             const el = locator.startsWith('//') ? base.locator(`xpath=${locator}`) : base.locator(locator);
-            const eidx = await el.first().getAttribute('data-explorbot-eidx');
-            return eidx ? Number.parseInt(eidx, 10) : null;
+            return await el.first().getAttribute('data-explorbot-eidx');
         }
         catch (error) {
             if (this.isFatalBrowserError(error)) {
@@ -607,4 +596,58 @@ function toCodeceptjsTest(test) {
     codeceptjsTest.notes = test.getPrintableNotes();
     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({ forAI: true });
+    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]) => {
+                const extract = new Function(`return ${extractFnStr}`)();
+                const results = [];
+                let ariaIdx = 0;
+                for (const el of domElements) {
+                    if (ariaIdx >= data.length)
+                        break;
+                    el.setAttribute('data-explorbot-eidx', data[ariaIdx].ref);
+                    const elData = extract(el);
+                    if (elData)
+                        results.push(elData);
+                    ariaIdx++;
+                }
+                return results;
+            }, [entries, extractElementData.toString()]);
+            for (const raw of rawList) {
+                elements.push(WebElement.fromRawData(raw, role));
+            }
+        }
+        catch {
+            debugLog(`Failed to annotate role=${role}`);
+        }
+    }
+    return { ariaSnapshot, elements };
+}
 export default Explorer;