explorbot 0.0.5 → 0.1.0

package/dist/src/utils/web-element.js

@@ -3,6 +3,7 @@ const KEY_DISPLAY_ATTRS = ['role', 'id', 'class', 'aria-label'];
 const KEY_ATTRS = ['role', 'aria-label', 'id', 'name', 'type', 'href'];
 export class WebElement {
     tag;
+    role;
     xpath;
     clickXPath;
     attrs;
@@ -12,6 +13,7 @@ export class WebElement {
     y;
     constructor(data) {
         this.tag = data.tag;
+        this.role = data.role || data.attrs.role || '';
         this.xpath = data.xpath;
         this.clickXPath = data.clickXPath;
         this.attrs = data.attrs;
@@ -33,8 +35,7 @@ export class WebElement {
         return `(${this.x}, ${this.y})`;
     }
     get eidx() {
-        const val = this.attrs['data-explorbot-eidx'] || this.attrs.eidx;
-        return val ? Number.parseInt(val, 10) : null;
+        return this.attrs['data-explorbot-eidx'] || this.attrs.eidx || null;
     }
     get isNavigationLink() {
         if (this.tag !== 'a')
@@ -46,9 +47,10 @@ export class WebElement {
         const cls = this.attrs.class || '';
         return cls.split(/\s+/).filter((c) => c.length > 2 && !isDynamicId(c) && !isGenericClass(c));
     }
-    static fromRawData(d) {
+    static fromRawData(d, role) {
         return new WebElement({
             tag: d.tag,
+            role,
             xpath: '',
             clickXPath: buildClickableXPath({ tag: d.tag, allAttrs: d.allAttrs, text: d.text }),
             attrs: d.allAttrs,
@@ -111,7 +113,7 @@ export class WebElement {
         return { totalFound: result.totalFound, elements: result.matches.map((m) => WebElement.fromXPathMatch(m)) };
     }
 }
-function extractElementData(el) {
+export function extractElementData(el) {
     const rect = el.getBoundingClientRect();
     if (rect.width === 0 && rect.height === 0)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -77,7 +77,7 @@
     "@opentelemetry/sdk-trace-base": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.38.0",
     "@scalar/openapi-parser": "^0.25.6",
-    "@testomatio/reporter": "2.7.3",
+    "@testomatio/reporter": "^2.7.6",
     "ai": "^6.0.6",
     "axe-core": "^4.11.1",
     "bash-tool": "^1.3.15",

package/src/action.ts

@@ -64,7 +64,7 @@ class Action {
     }
   }
 
-  async capturePageState({ includeScreenshot = false }: { includeScreenshot?: boolean } = {}): Promise<ActionResult> {
+  async capturePageState({ includeScreenshot = false, ariaSnapshot: preCapuredAria }: { includeScreenshot?: boolean; ariaSnapshot?: string } = {}): Promise<ActionResult> {
     try {
       const currentState = this.stateManager.getCurrentState();
       const stateHash = currentState?.hash || 'screenshot';
@@ -111,19 +111,23 @@ class Action {
       // Capture iframe HTML snapshots
       const iframeSnapshots = await this.captureIframeSnapshots(html);
 
-      let ariaSnapshot: string | null = null;
+      let ariaSnapshot: string | null = preCapuredAria || null;
       let ariaSnapshotFile: string | undefined = 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({
@@ -137,7 +141,7 @@ class Action {
         iframeSnapshots,
         ariaSnapshot,
         ariaSnapshotFile,
-        iframeURL: frame?.url?.() || undefined,
+        iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
       });
       this.stateManager.updateState(result);
       return result;

package/src/ai/planner/subpages.ts

@@ -1,5 +1,6 @@
 import dedent from 'dedent';
 import { z } from 'zod';
+import { ConfigParser } from '../../config.ts';
 import { normalizeUrl } from '../../state-manager.ts';
 import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
@@ -9,9 +10,9 @@ import type { Constructor } from '../researcher/mixin.ts';
 
 const planRegistry: Map<string, PlanRecord> = new Map();
 
-export function registerPlan(url: string, plan: Plan, feature?: string): void {
+export function registerPlan(url: string, plan: Plan, feature?: string, stateHash?: string): void {
   const key = buildKey(url, feature);
-  planRegistry.set(key, { plan, feature, url });
+  planRegistry.set(key, { plan, feature, url, stateHash });
 }
 
 export function getRegisteredPlan(url: string, feature?: string): PlanRecord | undefined {
@@ -37,7 +38,30 @@ function buildKey(url: string, feature?: string): string {
   return normalized;
 }
 
-function isTemplateMatch(urlA: string, urlB: string): boolean {
+export function isDynamicSegment(segment: string): boolean {
+  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: string, urlB: string): boolean {
   const partsA = normalizeUrl(urlA).split('/');
   const partsB = normalizeUrl(urlB).split('/');
   if (partsA.length !== partsB.length) return false;
@@ -47,12 +71,18 @@ function isTemplateMatch(urlA: string, urlB: string): boolean {
     if (partsA[i] === partsB[i]) continue;
     diffCount++;
     if (diffCount > 1) return false;
-    const isNumericOrShortId = /^\d+$|^[a-f0-9]{4,}$/i;
-    if (!isNumericOrShortId.test(partsA[i]) && !isNumericOrShortId.test(partsB[i])) return false;
+    if (!isDynamicSegment(partsA[i]) && !isDynamicSegment(partsB[i])) return false;
   }
   return diffCount === 1;
 }
 
+export function getPlannedByStateHash(hash: string): PlanRecord | null {
+  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(),
@@ -71,7 +101,7 @@ export function WithSubPages<T extends Constructor>(Base: T) {
       for (const page of visited) {
         const pagePath = normalizeUrl(page.url);
         if (!pagePath.startsWith(currentPath) || pagePath === currentPath) continue;
-        if (isPagePlanned(page.url)) continue;
+        if (this.findSimilarPlan(page.url)) continue;
         if (candidates.some((c) => normalizeUrl(c.url) === pagePath)) continue;
 
         candidates.push({
@@ -136,6 +166,6 @@ export function WithSubPages<T extends Constructor>(Base: T) {
   };
 }
 
-type PlanRecord = { plan: Plan; feature?: string; url: string };
+type PlanRecord = { plan: Plan; feature?: string; url: string; stateHash?: string };
 
 type SubPageCandidate = { url: string; title?: string; h1?: string; visitCount: number };

package/src/ai/planner.ts

@@ -18,7 +18,8 @@ import { Conversation } from './conversation.ts';
 import type { Fisherman } from './fisherman.ts';
 import { getActiveStyle, getStyles } from './planner/styles.ts';
 import { WithSessionDedup } from './planner/session-dedup.ts';
-import { WithSubPages, getRegisteredPlan, registerPlan } from './planner/subpages.ts';
+import { WithSubPages, getPlannedByStateHash, getRegisteredPlan, registerPlan } from './planner/subpages.ts';
+import { findSimilarStateHash } from './researcher/cache.ts';
 import type { Provider } from './provider.js';
 import { hasFocusedSection } from './researcher/focus.ts';
 import { POSSIBLE_SECTIONS, Researcher } from './researcher.ts';
@@ -127,13 +128,25 @@ export class Planner extends PlannerBase implements Agent {
     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) {
@@ -211,7 +224,7 @@ export class Planner extends PlannerBase implements Agent {
     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);
+    if (state.url) registerPlan(state.url, this.currentPlan, feature, state.hash);
 
     this.registerPlanInSession(this.currentPlan);
 

package/src/ai/researcher/cache.ts

@@ -64,7 +64,7 @@ export function saveResearch(hash: string, text: string, combinedHtml?: string):
   return researchFile;
 }
 
-export function findSimilarResearch(combinedHtml: string): Promise<string | null> {
+function findSimilarMatch(combinedHtml: string): Promise<{ hash: string; similarity: number } | null> {
   const statesDir = getStatesDir();
   if (!existsSync(statesDir)) return Promise.resolve(null);
 
@@ -84,13 +84,8 @@ export function findSimilarResearch(combinedHtml: string): Promise<string | 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({
@@ -101,3 +96,14 @@ export function findSimilarResearch(combinedHtml: string): Promise<string | null
     });
   });
 }
+
+export async function findSimilarResearch(combinedHtml: string): Promise<string | null> {
+  const match = await findSimilarMatch(combinedHtml);
+  if (!match) return null;
+  return getCachedResearch(match.hash) || null;
+}
+
+export async function findSimilarStateHash(combinedHtml: string): Promise<string | null> {
+  const match = await findSimilarMatch(combinedHtml);
+  return match?.hash || null;
+}

package/src/ai/researcher/coordinates.ts

@@ -85,7 +85,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
     }
 
     private async _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult> {
-      const elements = new Map<number, { coordinates: string | null; color: string | null; icon: string | null }>();
+      const elements = new Map<string, { coordinates: string | null; color: string | null; icon: string | null }>();
       const emptyResult: VisualAnalysisResult = { elements, pagePurpose: null, primaryActions: null, focusedSection: null };
       if (!this.actionResult) return emptyResult;
 
@@ -131,8 +131,9 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
         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)) continue;
+          let eidx = (row.eidx || '').trim();
+          if (!eidx || eidx === '-') continue;
+          if (/^\d+$/.test(eidx)) eidx = `e${eidx}`;
           const val = (v: string) => (v && v !== '-' ? v : null);
           elements.set(eidx, {
             coordinates: val(row.Coordinates),
@@ -166,7 +167,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
       return emptyResult;
     }
 
-    async mergeVisualData(result: ResearchResult, visualData: Map<number, { coordinates: string | null; color: string | null; icon: string | null }>): Promise<void> {
+    async mergeVisualData(result: ResearchResult, visualData: Map<string, { coordinates: string | null; color: string | null; icon: string | null }>): Promise<void> {
       const sections = parseResearchSections(result.text);
       let merged = 0;
 
@@ -194,7 +195,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
     async backfillCoordinates(result: ResearchResult): Promise<void> {
       const page = this.explorer.playwrightHelper.page;
       const sections = parseResearchSections(result.text);
-      const eidxWithoutCoords: number[] = [];
+      const eidxWithoutCoords: string[] = [];
       for (const section of sections) {
         for (const el of section.elements) {
           if (el.eidx && !el.coordinates) eidxWithoutCoords.push(el.eidx);
@@ -224,7 +225,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
 }
 
 export interface VisualAnalysisResult {
-  elements: Map<number, { coordinates: string | null; color: string | null; icon: string | null }>;
+  elements: Map<string, { coordinates: string | null; color: string | null; icon: string | null }>;
   pagePurpose: string | null;
   primaryActions: string[] | null;
   focusedSection: string | null;
@@ -232,7 +233,7 @@ export interface VisualAnalysisResult {
 
 export interface CoordinateMethods {
   analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult>;
-  mergeVisualData(result: ResearchResult, visualData: Map<number, { coordinates: string | null; color: string | null; icon: string | null }>): Promise<void>;
+  mergeVisualData(result: ResearchResult, visualData: Map<string, { coordinates: string | null; color: string | null; icon: string | null }>): Promise<void>;
   backfillCoordinates(result: ResearchResult): Promise<void>;
   visuallyAnnotateElements(opts?: { containers?: Array<{ css: string; label: string }> }): Promise<number>;
 }

package/src/ai/researcher/deep-analysis.ts

@@ -77,7 +77,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     }
 
     private async _discoverExpandables(researchText: string): Promise<ExpandableElement[]> {
-      const allElements = new Map<number, ExpandableElement>();
+      const allElements = new Map<string, ExpandableElement>();
       for (const section of parseResearchSections(researchText)) {
         for (const el of section.elements) {
           if (el.eidx != null) allElements.set(el.eidx, { ...el, container: section.containerCss });
@@ -91,7 +91,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
         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}
 
@@ -99,7 +99,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
         - 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');
@@ -112,7 +112,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       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,
@@ -121,33 +121,30 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
           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<number>();
+      const eidxSet = new Set<string>();
+      const parseRefs = (text: string | undefined) => {
+        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)!);
     }

package/src/ai/researcher/locators.ts

@@ -146,7 +146,7 @@ export function WithLocators<T extends Constructor>(Base: T) {
         for (const fixedSection of fixedSections) {
           const originalSections = parseResearchSections(result.text);
           const original = originalSections.find((s) => s.name === fixedSection.name);
-          if (!original) continue;
+          if (!original || original.elements.length === 0) continue;
 
           if (fixedSection.containerCss && fixedSection.containerCss !== original.containerCss) {
             debugLog(`Fixed container for "${fixedSection.name}": '${original.containerCss}' → '${fixedSection.containerCss}'`);
@@ -177,8 +177,8 @@ export function WithLocators<T extends Constructor>(Base: T) {
       const sections = parseResearchSections(result.text);
       const brokenCss = new Set(result.locators.filter((l) => l.type === 'css' && l.valid === false).map((l) => `${l.section}::${l.element}`));
 
-      const needsXpath: number[] = [];
-      const needsXpathEls = new Map<number, { section: (typeof sections)[0]; el: (typeof sections)[0]['elements'][0] }>();
+      const needsXpath: string[] = [];
+      const needsXpathEls = new Map<string, { section: (typeof sections)[0]; el: (typeof sections)[0]['elements'][0] }>();
 
       for (const section of sections) {
         for (const el of section.elements) {

package/src/ai/researcher/parser.ts

@@ -13,7 +13,7 @@ export interface ResearchElement {
   coordinates: string | null;
   color: string | null;
   icon: string | null;
-  eidx: number | null;
+  eidx: string | null;
 }
 
 export interface ResearchSection {
@@ -62,8 +62,8 @@ export function mapRowToElement(row: Record<string, string>): ResearchElement |
   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 || '-');
 
@@ -76,7 +76,7 @@ export function mapRowToElement(row: Record<string, string>): ResearchElement |
     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,
   };
 }
 

package/src/ai/researcher/research-result.ts

@@ -65,6 +65,7 @@ export class ResearchResult {
   }
 
   rebuildSectionInText(section: ResearchSection): void {
+    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/src/ai/researcher.ts

@@ -131,9 +131,9 @@ export class Researcher extends ResearcherBase implements Agent {
       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);
@@ -154,7 +154,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
       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');
@@ -385,9 +385,10 @@ export class Researcher extends ResearcherBase implements Agent {
     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/src/ai/tools.ts

@@ -340,8 +340,13 @@ export function createCodeceptJSTools(explorer: Explorer, task: 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) {

package/src/commands/context-command.ts

@@ -21,7 +21,7 @@ export class ContextCommand extends BaseCommand {
 
     const isVisual = args.includes('--visual') || args.includes('--screenshot');
 
-    await explorer.annotateElements();
+    const { ariaSnapshot } = await explorer.annotateElements();
 
     if (isVisual) {
       const cachedResearch = Researcher.getCachedResearch(state);
@@ -29,7 +29,7 @@ export class ContextCommand extends BaseCommand {
       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();
 

package/src/commands/explore-command.ts

@@ -78,7 +78,7 @@ export class ExploreCommand extends BaseCommand {
   }
 
   private printResults(savedPath?: string | null): void {
-    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;
 

package/src/commands/init-command.ts

@@ -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.ts';
 
 const DEFAULT_CONFIG_TEMPLATE = `import { createOpenRouter } from '@openrouter/ai-sdk-provider';
@@ -103,9 +104,11 @@ export function runInitCommand(options: InitCommandOptions): void {
     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 });

package/src/commands/plan-command.ts

@@ -9,6 +9,7 @@ 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: string): Promise<void> {
@@ -16,11 +17,15 @@ export class PlanCommand extends BaseCommand {
     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();

package/src/config.ts

@@ -185,6 +185,7 @@ interface ExplorbotConfig {
   api?: ApiConfig;
   stepsFile?: string;
   files?: Record<string, string>;
+  dynamicPageRegex?: string;
 }
 
 const config: ExplorbotConfig = {

package/src/explorbot.ts

@@ -108,7 +108,7 @@ export class ExplorBot {
   }
 
   getCurrentState(): WebPageState | null {
-    return this.explorer.getStateManager().getCurrentState();
+    return this.explorer?.getStateManager().getCurrentState() ?? null;
   }
 
   getExplorer(): Explorer {