explorbot 0.1.5 → 0.1.6

package/src/ai/researcher/sections.ts

@@ -0,0 +1,122 @@
+import dedent from 'dedent';
+import type { ActionResult } from '../../action-result.js';
+import { executionController } from '../../execution-controller.ts';
+import type Explorer from '../../explorer.ts';
+import type { StateManager } from '../../state-manager.js';
+import { tag } from '../../utils/logger.js';
+import { RulesLoader } from '../../utils/rules-loader.ts';
+import type { Provider } from '../provider.js';
+import { locatorRule as generalLocatorRuleText } from '../rules.js';
+import type { Constructor } from './mixin.ts';
+
+export interface SectionMethods {
+  researchBySections(): Promise<string>;
+}
+
+export function WithSections<T extends Constructor>(Base: T) {
+  return class extends Base {
+    declare explorer: Explorer;
+    declare provider: Provider;
+    declare stateManager: StateManager;
+    declare actionResult: ActionResult | undefined;
+
+    async researchBySections(): Promise<string> {
+      const ariaSnapshot = this.actionResult?.getCompactARIA() || '';
+      const configured = (this as any).getConfiguredSections() as Record<string, string>;
+      const focusCss = await this._detectFocusCss();
+
+      let targets: Array<[string, string]>;
+      if (focusCss) {
+        targets = [['Focus', `element bounded by CSS container '${focusCss}'`]];
+        tag('info').log(`Focus element detected via selector '${focusCss}', researching focused area only`);
+      } else {
+        targets = Object.entries(configured);
+        tag('info').log(`Splitting research into ${targets.length} per-section requests`);
+      }
+
+      const parts: string[] = [];
+      for (const [name, description] of targets) {
+        if (executionController.isInterrupted()) break;
+        const text = await this._researchSingleSection(name, description, ariaSnapshot, focusCss);
+        if (!text) continue;
+        const trimmed = text.trim();
+        if (trimmed === 'NOT_PRESENT' || trimmed.startsWith('NOT_PRESENT')) continue;
+        parts.push(trimmed);
+      }
+
+      if (parts.length === 0) {
+        throw new Error('Per-section research produced no sections — AI responses all empty or NOT_PRESENT');
+      }
+
+      let merged = parts.join('\n\n');
+      if (focusCss) merged += '\n\n> Focused: Focus';
+      return merged;
+    }
+
+    private async _detectFocusCss(): Promise<string | null> {
+      const focusSections = (this.explorer.getConfig().ai?.agents?.researcher as any)?.focusSections as string[] | undefined;
+      if (!focusSections?.length) return null;
+
+      for (const css of focusSections) {
+        const count = await this.explorer.playwrightLocatorCount((page: any) => page.locator(css)).catch(() => 0);
+        if (count > 0) return css;
+      }
+      return null;
+    }
+
+    private async _researchSingleSection(name: string, description: string, ariaSnapshot: string, focusCss: string | null): Promise<string> {
+      const currentUrl = this.stateManager.getCurrentState()?.url || '';
+      const rules = RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl);
+      const url = this.actionResult?.url || 'Unknown';
+      const title = this.actionResult?.title || 'Unknown';
+
+      let focusHint = '';
+      if (focusCss) {
+        focusHint = dedent`
+          The user's focus is the element matching CSS '${focusCss}'.
+          Use that CSS as the Container for this section.
+        `;
+      }
+
+      const prompt = dedent`
+        <task>
+        Identify the "${name}" section on this page: ${description}
+        If this section is NOT present on the page, respond with ONLY: NOT_PRESENT
+        Otherwise output only this single section in the format below.
+        ${focusHint}
+        </task>
+
+        <section_format>
+        ## ${name}
+
+        > Container: '.semantic-container-selector'
+
+        | Element | ARIA | CSS | eidx |
+        </section_format>
+
+        <rules>
+        - Every element with eidx 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").
+        </rules>
+
+        ${generalLocatorRuleText}
+
+        ${rules}
+
+        URL: ${url}
+        Title: ${title}
+
+        <aria>
+        ${ariaSnapshot}
+        </aria>
+      `;
+
+      const conversation = this.provider.startConversation((this as any).getSystemMessage(), 'researcher');
+      conversation.addUserText(prompt);
+
+      const result = await this.provider.invokeConversation(conversation, undefined, { agentName: 'researcher' });
+      return result?.response.text || '';
+    }
+  };
+}

package/src/ai/researcher.ts

@@ -28,6 +28,7 @@ import { detectFocusFromAria, hasFocusedSection, markSectionAsFocused, pickDefau
 import { type LocatorMethods, WithLocators } from './researcher/locators.ts';
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from './researcher/parser.ts';
 import { ResearchResult } from './researcher/research-result.ts';
+import { type SectionMethods, WithSections } from './researcher/sections.ts';
 import { locatorRule as generalLocatorRuleText } from './rules.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { TaskAgent } from './task-agent.ts';
@@ -46,9 +47,9 @@ export const POSSIBLE_SECTIONS = {
   navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
 
-const ResearcherBase = WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent)));
+const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent))));
 
-export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods {}
+export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods, SectionMethods {}
 
 export class Researcher extends ResearcherBase implements Agent {
   protected readonly ACTION_TOOLS = ['click'];
@@ -170,10 +171,12 @@ export class Researcher extends ResearcherBase implements Agent {
       const prompt = await this.buildResearchPrompt();
       conversation.addUserText(prompt);
 
-      let invocationResult: Awaited<ReturnType<typeof this.provider.invokeConversation>>;
+      let researchText: string;
       let activeConversation = conversation;
       try {
-        invocationResult = await this.provider.invokeConversation(conversation, undefined, { agentName: 'researcher' });
+        const invocationResult = await this.provider.invokeConversation(conversation, undefined, { agentName: 'researcher' });
+        if (!invocationResult) throw new Error('Failed to get response from provider');
+        researchText = invocationResult.response.text;
       } catch (error) {
         if (!(error instanceof ContextLengthError) || retriesLeft <= 0) {
           if (error instanceof ContextLengthError) {
@@ -181,15 +184,12 @@ export class Researcher extends ResearcherBase implements Agent {
           }
           throw error;
         }
-        tag('warning').log('Output truncated, retrying with fresh focused conversation (ARIA only)...');
         retriesLeft = 0;
+        researchText = await this.researchBySections();
         activeConversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
-        activeConversation.addUserText(this.buildFocusedRetryPrompt());
-        invocationResult = await this.provider.invokeConversation(activeConversation, undefined, { agentName: 'researcher' });
       }
-      if (!invocationResult) throw new Error('Failed to get response from provider');
 
-      const result = new ResearchResult(invocationResult.response.text, state.url);
+      const result = new ResearchResult(researchText, state.url);
       debugLog(`Original research response length: ${result.text.length} chars`);
 
       const interrupted = () => executionController.isInterrupted();
@@ -537,44 +537,6 @@ export class Researcher extends ResearcherBase implements Agent {
     `;
   }
 
-  private buildFocusedRetryPrompt(): string {
-    const currentUrl = this.stateManager.getCurrentState()?.url || '';
-    const example = RulesLoader.loadRules('researcher', ['section-example'], currentUrl);
-    const uiMapTable = RulesLoader.loadRules('researcher', ['ui-map-table'], currentUrl);
-    const url = this.actionResult?.url || 'Unknown';
-    const title = this.actionResult?.title || 'Unknown';
-    const aria = this.actionResult?.getCompactARIA() || '';
-    return dedent`
-      Previous response was truncated. Restart with a minimal output.
-
-      <task>
-      Output a UI map for ONE section only — the main interactive area of this page.
-      Skip navigation, sidebar, and footer. Max 15 elements.
-      Every element with an eidx MUST appear. Every row needs CSS; ARIA may be "-" for icon-only.
-      End with a single line: \`> Focused: <section name>\`.
-      </task>
-
-      <section_format>
-      ## Section Name
-
-      > Container: '.container-css-selector'
-
-      | Element | ARIA | CSS | eidx |
-      </section_format>
-
-      ${example}
-
-      ${uiMapTable}
-
-      URL: ${url}
-      Title: ${title}
-
-      <aria>
-      ${aria}
-      </aria>
-    `;
-  }
-
   async textContent(state: WebPageState): Promise<string> {
     const actionResult = ActionResult.fromState(state);
     const html = await actionResult.combinedHtml();

package/src/ai/task-agent.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../action-result.js';
-import type { ExperienceTracker } from '../experience-tracker.js';
+import { renderExperienceToc, type ExperienceTracker } from '../experience-tracker.js';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 
@@ -56,37 +56,13 @@ export abstract class TaskAgent {
 
   protected getExperience(actionResult: ActionResult): string {
     const tracker = this.getExperienceTracker();
-    const relevantExperience = tracker.getRelevantExperience(actionResult);
+    const toc = tracker.getExperienceTableOfContents(actionResult);
+    if (toc.length === 0) return '';
 
-    if (relevantExperience.length === 0) return '';
-
-    const allContent = relevantExperience
-      .map((e) => e.content)
-      .filter((e) => !!e)
-      .join('\n\n---\n\n');
-
-    const totalChars = allContent.length;
-    let experienceContent: string;
-
-    if (totalChars <= 10_000) {
-      debugLog(`injecting all experience (${Math.round(totalChars / 1000)}k chars)`);
-      experienceContent = allContent;
-    } else {
-      experienceContent = tracker.getSuccessfulExperience(actionResult).join('\n\n---\n\n');
-      debugLog(`injecting success-only experience (${Math.round(experienceContent.length / 1000)}k chars, filtered from ${Math.round(totalChars / 1000)}k)`);
-    }
-
-    if (!experienceContent) return '';
-
-    tag('substep').log(`Found ${relevantExperience.length} experience ${pluralize(relevantExperience.length, 'file')}`);
-    return dedent`
-      <experience>
-      Here is past experience of interacting with this page.
-      Use successful solutions first. Avoid repeating failed actions.
-
-      ${experienceContent}
-      </experience>
-    `;
+    const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
+    debugLog(`injecting experience TOC (${toc.length} files, ${totalSections} sections)`);
+    tag('substep').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections)`);
+    return renderExperienceToc(toc);
   }
 
   setHistorian(historian: Historian): void {

package/src/ai/tester.ts

@@ -11,7 +11,7 @@ import type Explorer from '../explorer.ts';
 import type { StateTransition, WebPageState } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Note, type Test, TestResult, type TestResultType } from '../test-plan.ts';
-import { extractFocusedElement } from '../utils/aria.ts';
+import { detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { codeToMarkdown } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -59,6 +59,8 @@ export class Tester extends TaskAgent implements Agent {
   executionLogFile: string | null = null;
   private previousUrl: string | null = null;
   private previousStateHash: string | null = null;
+  private pageStateHash: string | null = null;
+  private pageActionResult: ActionResult | null = null;
   private hooksRunner: HooksRunner;
 
   constructor(explorer: Explorer, provider: Provider, researcher: Researcher, navigator: Navigator, agentTools?: any) {
@@ -117,6 +119,8 @@ export class Tester extends TaskAgent implements Agent {
 
     this.previousUrl = null;
     this.previousStateHash = null;
+    this.pageStateHash = null;
+    this.pageActionResult = null;
     this.explorer.getStateManager().clearHistory();
     this.resetFailureCount();
     this.pilot?.reset();
@@ -441,7 +445,8 @@ export class Tester extends TaskAgent implements Agent {
 
     if (isNewUrl) {
       const research = await this.researcher.research(currentState);
-      const experience = this.getExperience(currentState);
+      this.pageStateHash = currentStateHash;
+      this.pageActionResult = currentState;
       let uiMapSection = '';
       if (research) {
         uiMapSection = dedent`
@@ -467,8 +472,6 @@ export class Tester extends TaskAgent implements Agent {
         </page_aria>
         ${uiMapSection}
 
-        ${experience}
-
         Use <page_ui_map> to understand the page structure and its main elements.
         However, <page_ui_map> is not always up to date, use <page_aria> and <page_html> to understand the ACTUAL state of the page
         Do not interact with elements that are not listed in <page_aria> and <page_html>
@@ -477,6 +480,19 @@ export class Tester extends TaskAgent implements Agent {
       return context;
     }
 
+    const focusArea = detectFocusArea(currentState.ariaSnapshot);
+    if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
+      const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash);
+      if (overlaySection) {
+        context += dedent`
+
+          <page_ui_map_overlay>
+          ${overlaySection}
+          </page_ui_map_overlay>
+        `;
+      }
+    }
+
     // if (isStateChanged) {
     //   const combinedHtml = await currentState.combinedHtml();
     //   context += dedent`

package/src/ai/tools.ts

@@ -2,6 +2,7 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult, type ToolResultMetadata } from '../action-result.ts';
+import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
 import { type Task, TestResult } from '../test-plan.js';
 import { extractFocusedElement } from '../utils/aria.ts';
@@ -449,14 +450,18 @@ export function createAgentTools({
   explorer,
   researcher,
   navigator,
+  experienceTracker,
+  getState,
 }: {
   explorer: Explorer;
   researcher: Researcher;
   navigator: Navigator;
+  experienceTracker?: ExperienceTracker;
+  getState?: () => ActionResult | null;
 }): any {
   let visionDisabled = false;
 
-  return {
+  const tools: Record<string, any> = {
     see: tool({
       description: dedent`
         Check the page contents based on current page state and screenshot.
@@ -947,6 +952,33 @@ export function createAgentTools({
       },
     }),
   };
+
+  if (experienceTracker && getState) {
+    tools.learn_experience = tool({
+      description: dedent`
+        Read the full body of a specific experience section listed in <experience>.
+        The TOC shows entries like "A.1 ## Successful Flow: ...". Pass the fileTag and sectionIndex.
+        Only call when a TOC entry looks directly relevant to the current step.
+      `,
+      inputSchema: z.object({
+        fileTag: z.string().describe('File tag from the TOC, e.g. "A", "B", "AA"'),
+        sectionIndex: z.number().int().positive().describe('1-based section index within that file'),
+      }),
+      execute: async ({ fileTag, sectionIndex }) => {
+        const state = getState();
+        if (!state) {
+          return { error: 'No current page state available.' };
+        }
+        const section = experienceTracker.getExperienceSection(fileTag, sectionIndex, state);
+        if (!section) {
+          return { error: 'Section not found. Experience may have been updated; re-read the latest TOC.' };
+        }
+        return section;
+      },
+    });
+  }
+
+  return tools;
 }
 
 const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';

package/src/commands/explore-command.ts

@@ -1,8 +1,6 @@
-import { existsSync, readdirSync } from 'node:fs';
 import figureSet from 'figures';
 import path from 'node:path';
 import { getStyles } from '../ai/planner/styles.js';
-import { ConfigParser } from '../config.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import type { Plan } from '../test-plan.js';
 import { jsonToTable } from '../utils/markdown-parser.js';
@@ -116,14 +114,11 @@ export class ExploreCommand extends BaseCommand {
   }
 
   private printRerunSuggestions(): void {
-    const testsDir = ConfigParser.getInstance().getTestsDir();
-    if (!existsSync(testsDir)) return;
+    const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
+    if (savedFiles.length === 0) return;
 
-    const testFiles = readdirSync(testsDir).filter((f) => f.endsWith('.js'));
-    if (testFiles.length === 0) return;
-
-    for (const file of testFiles) {
-      tag('info').log(`Generated: ${file}`);
+    for (const filePath of savedFiles) {
+      tag('info').log(`Generated: ${path.basename(filePath)}`);
     }
     tag('info').log(`List tests: ${getCliName()} runs`);
     tag('info').log(`Re-run with healing: ${getCliName()} rerun <filename> [index]`);

package/src/config.ts

@@ -69,6 +69,7 @@ interface ResearcherAgentConfig extends AgentConfig {
   maxExpandableClicks?: number;
   retries?: number;
   sections?: string[];
+  focusSections?: string[];
   errorPageTimeout?: number;
 }
 

package/src/experience-tracker.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import matter from 'gray-matter';
+import { marked, type Tokens } from 'marked';
 import type { ActionResult } from './action-result.js';
 import { ConfigParser } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
@@ -332,6 +333,133 @@ ${filteredCode}
 
     return results;
   }
+
+  getExperienceTableOfContents(state: ActionResult, options?: { includeDescendantExperience?: boolean }): ExperienceTocEntry[] {
+    const records = this.getRelevantExperience(state, options);
+    if (records.length === 0) return [];
+
+    const sorted = [...records].sort((a, b) => {
+      const aHash = basename(a.filePath, '.md');
+      const bHash = basename(b.filePath, '.md');
+      return aHash.localeCompare(bHash);
+    });
+
+    const toc: ExperienceTocEntry[] = [];
+    for (let i = 0; i < sorted.length; i++) {
+      const record = sorted[i];
+      const fileHash = basename(record.filePath, '.md');
+      const url = (record.data as WebPageState)?.url || '';
+      const sections = listTocHeadings(record.content);
+      if (sections.length === 0) continue;
+      toc.push({
+        fileTag: indexToLetters(i),
+        fileHash,
+        url,
+        sections,
+      });
+    }
+    return toc;
+  }
+
+  getExperienceSection(fileTag: string, sectionIndex: number, state: ActionResult, options?: { includeDescendantExperience?: boolean }): { title: string; url: string; content: string } | null {
+    const toc = this.getExperienceTableOfContents(state, options);
+    const entry = toc.find((e) => e.fileTag === fileTag);
+    if (!entry) return null;
+
+    const filePath = this.findExperienceFileByHash(entry.fileHash);
+    if (!filePath) return null;
+
+    const { content } = this.readExperienceFile(entry.fileHash);
+    const extracted = extractHeadingSection(content, sectionIndex);
+    if (!extracted) return null;
+
+    return { title: extracted.title, url: entry.url, content: extracted.body };
+  }
+
+  private findExperienceFileByHash(fileHash: string): string | null {
+    for (const dir of this.getExperienceDirectories()) {
+      const candidate = join(dir, `${fileHash}.md`);
+      if (existsSync(candidate)) return candidate;
+    }
+    return null;
+  }
+}
+
+function listTocHeadings(content: string): { index: number; level: 2 | 3; title: string }[] {
+  const tokens = marked.lexer(content);
+  const result: { index: number; level: 2 | 3; title: string }[] = [];
+  let index = 0;
+  for (const token of tokens) {
+    if (token.type !== 'heading') continue;
+    const heading = token as Tokens.Heading;
+    if (heading.depth !== 2 && heading.depth !== 3) continue;
+    index++;
+    result.push({ index, level: heading.depth as 2 | 3, title: heading.text });
+  }
+  return result;
+}
+
+function extractHeadingSection(content: string, sectionIndex: number): { title: string; body: string } | null {
+  const tokens = marked.lexer(content);
+  const matching: { tokenIdx: number; depth: number; text: string }[] = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.type !== 'heading') continue;
+    const heading = token as Tokens.Heading;
+    if (heading.depth !== 2 && heading.depth !== 3) continue;
+    matching.push({ tokenIdx: i, depth: heading.depth, text: heading.text });
+  }
+
+  if (sectionIndex < 1 || sectionIndex > matching.length) return null;
+
+  const target = matching[sectionIndex - 1];
+  let endTokenIdx = tokens.length;
+  for (let j = target.tokenIdx + 1; j < tokens.length; j++) {
+    const token = tokens[j];
+    if (token.type !== 'heading') continue;
+    if ((token as Tokens.Heading).depth <= target.depth) {
+      endTokenIdx = j;
+      break;
+    }
+  }
+
+  const body = tokens
+    .slice(target.tokenIdx, endTokenIdx)
+    .map((t) => (t as any).raw || '')
+    .join('');
+  return { title: target.text, body };
+}
+
+function indexToLetters(index: number): string {
+  let n = index;
+  let result = '';
+  while (true) {
+    result = String.fromCharCode(65 + (n % 26)) + result;
+    n = Math.floor(n / 26);
+    if (n === 0) break;
+    n -= 1;
+  }
+  return result;
+}
+
+export function renderExperienceToc(toc: ExperienceTocEntry[]): string {
+  if (toc.length === 0) return '';
+
+  const lines: string[] = [];
+  lines.push('<experience>');
+  lines.push('Past experience for this page. Call learn_experience({ fileTag, sectionIndex }) to read a section.');
+  lines.push('');
+  for (const entry of toc) {
+    lines.push(`File ${entry.fileTag} ${entry.url}:`);
+    for (const section of entry.sections) {
+      const prefix = '#'.repeat(section.level);
+      lines.push(`  ${entry.fileTag}.${section.index} ${prefix} ${section.title}`);
+    }
+    lines.push('');
+  }
+  lines.push('</experience>');
+  return lines.join('\n');
 }
 
 export interface SessionStep {
@@ -348,3 +476,10 @@ export interface SessionExperienceEntry {
   steps: SessionStep[];
   relatedUrls?: string[];
 }
+
+export interface ExperienceTocEntry {
+  fileTag: string;
+  fileHash: string;
+  url: string;
+  sections: { index: number; level: 2 | 3; title: string }[];
+}

package/src/explorbot.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { ActionResult } from './action-result.ts';
 import { ApiClient } from './api/api-client.ts';
 import { RequestStore } from './api/request-store.ts';
 import { loadSpec } from './api/spec-reader.ts';
@@ -182,8 +183,14 @@ export class ExplorBot {
     return (this.agents.pilot ||= this.createAgent(({ ai, explorer }) => {
       const researcher = this.agentResearcher();
       const navigator = this.agentNavigator();
-      const tools = createAgentTools({ explorer, researcher, navigator });
-      return new Pilot(ai, tools, researcher, explorer);
+      const stateManager = explorer.getStateManager();
+      const experienceTracker = stateManager.getExperienceTracker();
+      const getState = () => {
+        const state = stateManager.getCurrentState();
+        return state ? ActionResult.fromState(state) : null;
+      };
+      const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState });
+      return new Pilot(ai, tools, researcher, explorer, experienceTracker);
     }));
   }
 

package/src/utils/aria.ts

@@ -355,8 +355,41 @@ export interface FocusAreaResult {
   name: string | null;
 }
 
+const CLOSE_OVERLAY_BUTTON_RE = /^close\s+(modal|dialog|popup|drawer|panel|sheet)\b/i;
+
+const findOverlayByCloseButton = (nodeList: AriaNode[]): FocusAreaResult | null => {
+  const closeIdx = nodeList.findIndex((n) => n.role === 'button' && CLOSE_OVERLAY_BUTTON_RE.test(n.name || ''));
+  if (closeIdx !== -1) {
+    let heading: AriaNode | undefined;
+    for (let i = closeIdx - 1; i >= 0; i--) {
+      if (nodeList[i].role === 'heading' && nodeList[i].name) {
+        heading = nodeList[i];
+        break;
+      }
+    }
+    if (!heading) {
+      for (let i = closeIdx + 1; i < nodeList.length; i++) {
+        if (nodeList[i].role === 'heading' && nodeList[i].name) {
+          heading = nodeList[i];
+          break;
+        }
+      }
+    }
+    return {
+      detected: true,
+      type: 'dialog',
+      name: heading?.name || null,
+    };
+  }
+  for (const node of nodeList) {
+    const inner = findOverlayByCloseButton(node.children);
+    if (inner) return inner;
+  }
+  return null;
+};
+
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
-  const nodes = parseAriaSnapshot(snapshot);
+  const nodes = parseAriaSnapshot(snapshot, true);
 
   const findFocusArea = (nodeList: AriaNode[]): FocusAreaResult | null => {
     for (const node of nodeList) {
@@ -385,7 +418,12 @@ export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
   };
 
   const result = findFocusArea(nodes);
-  return result || { detected: false, type: null, name: null };
+  if (result) return result;
+
+  const fallback = findOverlayByCloseButton(nodes);
+  if (fallback && fallback.name) return fallback;
+
+  return { detected: false, type: null, name: null };
 };
 
 export const collectInteractiveNodes = (snapshot: string | null): Array<Record<string, unknown>> => {