explorbot 0.3.0 → 0.3.2

package/src/ai/provider.ts

@@ -1,8 +1,10 @@
 import { OpenTelemetry } from '@ai-sdk/otel';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
-import { generateObject, generateText, isStepCount, registerTelemetry } from 'ai';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { generateObject, generateText, isStepCount, registerTelemetry, tool } from 'ai';
 import type { ModelMessage } from 'ai';
+import { z } from 'zod';
 import { clearActivity, setActivity } from '../activity.ts';
 import { type AIConfig, configuredModels, modelName as getModelName } from '../config.js';
 import { executionController } from '../execution-controller.ts';
@@ -11,7 +13,7 @@ import { Stats } from '../stats.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { type RetryOptions, withRetry } from '../utils/retry.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import { Conversation, toToolExecution } from './conversation.js';
+import { Conversation, NARRATION_TOOL, toToolExecution } from './conversation.js';
 
 const debugLog = createDebug('explorbot:provider');
 const promptLog = createDebug('explorbot:provider:out');
@@ -20,7 +22,30 @@ const responseLog = createDebug('explorbot:provider:in');
 class AiError extends Error {}
 export class ContextLengthError extends Error {}
 
+const DEFAULT_PARALLEL_REQUESTS = 4;
+
+const modelSlotContext = new AsyncLocalStorage<boolean>();
+
+const HARMONY_CHANNELS = ['commentary', 'analysis', 'final'];
+
+function createHarmonyChannelFallbackTool() {
+  return tool({
+    description: 'Internal compatibility fallback for model channel output. Do not call directly.',
+    inputSchema: z.record(z.string(), z.any()),
+    execute: async () => ({ message: 'Noted. Continue with your next action.' }),
+  });
+}
+
 let telemetryRegistered = false;
+let beforeExitFlushHooked = false;
+let activeOtelSdk: NodeSDK | null = null;
+
+export async function flushTelemetry(): Promise<void> {
+  const sdk = activeOtelSdk;
+  activeOtelSdk = null;
+  if (!sdk) return;
+  await sdk.shutdown().catch((error) => debugLog(`Telemetry flush failed: ${error instanceof Error ? error.message : error}`));
+}
 
 const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
 
@@ -79,6 +104,8 @@ export class Provider {
   };
 
   lastConversation: Conversation | null = null;
+  private activeModelCalls = 0;
+  private modelCallWaiters: (() => void)[] = [];
 
   constructor(config: AIConfig) {
     if (!config?.model) {
@@ -99,6 +126,10 @@ export class Provider {
     }
   }
 
+  async stop(): Promise<void> {
+    await flushTelemetry();
+  }
+
   getModelForAgent(agentName?: string): any {
     if (!agentName) {
       return this.config.model;
@@ -154,10 +185,28 @@ export class Provider {
   private getRetryOptions(options: any = {}): RetryOptions {
     return {
       ...this.defaultRetryOptions,
-      maxAttempts: options.maxRetries || this.defaultRetryOptions.maxAttempts,
+      maxAttempts: options.maxRetries || this.config.retryAttempts || this.defaultRetryOptions.maxAttempts,
+      baseDelay: this.config.retryDelay || this.defaultRetryOptions.baseDelay,
     };
   }
 
+  private async withModelRequestSlot<T>(fn: () => Promise<T>): Promise<T> {
+    if (modelSlotContext.getStore()) return fn();
+    const limit = Math.max(1, this.config.maxParallelRequests ?? DEFAULT_PARALLEL_REQUESTS);
+    if (this.activeModelCalls >= limit || this.modelCallWaiters.length > 0) {
+      await new Promise<void>((resolve) => this.modelCallWaiters.push(resolve));
+    } else {
+      this.activeModelCalls++;
+    }
+    try {
+      return await modelSlotContext.run(true, fn);
+    } finally {
+      const next = this.modelCallWaiters.shift();
+      if (next) next();
+      else this.activeModelCalls--;
+    }
+  }
+
   private mergeProviderOptions(config: Record<string, any>, agentName?: string): Record<string, any> {
     if (!agentName) return config;
     const agentOptions = this.getProviderOptionsForAgent(agentName);
@@ -234,7 +283,12 @@ export class Provider {
       spanProcessors: [processor],
       instrumentations: [],
     });
+    activeOtelSdk = this.otelSdk;
     void this.otelSdk.start();
+    if (!beforeExitFlushHooked) {
+      process.on('beforeExit', () => void flushTelemetry());
+      beforeExitFlushHooked = true;
+    }
     if (!telemetryRegistered) {
       registerTelemetry(new OpenTelemetry());
       telemetryRegistered = true;
@@ -288,7 +342,7 @@ export class Provider {
   async invokeConversation(conversation: Conversation, tools?: any, options: any = {}): Promise<{ conversation: Conversation; response: any; toolExecutions?: any[] } | null> {
     const response = tools ? await this.generateWithTools(conversation.messages, conversation.model, tools, options) : await this.chat(conversation.messages, conversation.model, options);
 
-    const responseMessages = response.response?.messages || [];
+    const responseMessages = response.responseMessages || [];
     if (responseMessages.length > 0) {
       conversation.messages.push(...responseMessages);
       tag('debug').log('Added', responseMessages.length, 'messages from response');
@@ -302,7 +356,7 @@ export class Provider {
     const toolResults = response.toolResults || [];
 
     const resultsById = new Map(toolResults.map((r: any) => [r.toolCallId, r]));
-    const toolExecutions = toolCalls.map((call: any) => toToolExecution(call.toolName || '', call.input, resultsById.get(call.toolCallId)?.output));
+    const toolExecutions = toolCalls.filter((call: any) => call.toolName !== NARRATION_TOOL).map((call: any) => toToolExecution(call.toolName || '', call.input, resultsById.get(call.toolCallId)?.output));
 
     return { conversation, response, toolExecutions };
   }
@@ -316,21 +370,23 @@ export class Provider {
 
     promptLog(messages[messages.length - 1].content);
     try {
-      const response = await withRetry(async () => {
-        const result = await generateText({ messages, ...config });
-        this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
-        if (!result.text) {
-          debugLog(result);
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          const result = await generateText({ messages, ...config });
+          this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
+          if (!result.text) {
+            debugLog(result);
+            if (result.finishReason === 'length') {
+              throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
+            }
+            throw new Error('No response text from AI');
+          }
           if (result.finishReason === 'length') {
-            throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
+            debugLog('finishReason=length, response may be truncated');
           }
-          throw new Error('No response text from AI');
-        }
-        if (result.finishReason === 'length') {
-          debugLog('finishReason=length, response may be truncated');
-        }
-        return result;
-      }, this.getRetryOptions(options));
+          return result;
+        }, this.getRetryOptions(options))
+      );
 
       clearActivity();
       responseLog(response.text);
@@ -356,7 +412,8 @@ export class Provider {
     setActivity(`🤖 Asking ${modelName} with dynamic tools`, 'ai');
     promptLog(`Using model: ${modelName}`);
 
-    const toolNames = Object.keys(tools || {});
+    const toolsWithCommentary = tools?.commentary ? tools : { ...tools, commentary: createHarmonyChannelFallbackTool() };
+    const toolNames = Object.keys(toolsWithCommentary || {});
     tag('debug').log(`Tools enabled: [${toolNames.join(', ')}]`);
     promptLog('Available tools:', toolNames);
     promptLog(messages[messages.length - 1].content);
@@ -365,17 +422,19 @@ export class Provider {
     const extraStop = options.stopWhen;
     const stopConditions: any[] = [isStepCount(maxRoundtrips)];
     if (extraStop) stopConditions.push(extraStop);
-    const config = this.buildGenerateConfig({ tools, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
+    const config = this.buildGenerateConfig({ tools: toolsWithCommentary, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
     try {
-      const response = await withRetry(async () => {
-        const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
-        this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
-        const hasToolCall = (result.toolCalls?.length || 0) > 0;
-        if (!result.text && !hasToolCall && result.finishReason === 'length') {
-          throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
-        }
-        return result;
-      }, this.getRetryOptions(options));
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
+          this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
+          const hasToolCall = (result.toolCalls?.length || 0) > 0;
+          if (!result.text && !hasToolCall && result.finishReason === 'length') {
+            throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
+          }
+          return result;
+        }, this.getRetryOptions(options))
+      );
 
       clearActivity();
 
@@ -418,9 +477,11 @@ export class Provider {
 
     try {
       promptLog(messages[messages.length - 1].content);
-      const response = await withRetry(async () => {
-        return (await this.raceWithIdleTimeout((signal) => generateObject({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
-      }, this.getRetryOptions(options));
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          return (await this.raceWithIdleTimeout((signal) => generateObject({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
+        }, this.getRetryOptions(options))
+      );
 
       clearActivity();
       responseLog(response.object);
@@ -572,8 +633,6 @@ export class Provider {
 
     setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');
 
-    const imageData = `data:image/png;base64,${image.toString()}`;
-
     const messages: ModelMessage[] = [
       {
         role: 'user',
@@ -585,7 +644,7 @@ export class Provider {
           {
             type: 'file',
             mediaType: 'image/png',
-            data: imageData,
+            data: image,
           },
         ],
       },
@@ -602,12 +661,14 @@ export class Provider {
 
     try {
       promptLog(`Processing image with prompt: ${prompt}`);
-      const response = await withRetry(async () => {
-        return await generateText({
-          messages,
-          ...config,
-        });
-      }, this.getRetryOptions());
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          return await generateText({
+            messages,
+            ...config,
+          });
+        }, this.getRetryOptions())
+      );
 
       clearActivity();
       responseLog(response.text);
@@ -623,13 +684,13 @@ export class Provider {
   }
 
   hasVision(): boolean {
-    return this.config.visionModel !== undefined;
+    return this.config.visionModel !== undefined && !Stats.visionDisabled;
   }
 }
 
 function repairToolCall(options: ToolCallRepairOptions): any | null {
   if (options.toolCall.toolName.includes('<|channel|>')) return repairChannelMarker(options);
-  return null;
+  return repairHarmonyChannel(options);
 }
 
 function repairChannelMarker({ toolCall, tools }: ToolCallRepairOptions): any | null {
@@ -641,6 +702,17 @@ function repairChannelMarker({ toolCall, tools }: ToolCallRepairOptions): any |
   return { ...toolCall, toolName };
 }
 
+function repairHarmonyChannel({ toolCall, tools }: ToolCallRepairOptions): any | null {
+  if (!HARMONY_CHANNELS.includes(toolCall.toolName)) return null;
+  if (!tools.commentary) return null;
+  let input = toolCall.input;
+  if (typeof input !== 'string' || !input.trim().startsWith('{')) {
+    input = JSON.stringify({ content: typeof input === 'string' ? input : JSON.stringify(input ?? null) });
+  }
+  tag('warning').log(`Repaired tool name '${toolCall.toolName}' → 'commentary'`);
+  return { ...toolCall, toolName: NARRATION_TOOL, input };
+}
+
 export { AiError, Provider as AIProvider };
 
 type ToolCallRepairOptions = { toolCall: any; tools: any };

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

@@ -5,7 +5,7 @@ import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
 import { WebPageState } from '../../state-manager.js';
-import { detectFocusArea, diffAriaSnapshots } from '../../utils/aria.ts';
+import { diffAriaSnapshots } from '../../utils/aria.ts';
 import { extractCodeBlocks } from '../../utils/code-extractor.ts';
 import { tag } from '../../utils/logger.js';
 import { mdq } from '../../utils/markdown-query.ts';
@@ -86,7 +86,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     }
 
     async researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null> {
-      const focusArea = detectFocusArea(current.ariaSnapshot);
+      const focusArea = current.overlay;
       if (!focusArea.detected || !focusArea.name) return null;
       if (focusArea.type !== 'dialog' && focusArea.type !== 'modal') return null;
 

package/src/ai/tester.ts

@@ -8,10 +8,9 @@ import { clearActivity, setActivity } from '../activity.ts';
 import type { RequestStore } from '../api/request-store.ts';
 import type { TestRun } from '../explorer.ts';
 import { Observability } from '../observability.ts';
-import type { StateTransition } from '../state-manager.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';
@@ -100,7 +99,7 @@ export class Tester extends TaskAgent implements Agent {
 
   async test(task: Test, opts: TestOptions = {}): Promise<{ success: boolean }> {
     Stats.tests++;
-    const state = this.stateManager.getCurrentState();
+    let state = this.stateManager.getCurrentState();
     if (!state) throw new Error('No state found');
 
     setActivity(`🧪 Testing: ${task.scenario}`, 'action');
@@ -122,7 +121,21 @@ export class Tester extends TaskAgent implements Agent {
       task.addObservation(`Network error: ${r.method} ${r.path} → ${r.status}`);
     });
 
-    const initialState = ActionResult.fromState(state);
+    let initialState = ActionResult.fromState(state);
+    const currentUrl = state.fullUrl || state.url;
+    let startOnCurrentPage = opts.startOnCurrentPage;
+    if (isErrorPage(initialState) && !startOnCurrentPage && task.startUrl && normalizeUrl(currentUrl) !== normalizeUrl(task.startUrl)) {
+      debugLog(`Recovering from error page at ${currentUrl} by navigating to ${task.startUrl}`);
+      try {
+        await this.explorer.visit(task.startUrl);
+        state = this.stateManager.getCurrentState();
+        if (!state) throw new Error('No state found after navigating to test start URL');
+        initialState = ActionResult.fromState(state);
+        startOnCurrentPage = true;
+      } catch (error) {
+        debugLog(`Could not recover from error page: ${compactErrorMessage(error)}`);
+      }
+    }
     if (isErrorPage(initialState)) {
       task.start();
       this.testRun = await this.explorer.beginTest(task);
@@ -153,7 +166,7 @@ export class Tester extends TaskAgent implements Agent {
           expected: task.expected,
         },
       },
-      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest }, opts)
+      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest }, { ...opts, startOnCurrentPage })
     );
   }
 
@@ -481,7 +494,7 @@ export class Tester extends TaskAgent implements Agent {
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
       Fall back to interact() when those fail, when the step needs a sequence of actions, or when your context is not enough to locate the element.
-      Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
+      Use tool names exactly as listed in this prompt. Do not invent combined tool names or aliases.
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
       Do not run same tool calls with same parameters again.
@@ -517,7 +530,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) {

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/explore-command.ts

@@ -63,23 +63,26 @@ export class ExploreCommand extends BaseCommand {
       return;
     }
 
-    if (cfg.enabled) {
-      await this.runReuseMode(mainUrl, feature, cfg);
-    } else {
-      await this.runFreshMode(mainUrl, feature, cfg.styles);
-    }
+    try {
+      if (cfg.enabled) {
+        await this.runReuseMode(mainUrl, feature, cfg);
+      } else {
+        await this.runFreshMode(mainUrl, feature, cfg.styles);
+      }
 
-    const mainPlan = this.completedPlans[0];
-    if (mainPlan) this.explorBot.setCurrentPlan(mainPlan);
-    if (this.dryRun) {
+      const mainPlan = this.completedPlans[0];
+      if (mainPlan) this.explorBot.setCurrentPlan(mainPlan);
+      if (this.dryRun) {
+        this.printResults();
+        return;
+      }
+      if (mainUrl) await this.explorBot.visit(mainUrl).catch((err) => tag('warning').log(`Could not return to ${mainUrl}: ${browserErrorMessage(err)}`));
+      const savedPath = this.explorBot.savePlans(this.completedPlans);
       this.printResults();
-      return;
+      this.printNextSteps(savedPath);
+    } finally {
+      if (!this.dryRun) await this.explorBot.printSessionAnalysis();
     }
-    if (mainUrl) await this.explorBot.visit(mainUrl).catch((err) => tag('warning').log(`Could not return to ${mainUrl}: ${browserErrorMessage(err)}`));
-    const savedPath = this.explorBot.savePlans(this.completedPlans);
-    this.printResults();
-    await this.explorBot.printSessionAnalysis();
-    this.printNextSteps(savedPath);
   }
 
   private originLabel(test: Test): string {

package/src/config.ts

@@ -175,8 +175,9 @@ interface AIConfig {
   vision?: boolean;
   visionModel?: any;
   agenticModel?: any;
-  maxAttempts?: number;
+  retryAttempts?: number;
   retryDelay?: number;
+  maxParallelRequests?: number;
   agents?: AgentsConfig;
 }
 

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/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/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,
+    };
+  }
+}