explorbot 0.3.1 → 0.3.4

package/src/ai/researcher/sections.ts

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

package/src/ai/researcher.ts

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

package/src/ai/rules.ts

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

package/src/ai/tester.ts

@@ -11,7 +11,6 @@ import { Observability } from '../observability.ts';
 import { type StateTransition, normalizeUrl } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Test, TestResult, type TestResultType } from '../test-plan.ts';
-import { detectFocusArea } from '../utils/aria.ts';
 import { ErrorPageError, isErrorPage } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
@@ -66,6 +65,12 @@ export class Tester extends TaskAgent implements Agent {
   private stalledIterations = 0;
   private readonly MAX_STALLED_ITERATIONS = 3;
 
+  private skipResearch = (err: Error): string => {
+    if (err.name === 'AbortError') throw err;
+    tag('warning').log(`Research skipped: ${err.message}`);
+    return '';
+  };
+
   constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any) {
     super(deps);
     this.requestStore = deps.requestStore;
@@ -531,7 +536,7 @@ export class Tester extends TaskAgent implements Agent {
 
     let context = '';
 
-    const focusArea = detectFocusArea(currentState.ariaSnapshot);
+    const focusArea = currentState.overlay;
 
     const focusedElement = currentState.focusedElement;
     if (focusedElement) {
@@ -582,12 +587,7 @@ export class Tester extends TaskAgent implements Agent {
       const alreadySeenUiMap = this.seenUiMapUrls.has(currentUrl);
       let research = '';
       if (!alreadySeenUiMap) {
-        try {
-          research = await this.researcher.research(currentState);
-        } catch (err) {
-          if (!(err instanceof ErrorPageError)) throw err;
-          tag('warning').log(`Research skipped: ${err.message}`);
-        }
+        research = await this.researcher.research(currentState).catch(this.skipResearch);
       }
       this.pageStateHash = currentStateHash;
       this.pageActionResult = currentState;
@@ -628,7 +628,7 @@ export class Tester extends TaskAgent implements Agent {
     }
 
     if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
-      const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash);
+      const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash).catch(this.skipResearch);
       if (overlaySection) {
         context += dedent`
 

package/src/ai/tools.ts

@@ -1,6 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
+import type { ExecutedStep } from '../action.ts';
 import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
 import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
@@ -411,7 +412,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
             const message = errorText(action.lastError);
             await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
-            let formSuggestion = 'Look into error message and identify which commands passed and which failed. Continue execution using step-by-step approach using click() and form() tools.';
+            let formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
             if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
               const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
               if (disambiguated) {
@@ -421,10 +422,11 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
 
             return failedToolResult(
               'form',
-              `Form execution FAILED! ${message}`,
+              `Form execution FAILED! ${message}\n${formatExecutedSteps(action.executedSteps, codeLines.length)}`,
               {
                 ...toolResult,
                 code: codeBlock,
+                attempts: action.executedSteps,
                 suggestion: formSuggestion,
               },
               action.lastError
@@ -446,6 +448,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
               ...toolResult,
               message: `Form completed successfully with ${lines.length} commands.`,
               commandsExecuted: lines.length,
+              attempts: action.executedSteps,
               code: codeBlock,
               suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
             },
@@ -806,21 +809,26 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
           const actionResult = ActionResult.fromState(currentState);
           const experience = renderExperienceRecipes(explorer.activeTest?.getAppliedExperience(actionResult) ?? []);
           const success = await navigator.resolveState(instruction, actionResult, { experience });
+          const attempts = navigator.executedSteps;
+          let stepReport = '';
+          if (attempts.length) stepReport = `\n${formatExecutedSteps(attempts)}`;
 
           const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, instruction);
 
           if (success) {
             return successToolResult('interact', {
               ...toolResult,
-              message: `Successfully executed: ${instruction}`,
+              message: `Successfully executed: ${instruction}${stepReport}`,
+              attempts,
             });
           }
 
           let reason = '';
           if (navigator.lastFailureReason) reason = `: ${navigator.lastFailureReason}`;
 
-          return failedToolResult('interact', `Failed to execute: ${instruction}${reason}`, {
+          return failedToolResult('interact', `Failed to execute: ${instruction}${reason}${stepReport}`, {
             ...toolResult,
+            attempts,
             suggestion: 'The action could not be completed. Try a different instruction or use more specific element descriptions.',
           });
         } catch (error) {
@@ -1232,6 +1240,14 @@ export function hasFailedRequest(pageDiff: PageDiff): boolean {
   return (pageDiff.requests ?? []).some((request) => request.status >= 400);
 }
 
+export function formatExecutedSteps(steps: ExecutedStep[], requestedCount = steps.length): string {
+  if (!steps.length) return `No command ran of ${requestedCount} requested.`;
+  const lines = steps.map((step) => `  ${step.success ? 'OK' : 'FAILED'} ${step.command}`);
+  const notRun = requestedCount - steps.length;
+  if (notRun > 0) lines.push(`  NOT RUN ${notRun} more`);
+  return lines.join('\n');
+}
+
 function hasObservablePageChange(data?: Record<string, any>): boolean {
   if (!data?.pageDiff) return false;
   if (data.pageDiff.urlChanged === true) return true;

package/src/commands/exit-command.ts

@@ -11,7 +11,7 @@ export class ExitCommand extends BaseCommand {
 
   async execute(_args: string): Promise<void> {
     await this.explorBot.printSessionAnalysis();
-    await this.explorBot.getExplorer().stop();
+    await this.explorBot.stop();
 
     if (Stats.hasActivity()) {
       await new Promise<void>((resolve) => {

package/src/commands/init-command.ts

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

package/src/components/InitWizard.tsx

@@ -10,14 +10,15 @@ import InputReadline from './InputReadline.js';
 const PROVIDER_NAMES = Object.keys(PROVIDERS);
 
 interface InitWizardProps {
-  mode: 'choose' | 'global';
+  mode: 'choose' | 'global' | 'local';
   globalConfigExists: boolean;
   onLocal: () => void;
   onComplete: () => void;
   onCancel: () => void;
+  onLocalProvider?: (provider: string) => void;
 }
 
-const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLocal, onComplete, onCancel }) => {
+const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLocal, onComplete, onCancel, onLocalProvider }) => {
   const [step, setStep] = useState<'target' | 'provider' | 'key' | 'validate'>(mode === 'choose' ? 'target' : 'provider');
   const [targetIndex, setTargetIndex] = useState(0);
   const [providerIndex, setProviderIndex] = useState(0);
@@ -78,7 +79,10 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
     if (step === 'provider') {
       if (key.upArrow) setProviderIndex((index) => Math.max(0, index - 1));
       if (key.downArrow) setProviderIndex((index) => Math.min(PROVIDER_NAMES.length - 1, index + 1));
-      if (key.return) setStep('key');
+      if (key.return) {
+        if (mode === 'local') onLocalProvider?.(provider);
+        else setStep('key');
+      }
       return;
     }
 
@@ -151,7 +155,7 @@ const InitWizard: React.FC<InitWizardProps> = ({ mode, globalConfigExists, onLoc
 
       <Box marginTop={1}>
         <Text dimColor>
-          Config goes to {globalDir()} | {step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm'} | Ctrl+C: exit
+          Config goes to {mode === 'local' ? 'the current directory' : globalDir()} | {step === 'key' ? 'Enter: continue' : '↑↓: select | Enter: confirm'} | Ctrl+C: exit
         </Text>
       </Box>
     </Box>

package/src/explorbot.ts

@@ -142,6 +142,7 @@ export class ExplorBot {
   async stop(): Promise<void> {
     this.agents.quartermaster?.stop();
     await this.explorer?.stop();
+    await this.provider?.stop();
   }
 
   async visitInitialState(): Promise<void> {

package/src/explorer.ts

@@ -255,6 +255,7 @@ class Explorer {
     const projectRoot = configParser.getProjectRoot();
     (global as any).output_dir = configParser.getStatesDir();
     (global as any).codecept_dir = projectRoot;
+    (global as any).codeceptjs = codeceptjs;
 
     configParser.validateConfig(this.config);
 

package/src/knowledge-tracker.ts

@@ -95,7 +95,7 @@ export class KnowledgeTracker {
     return this.applicationSpec?.renderFor(state) || '';
   }
 
-  addKnowledge(urlPattern: string, description: string): { filename: string; filePath: string; isNewFile: boolean } {
+  addKnowledge(urlPattern: string, description: string, opts?: { replace?: boolean }): { filename: string; filePath: string; isNewFile: boolean } {
     const configParser = ConfigParser.getInstance();
     const configPath = configParser.getConfigPath();
 
@@ -130,10 +130,10 @@ export class KnowledgeTracker {
 
       // Append new knowledge with separator
       let newContent;
-      if (existingDescription) {
-        newContent = `${existingDescription}\n\n---\n\n${description}`;
-      } else {
+      if (opts?.replace || !existingDescription) {
         newContent = description;
+      } else {
+        newContent = `${existingDescription}\n\n---\n\n${description}`;
       }
 
       const fileContent = matter.stringify(newContent, frontmatter);

package/src/state-manager.ts

@@ -1,8 +1,8 @@
 import { ActionResult, type FocusedElement } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
-import { detectFocusArea } from './utils/aria.js';
 import { createDebug, tag } from './utils/logger.js';
+import { Overlay } from './utils/overlay.js';
 import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 
@@ -49,6 +49,7 @@ export interface WebPageState {
   focusedElement?: FocusedElement | null;
   links?: Link[];
   verifications?: Record<string, boolean>;
+  overlay?: Overlay;
 }
 
 export interface StateTransition {
@@ -206,8 +207,8 @@ export class StateManager {
   }
 
   private hasDialogAppeared(previousState: WebPageState | null, newState: WebPageState): boolean {
-    const prevFocus = detectFocusArea(previousState?.ariaSnapshot ?? null);
-    const newFocus = detectFocusArea(newState.ariaSnapshot ?? null);
+    const prevFocus = previousState?.overlay ?? Overlay.fromAria(previousState?.ariaSnapshot ?? null);
+    const newFocus = newState.overlay ?? Overlay.fromAria(newState.ariaSnapshot ?? null);
     return !prevFocus.detected && newFocus.detected;
   }
 

package/src/utils/aria.ts

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

package/src/utils/html.ts

@@ -98,7 +98,6 @@ export const HTML_SELECTORS = {
   interactiveControl: 'button, a[href], input, select, textarea, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="tab"], [role="menuitem"]',
   labelLike: 'h1, h2, h3, h4, h5, h6, legend, caption, label, [role="heading"], [class*="title"], [class*="label"], [class*="header"], [class*="name"]',
   semanticContextContainer: 'section, article, form, fieldset, li, tr, td, th, [role="group"], [role="tabpanel"], [role="region"], [class*="card"], [class*="panel"], [class*="item"], [class*="usage"], [class*="group"]',
-  semanticOverlays: ['[role="dialog"]', '[role="listbox"]', '[role="menu"]', '[role="tooltip"]:not([style*="display: none"]):not([style*="visibility: hidden"])'],
 } as const;
 
 export const HTML_VISIBILITY_LIMITS = {
@@ -163,7 +162,9 @@ export type VisibleOverlayExtractionConfig = {
   interactiveContentSelector: string;
   limits: typeof HTML_EXTRACTION_LIMITS;
   overlaySelectors: readonly string[];
+  overlaySemanticSelector: string;
   visibilityLimits: typeof HTML_VISIBILITY_LIMITS;
+  geometryFallback?: boolean;
 };
 export type ComponentScopeExtractionConfig = {
   eidxAttr: string;
@@ -479,20 +480,28 @@ export function extractVisibleOverlayHtml(config: VisibleOverlayExtractionConfig
     return interactiveCount > 0 || text.length > 0;
   }
 
-  const overlays: string[] = [];
+  function isFloatingOverlay(element: Element): boolean {
+    const style = window.getComputedStyle(element as HTMLElement);
+    return style.position === 'fixed' || style.position === 'absolute' || Number.parseInt(style.zIndex || '0', 10) > 0;
+  }
+
   const seen = new Set<Element>();
+  const collected: Element[] = [];
   for (const selector of config.overlaySelectors) {
     for (const element of Array.from(document.querySelectorAll(selector))) {
       if (seen.has(element)) continue;
       seen.add(element);
       if (!isVisible(element)) continue;
+      if (!element.matches(config.overlaySemanticSelector) && !isFloatingOverlay(element)) continue;
       const { interactiveCount, text } = getUsefulContent(element);
       if (interactiveCount === 0 && text.length === 0) continue;
-      overlays.push((element as HTMLElement).outerHTML.slice(0, config.limits.overlayHtmlLength));
+      collected.push(element);
     }
   }
 
-  if (overlays.length === 0) {
+  const overlays = collected.filter((element) => !collected.some((other) => other !== element && element.contains(other))).map((element) => (element as HTMLElement).outerHTML.slice(0, config.limits.overlayHtmlLength));
+
+  if (overlays.length === 0 && config.geometryFallback !== false) {
     const floatingCandidates = Array.from(document.body.querySelectorAll('*'))
       .filter((element) => !seen.has(element) && isVisible(element) && isLikelyFloatingOverlay(element))
       .sort((left, right) => {

package/src/utils/overlay.ts

@@ -0,0 +1,51 @@
+import { detectFocusArea } from './aria.js';
+import { HTML_EXTRACTION_LIMITS, HTML_SELECTORS, HTML_VISIBILITY_LIMITS, type VisibleOverlayExtractionConfig, extractHeadings } from './html.js';
+
+export const OVERLAY_SELECTORS = {
+  semanticOverlays: ['[role="dialog"]', '[role="listbox"]', '[role="menu"]', '[role="tooltip"]:not([style*="display: none"]):not([style*="visibility: hidden"])', '[class*="modal"]', '[class*="dialog"]', '[class*="overlay"]', '[class*="popup"]', '[class*="drawer"]', '[class*="lightbox"]'],
+  modalOverlays: ['[role="dialog"]', '[role="alertdialog"]', '[aria-modal="true"]', '[class*="modal"]', '[class*="dialog"]', '[class*="overlay"]', '[class*="popup"]', '[class*="drawer"]', '[class*="lightbox"]'],
+  overlaySemanticSelector: '[role="dialog"], [role="alertdialog"], [aria-modal="true"], [role="listbox"], [role="menu"], [role="tooltip"]',
+} as const;
+
+export type OverlayData = { type?: 'dialog' | 'modal' | null; name?: string | null };
+
+export class Overlay {
+  readonly type: 'dialog' | 'modal' | null;
+  readonly name: string | null;
+
+  constructor(data: OverlayData = {}) {
+    this.type = data.type ?? null;
+    this.name = data.name ?? null;
+  }
+
+  get detected(): boolean {
+    return this.type !== null;
+  }
+
+  static fromHtml(html: string): Overlay {
+    const headings = extractHeadings(html);
+    const name = [headings.h1, headings.h2, headings.h3, headings.h4].filter(Boolean).join(' ');
+    return new Overlay({ type: 'modal', name: name || null });
+  }
+
+  static fromAria(snapshot: string | null): Overlay {
+    return new Overlay(detectFocusArea(snapshot));
+  }
+
+  static resolve(data: { overlayHtml?: string; overlay?: OverlayData | null; ariaSnapshot?: string | null }): Overlay {
+    if (data.overlayHtml) return Overlay.fromHtml(data.overlayHtml);
+    if (data.overlay) return new Overlay(data.overlay);
+    return Overlay.fromAria(data.ariaSnapshot ?? null);
+  }
+
+  static captureConfig(): VisibleOverlayExtractionConfig {
+    return {
+      interactiveContentSelector: HTML_SELECTORS.interactiveContent,
+      limits: HTML_EXTRACTION_LIMITS,
+      overlaySelectors: OVERLAY_SELECTORS.modalOverlays,
+      overlaySemanticSelector: OVERLAY_SELECTORS.overlaySemanticSelector,
+      visibilityLimits: HTML_VISIBILITY_LIMITS,
+      geometryFallback: false,
+    };
+  }
+}