explorbot 0.0.5 → 0.1.0

package/bin/explorbot-cli.ts

@@ -128,10 +128,11 @@ addCommonOptions(program.command('explore <path>').description('Start web explor
   }
 });
 
-addCommonOptions(program.command('plan <path> [feature]').description('Generate test plan for a page and exit'))
+addCommonOptions(program.command('plan <path>').description('Generate test plan for a page and exit'))
   .option('-a, --append', 'Add tests to existing plan file')
   .option('--style <style>', 'Planning style: normal, curious, psycho')
-  .action(async (planPath, feature, options) => {
+  .option('--focus <feature>', 'Focus area for test planning')
+  .action(async (planPath, options) => {
     try {
       const explorBot = new ExplorBot(buildExplorBotOptions(planPath, options));
       await explorBot.start();
@@ -146,7 +147,7 @@ addCommonOptions(program.command('plan <path> [feature]').description('Generate
         }
       }
 
-      await explorBot.plan(feature || undefined, {
+      await explorBot.plan(options.focus || undefined, {
         fresh: !options.append,
         style: options.style,
       });

package/dist/bin/explorbot-cli.js

@@ -102,10 +102,11 @@ addCommonOptions(program.command('explore <path>').description('Start web explor
         await showStatsAndExit(1);
     }
 });
-addCommonOptions(program.command('plan <path> [feature]').description('Generate test plan for a page and exit'))
+addCommonOptions(program.command('plan <path>').description('Generate test plan for a page and exit'))
     .option('-a, --append', 'Add tests to existing plan file')
     .option('--style <style>', 'Planning style: normal, curious, psycho')
-    .action(async (planPath, feature, options) => {
+    .option('--focus <feature>', 'Focus area for test planning')
+    .action(async (planPath, options) => {
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(planPath, options));
         await explorBot.start();
@@ -117,7 +118,7 @@ addCommonOptions(program.command('plan <path> [feature]').description('Generate
                 explorBot.loadPlan(existingPlanPath);
             }
         }
-        await explorBot.plan(feature || undefined, {
+        await explorBot.plan(options.focus || undefined, {
             fresh: !options.append,
             style: options.style,
         });

package/dist/src/action.js

@@ -50,7 +50,7 @@ class Action {
             return undefined;
         }
     }
-    async capturePageState({ includeScreenshot = false } = {}) {
+    async capturePageState({ includeScreenshot = false, ariaSnapshot: preCapuredAria } = {}) {
         try {
             const currentState = this.stateManager.getCurrentState();
             const stateHash = currentState?.hash || 'screenshot';
@@ -90,20 +90,23 @@ class Action {
             debugLog('Page:', { url, title, size: html.length, html: html.substring(0, 100) });
             // Capture iframe HTML snapshots
             const iframeSnapshots = await this.captureIframeSnapshots(html);
-            let ariaSnapshot = null;
+            let ariaSnapshot = preCapuredAria || null;
             let ariaSnapshotFile = undefined;
-            try {
-                const page = this.playwrightHelper.page;
-                const serializedSnapshot = await page.locator('body').ariaSnapshot();
+            if (!ariaSnapshot) {
+                try {
+                    const page = this.playwrightHelper.page;
+                    ariaSnapshot = await page.locator('body').ariaSnapshot();
+                }
+                catch (err) {
+                    debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
+                }
+            }
+            if (ariaSnapshot) {
                 const ariaFileName = `${stateHash}_${timestamp}.aria.yaml`;
                 const ariaPath = join(statesDir, ariaFileName);
-                fs.writeFileSync(ariaPath, serializedSnapshot, 'utf8');
-                ariaSnapshot = serializedSnapshot;
+                fs.writeFileSync(ariaPath, ariaSnapshot, 'utf8');
                 ariaSnapshotFile = ariaFileName;
             }
-            catch (err) {
-                debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
-            }
             const result = new ActionResult({
                 html,
                 title,
@@ -115,7 +118,7 @@ class Action {
                 iframeSnapshots,
                 ariaSnapshot,
                 ariaSnapshotFile,
-                iframeURL: frame?.url?.() || undefined,
+                iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
             this.stateManager.updateState(result);
             return result;

package/dist/src/ai/planner/subpages.js

@@ -1,10 +1,11 @@
 import dedent from 'dedent';
 import { z } from 'zod';
+import { ConfigParser } from "../../config.js";
 import { normalizeUrl } from "../../state-manager.js";
 const planRegistry = new Map();
-export function registerPlan(url, plan, feature) {
+export function registerPlan(url, plan, feature, stateHash) {
     const key = buildKey(url, feature);
-    planRegistry.set(key, { plan, feature, url });
+    planRegistry.set(key, { plan, feature, url, stateHash });
 }
 export function getRegisteredPlan(url, feature) {
     return planRegistry.get(buildKey(url, feature));
@@ -26,7 +27,36 @@ function buildKey(url, feature) {
         return `${normalized}::${feature}`;
     return normalized;
 }
-function isTemplateMatch(urlA, urlB) {
+export function isDynamicSegment(segment) {
+    try {
+        const configRegex = ConfigParser.getInstance().getConfig().dynamicPageRegex;
+        if (configRegex)
+            return new RegExp(configRegex, 'i').test(segment);
+    }
+    catch {
+        /* config not loaded yet */
+    }
+    // numeric: /users/123
+    if (/^\d+$/.test(segment))
+        return true;
+    // UUID: /items/550e8400-e29b-41d4-a716-446655440000
+    if (/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(segment))
+        return true;
+    // ULID: /items/01ARZ3NDEKTSV4RRFFQ69G5FAV
+    if (/^[0-9A-HJKMNP-TV-Z]{26}$/.test(segment))
+        return true;
+    // hex ID (4+ chars): /suite/70dae98a
+    if (/^[a-f0-9]{4,}$/i.test(segment))
+        return true;
+    // hex-prefixed slug (8+ hex before dash): /suite/95ef0c94-mobile
+    if (/^[a-f0-9]{8,}-/i.test(segment))
+        return true;
+    // short mixed alphanumeric (digits + letters, ≤8 chars, no dash): /item/x7f2
+    if (segment.length <= 8 && !segment.includes('-') && /\d/.test(segment) && /[a-z]/i.test(segment))
+        return true;
+    return false;
+}
+export function isTemplateMatch(urlA, urlB) {
     const partsA = normalizeUrl(urlA).split('/');
     const partsB = normalizeUrl(urlB).split('/');
     if (partsA.length !== partsB.length)
@@ -38,12 +68,18 @@ function isTemplateMatch(urlA, urlB) {
         diffCount++;
         if (diffCount > 1)
             return false;
-        const isNumericOrShortId = /^\d+$|^[a-f0-9]{4,}$/i;
-        if (!isNumericOrShortId.test(partsA[i]) && !isNumericOrShortId.test(partsB[i]))
+        if (!isDynamicSegment(partsA[i]) && !isDynamicSegment(partsB[i]))
             return false;
     }
     return diffCount === 1;
 }
+export function getPlannedByStateHash(hash) {
+    for (const record of planRegistry.values()) {
+        if (record.stateHash === hash)
+            return record;
+    }
+    return null;
+}
 const SubPagePickSchema = z.object({
     url: z.string().nullable(),
     reason: z.string(),
@@ -58,7 +94,7 @@ export function WithSubPages(Base) {
                 const pagePath = normalizeUrl(page.url);
                 if (!pagePath.startsWith(currentPath) || pagePath === currentPath)
                     continue;
-                if (isPagePlanned(page.url))
+                if (this.findSimilarPlan(page.url))
                     continue;
                 if (candidates.some((c) => normalizeUrl(c.url) === pagePath))
                     continue;

package/dist/src/ai/planner.js

@@ -14,7 +14,8 @@ import { mdq } from '../utils/markdown-query.js';
 import { Conversation } from "./conversation.js";
 import { getActiveStyle, getStyles } from "./planner/styles.js";
 import { WithSessionDedup } from "./planner/session-dedup.js";
-import { WithSubPages, getRegisteredPlan, registerPlan } from "./planner/subpages.js";
+import { WithSubPages, getPlannedByStateHash, getRegisteredPlan, registerPlan } from "./planner/subpages.js";
+import { findSimilarStateHash } from "./researcher/cache.js";
 import { hasFocusedSection } from "./researcher/focus.js";
 import { POSSIBLE_SECTIONS, Researcher } from "./researcher.js";
 import { fileUploadRule, protectionRule } from "./rules.js";
@@ -108,13 +109,24 @@ export class Planner extends PlannerBase {
         debugLog('Planning:', state?.url);
         if (!state)
             throw new Error('No state found');
-        if (!this.freshStart && !feature && !this.currentPlan && state.url) {
+        if (!feature && !this.currentPlan && state.url) {
             const similar = this.findSimilarPlan(state.url);
             if (similar) {
                 tag('info').log(`Similar page already planned: ${similar.url} (${similar.plan.tests.length} tests)`);
                 this.registerPlanInSession(similar.plan);
                 return similar.plan;
             }
+            const actionResult = ActionResult.fromState(state);
+            const combinedHtml = await actionResult.combinedHtml();
+            const similarHash = await findSimilarStateHash(combinedHtml);
+            if (similarHash) {
+                const planned = getPlannedByStateHash(similarHash);
+                if (planned) {
+                    tag('info').log(`Page content similar to already-planned: ${planned.url} — skipping`);
+                    this.registerPlanInSession(planned.plan);
+                    return planned.plan;
+                }
+            }
         }
         if (!this.freshStart && !this.currentPlan && state.url) {
             this.currentPlan = Planner.getCachedPlan(state.url);
@@ -185,7 +197,7 @@ export class Planner extends PlannerBase {
         tag('success').log(`Planning complete! ${this.currentPlan.tests.length} tests in plan: ${this.currentPlan.title}`);
         tag('info').log(`Planning style: ${this.lastStyleName} (available: ${availableStyles})`);
         if (state.url)
-            registerPlan(state.url, this.currentPlan, feature);
+            registerPlan(state.url, this.currentPlan, feature, state.hash);
         this.registerPlanInSession(this.currentPlan);
         return this.currentPlan;
     }

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

@@ -59,7 +59,7 @@ export function saveResearch(hash, text, combinedHtml) {
     }
     return researchFile;
 }
-export function findSimilarResearch(combinedHtml) {
+function findSimilarMatch(combinedHtml) {
     const statesDir = getStatesDir();
     if (!existsSync(statesDir))
         return Promise.resolve(null);
@@ -76,13 +76,8 @@ export function findSimilarResearch(combinedHtml) {
                 resolve(null);
                 return;
             }
-            debugLog(`Similar research found: ${matchHash} (${similarity}% similar)`);
-            const research = getCachedResearch(matchHash);
-            if (research) {
-                resolve(research);
-                return;
-            }
-            resolve(null);
+            debugLog(`Similar fingerprint found: ${matchHash} (${similarity}% similar)`);
+            resolve({ hash: matchHash, similarity });
         };
         worker.postMessage({
             html: combinedHtml,
@@ -92,3 +87,13 @@ export function findSimilarResearch(combinedHtml) {
         });
     });
 }
+export async function findSimilarResearch(combinedHtml) {
+    const match = await findSimilarMatch(combinedHtml);
+    if (!match)
+        return null;
+    return getCachedResearch(match.hash) || null;
+}
+export async function findSimilarStateHash(combinedHtml) {
+    const match = await findSimilarMatch(combinedHtml);
+    return match?.hash || null;
+}

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

@@ -115,9 +115,11 @@ export function WithCoordinates(Base) {
                 const text = aiResult.text || '';
                 const rows = mdq(text).query('table').toJson();
                 for (const row of rows) {
-                    const eidx = Number.parseInt(row.eidx, 10);
-                    if (Number.isNaN(eidx))
+                    let eidx = (row.eidx || '').trim();
+                    if (!eidx || eidx === '-')
                         continue;
+                    if (/^\d+$/.test(eidx))
+                        eidx = `e${eidx}`;
                     const val = (v) => (v && v !== '-' ? v : null);
                     elements.set(eidx, {
                         coordinates: val(row.Coordinates),

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

@@ -68,7 +68,7 @@ export function WithDeepAnalysis(Base) {
         From this UI research, identify elements that could reveal hidden UI when clicked
         (dropdown menus, popups, expandable panels, accordion sections, overflow menus, tab switches).
 
-        Available eidx numbers: ${eidxList}
+        Available eidx refs: ${eidxList}
 
         ${researchText}
 
@@ -76,7 +76,7 @@ export function WithDeepAnalysis(Base) {
         - Only pick elements that HIDE content until clicked (menus, dropdowns, accordions, tabs)
         - Skip regular links, data items, and navigation
         - For repeated elements (same expand button on every row), pick only the FIRST one
-        - Respond with comma-separated eidx numbers only, e.g.: 3, 7, 15
+        - Respond with comma-separated eidx refs only, e.g.: e3, e7, e15
       `;
             const model = this.provider.getModelForAgent('researcher');
             const textCall = this.provider.chat([{ role: 'user', content: textPrompt }], model, {
@@ -87,7 +87,7 @@ export function WithDeepAnalysis(Base) {
             const screenshot = this.actionResult?.screenshot;
             if (screenshot && this.provider.hasVision()) {
                 const visionPrompt = dedent `
-          This screenshot has interactive elements labeled with eidx numbers (solid bordered boxes with numbers).
+          This screenshot has interactive elements labeled with eidx refs (solid bordered boxes with labels).
           Identify elements that could reveal hidden UI when clicked.
 
           Look for: overflow/ellipsis menus, chevron dropdowns, hamburger menus,
@@ -96,30 +96,27 @@ export function WithDeepAnalysis(Base) {
           Rules:
           - For repeated icons (same icon on every list row), pick only the FIRST one
           - Skip regular text buttons, links, and navigation items
-          - Respond with comma-separated eidx numbers only, e.g.: 3, 7, 15
+          - Respond with comma-separated eidx refs only, e.g.: e3, e7, e15
         `;
                 visionCall = this.provider.processImage(visionPrompt, screenshot.toString('base64'));
             }
             const [textRes, visionRes] = await Promise.all([textCall, visionCall]);
             const eidxSet = new Set();
+            const parseRefs = (text) => {
+                if (!text)
+                    return [];
+                const matches = text.match(/e?\d+/g) || [];
+                const refs = matches.map((m) => (m.startsWith('e') ? m : `e${m}`));
+                return refs.filter((r) => allElements.has(r));
+            };
             for (const res of [textRes, visionRes]) {
-                if (!res?.text)
-                    continue;
-                const nums = res.text.match(/\d+/g)?.map(Number) || [];
-                for (const n of nums) {
-                    if (allElements.has(n))
-                        eidxSet.add(n);
+                for (const ref of parseRefs(res?.text)) {
+                    eidxSet.add(ref);
                 }
             }
-            const textNums = textRes?.text
-                ?.match(/\d+/g)
-                ?.map(Number)
-                .filter((n) => allElements.has(n)) || [];
-            const visionNums = visionRes?.text
-                ?.match(/\d+/g)
-                ?.map(Number)
-                .filter((n) => allElements.has(n)) || [];
-            debugLog(`Text model picked eidx: [${textNums.join(', ')}], Vision model picked eidx: [${visionNums.join(', ')}]`);
+            const textRefs = parseRefs(textRes?.text);
+            const visionRefs = parseRefs(visionRes?.text);
+            debugLog(`Text model picked eidx: [${textRefs.join(', ')}], Vision model picked eidx: [${visionRefs.join(', ')}]`);
             return [...eidxSet].map((eidx) => allElements.get(eidx));
         }
         _buildClickCommands(el) {

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

@@ -126,7 +126,7 @@ export function WithLocators(Base) {
                 for (const fixedSection of fixedSections) {
                     const originalSections = parseResearchSections(result.text);
                     const original = originalSections.find((s) => s.name === fixedSection.name);
-                    if (!original)
+                    if (!original || original.elements.length === 0)
                         continue;
                     if (fixedSection.containerCss && fixedSection.containerCss !== original.containerCss) {
                         debugLog(`Fixed container for "${fixedSection.name}": '${original.containerCss}' → '${fixedSection.containerCss}'`);

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

@@ -37,8 +37,9 @@ export function mapRowToElement(row) {
     const name = stripQuotes(colMap.element || '');
     if (!name)
         return null;
-    const eidxRaw = (colMap.eidx || '').trim();
-    const eidxNum = eidxRaw ? Number.parseInt(eidxRaw, 10) : Number.NaN;
+    let eidxRaw = (colMap.eidx || '').trim();
+    if (eidxRaw && /^\d+$/.test(eidxRaw))
+        eidxRaw = `e${eidxRaw}`;
     const aria = parseAriaLocator(colMap.aria || '-');
     return {
         name,
@@ -49,7 +50,7 @@ export function mapRowToElement(row) {
         coordinates: (colMap.coordinates || '-').trim() === '-' ? null : colMap.coordinates.trim(),
         color: (colMap.color || '-').trim() === '-' || (colMap.color || '').trim() === '' ? null : colMap.color.trim(),
         icon: (colMap.icon || '-').trim() === '-' || (colMap.icon || '').trim() === '' ? null : colMap.icon.trim(),
-        eidx: Number.isNaN(eidxNum) ? null : eidxNum,
+        eidx: eidxRaw && eidxRaw !== '-' ? eidxRaw : null,
     };
 }
 export function extractContainerFromBlockquote(sectionMarkdown) {

package/dist/src/ai/researcher/research-result.js

@@ -62,6 +62,8 @@ export class ResearchResult {
         this.rebuildSectionInText(section);
     }
     rebuildSectionInText(section) {
+        if (section.elements.length === 0)
+            return;
         const newTable = rebuildSectionMarkdown(section);
         const escaped = section.name.replace(/"/g, '\\"');
         let sectionQuery = mdq(this.text).query(`section2(~"${escaped}")`);

package/dist/src/ai/researcher.js

@@ -98,9 +98,9 @@ export class Researcher extends ResearcherBase {
             setActivity(`${this.emoji} Researching...`, 'action');
             await this.ensureNavigated(state.url, screenshot && this.provider.hasVision());
             await this.hooksRunner.runBeforeHook('researcher', state.url);
-            const annotatedCount = await this.explorer.annotateElements();
-            debugLog(`Annotated ${annotatedCount} interactive elements with eidx`);
-            this.actionResult = await this.explorer.createAction().capturePageState({ includeScreenshot: screenshot && this.provider.hasVision() });
+            const { ariaSnapshot, elements: annotatedElements } = await this.explorer.annotateElements();
+            debugLog(`Annotated ${annotatedElements.length} interactive elements with eidx`);
+            this.actionResult = await this.explorer.createAction().capturePageState({ includeScreenshot: screenshot && this.provider.hasVision(), ariaSnapshot });
             if (isErrorPage(this.actionResult)) {
                 const recovered = await this.waitForPageLoad(screenshot);
                 if (!recovered) {
@@ -117,7 +117,7 @@ export class Researcher extends ResearcherBase {
             }
             debugLog('Researching web page:', this.actionResult.url);
             const combinedHtml = await this.actionResult.combinedHtml();
-            if (!deep) {
+            if (!deep && !force) {
                 const similar = await findSimilarResearch(combinedHtml);
                 if (similar) {
                     tag('info').log('Similar research found, reusing cached result');
@@ -325,9 +325,10 @@ export class Researcher extends ResearcherBase {
             return false;
         try {
             await withRetry(async () => {
-                await this.explorer.annotateElements();
+                const { ariaSnapshot } = await this.explorer.annotateElements();
                 this.actionResult = await this.explorer.createAction().capturePageState({
                     includeScreenshot: screenshot && this.provider.hasVision(),
+                    ariaSnapshot,
                 });
                 if (isErrorPage(this.actionResult))
                     throw new Error('Error page detected');

package/dist/src/ai/tools.js

@@ -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';

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

@@ -15,13 +15,13 @@ export class ContextCommand extends BaseCommand {
             throw new Error('No active page to show context for');
         }
         const isVisual = args.includes('--visual') || args.includes('--screenshot');
-        await explorer.annotateElements();
+        const { ariaSnapshot } = await explorer.annotateElements();
         if (isVisual) {
             const cachedResearch = Researcher.getCachedResearch(state);
             const containers = cachedResearch ? extractValidContainers(cachedResearch) : [];
             await explorer.visuallyAnnotateElements({ containers });
         }
-        const actionResult = await explorer.createAction().capturePageState({ includeScreenshot: isVisual });
+        const actionResult = await explorer.createAction().capturePageState({ includeScreenshot: isVisual, ariaSnapshot });
         const experienceTracker = explorer.getStateManager().getExperienceTracker();
         const knowledgeTracker = this.explorBot.getKnowledgeTracker();
         let mode = 'compact';

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

@@ -72,7 +72,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;

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>';
@@ -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/plan-command.js

@@ -8,17 +8,22 @@ 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
+        const focusMatch = args.match(/--focus\s+("[^"]+"|'[^']+'|\S+)/);
+        const focusFromFlag = focusMatch?.[1]?.replace(/^["']|["']$/g, '');
+        const focusFromText = args
             .replace('--clear', '')
             .replace('--fresh', '')
             .replace(/--style\s+\S+/, '')
+            .replace(/--focus\s+("[^"]+"|'[^']+'|\S+)/, '')
             .trim();
+        const focus = focusFromFlag || focusFromText;
         if (clear) {
             this.explorBot.clearPlan();
             tag('success').log('Plan cleared');

package/dist/src/explorbot.js

@@ -84,7 +84,7 @@ export class ExplorBot {
         await this.explorer.openFreshTab();
     }
     getCurrentState() {
-        return this.explorer.getStateManager().getCurrentState();
+        return this.explorer?.getStateManager().getCurrentState() ?? null;
     }
     getExplorer() {
         return this.explorer;

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,7 @@ 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;
+        return annotatePageElements(this.playwrightHelper.page);
     }
     async visuallyAnnotateElements(opts) {
         return visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []);
@@ -269,7 +258,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 +275,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 +595,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;