explorbot 0.4.4 → 0.4.6

package/src/ai/rules.ts

@@ -8,8 +8,9 @@ const locatorPriorityRule = dedent`
 
   1. ARIA locators (first choice) - target browser's accessibility tree, most reliable
      Use JSON format: { "role": "button", "text": "Login" }
-     Copy role and text VERBATIM from the ARIA snapshot or UI map — never guess the pair.
-     If the element is absent from the snapshot, do not invent one; use text or CSS instead.
+     Copy role and text VERBATIM from the ARIA snapshot, UI map, or the page diff that
+     reported the element — never guess the pair; a guessed role can silently match a
+     different element with the same text. If named nowhere, use text or CSS instead.
 
   2. Text locators (second choice) - exact visible text, use only when unique on the page
      Example: 'Login', 'Submit', 'Username'
@@ -238,10 +239,10 @@ export const unexpectedPopupRule = dedent`
   If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
 
   Dismiss strategy (try in order):
-  1. I.clickXY(0, 0) — click outside the popup to close it
-  2. I.pressKey('Escape') — press Escape to dismiss
-  3. I.click('Cancel') — click Cancel button if present
-  4. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  1. I.pressKey('Escape') — press Escape to dismiss
+  2. I.click('Cancel') — click Cancel button if present
+  3. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  4. I.clickXY(0, 0) via form() tool and check if page diff changed
   </unexpected_popup_rule>
 `;
 
@@ -335,7 +336,7 @@ export const actionRule = dedent`
   Prefer text/ARIA locators with context over complex CSS/XPath selectors.
   For inline create/edit flows, after filling a field verify it contains the value, then confirm using the nearest explicit button/link, an adjacent icon-only confirm control in the same row/form, or Enter if the field remains focused.
   If locator doesn't work, try CSS or XPath locators.
-  If nothing works, use I.clickXY(x, y) as last resort.
+  If nothing works, use visualClick() — it locates the target in a screenshot before clicking it.
 
   When a click result reports several matches, pick one from its numbered list by position rather than guessing a new locator.
   Reuse the same locator with step.opts({ elementIndex: N }) as the LAST argument. N is the "Element N" number.

package/src/ai/scout/tools.ts

@@ -0,0 +1,150 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tool } from 'ai';
+import { createBashTool } from 'bash-tool';
+import dedent from 'dedent';
+import { z } from 'zod';
+import { ConfigParser } from '../../config.ts';
+import { tag } from '../../utils/logger.ts';
+import { loadMarkdownFiles } from '../../utils/markdown-files.ts';
+import { readCaptainFile } from '../captain/file-tools.ts';
+
+const MAX_FILES = 500;
+const MAX_FINDINGS = 6000;
+
+let cachedScanner: 'rg' | 'grep' | null = null;
+
+export function loadScoutCorpus(dirs: string[]): ScoutCorpus {
+  const files: ScoutCorpusFile[] = [];
+  for (const dir of dirs) {
+    if (files.length >= MAX_FILES) {
+      tag('warning').log(`Scout corpus capped at ${MAX_FILES} files — remaining directories skipped`);
+      break;
+    }
+    for (const file of loadMarkdownFiles(dir, { recursive: true })) {
+      if (files.length >= MAX_FILES) break;
+      const entry: ScoutCorpusFile = { path: file.filePath };
+      if (typeof file.data.url === 'string') entry.url = file.data.url;
+      files.push(entry);
+    }
+  }
+  return { dirs, files, excludedPaths: [] };
+}
+
+export function excludeCorpusUrls(corpus: ScoutCorpus, urls: string[]): ScoutCorpus {
+  if (urls.length === 0) return corpus;
+
+  const excludedUrls = new Set(urls);
+  const files: ScoutCorpusFile[] = [];
+  const excludedPaths = [...corpus.excludedPaths];
+  for (const file of corpus.files) {
+    if (file.url && excludedUrls.has(file.url)) {
+      excludedPaths.push(file.path);
+      continue;
+    }
+    files.push(file);
+  }
+  return { dirs: corpus.dirs, files, excludedPaths };
+}
+
+export async function createScoutTools(corpus: ScoutCorpus) {
+  const scanner = await detectScanner();
+  const projectRoot = ConfigParser.getInstance().getProjectRoot();
+
+  let result = '';
+  let searchedOrRead = false;
+
+  const getResult = () => result;
+  const finishFromText = (text?: string) => {
+    if (text && searchedOrRead) result = text.slice(0, MAX_FINDINGS);
+  };
+
+  const files: Record<string, string> = {};
+  const readableFiles = new Set<string>();
+  for (const file of corpus.files) {
+    files[toPosix(file.path)] = readFileSync(file.path, 'utf8');
+    readableFiles.add(resolve(file.path));
+  }
+
+  const toolkit = await createBashTool({
+    destination: '/',
+    files,
+    maxOutputLength: 20000,
+  });
+
+  const bashExecute = toolkit.bash.execute;
+  const bash = {
+    ...toolkit.bash,
+    execute: async (input: { command: string }) => {
+      tag('step').log(`Scout: bash ${input.command}`);
+      searchedOrRead = true;
+      return bashExecute?.(input);
+    },
+  };
+
+  const tools: Record<string, any> = {
+    bash,
+    readFile: tool({
+      description: dedent`
+        Read one documentation file from the corpus.
+        Pass the exact path returned by a search result.
+      `,
+      inputSchema: z.object({
+        path: z.string().describe('File path from a search result'),
+        startLine: z.number().optional().describe('First line to read, 1-based. Negative values count from the end of the file'),
+        endLine: z.number().optional().describe('Last line to read, 1-based and inclusive. Negative values count from the end of the file'),
+        maxChars: z.number().optional().describe('Maximum characters to return, default 12000'),
+      }),
+      execute: async (input) => {
+        tag('step').log(`Scout: read ${input.path}`);
+        const output = readCaptainFile(projectRoot, input, corpus.dirs);
+        if (!output.success) return output;
+        const resolvedPath = resolve(projectRoot || process.cwd(), output.path);
+        if (!readableFiles.has(resolvedPath)) {
+          return { success: false, message: 'File is outside the Scout corpus' };
+        }
+        searchedOrRead = true;
+        return output;
+      },
+    }),
+  };
+
+  return { tools, scanner, getResult, finishFromText };
+}
+
+async function detectScanner(): Promise<'rg' | 'grep'> {
+  if (cachedScanner) return cachedScanner;
+  if (await binaryRuns('rg')) {
+    cachedScanner = 'rg';
+    return cachedScanner;
+  }
+  if (await binaryRuns('grep')) {
+    cachedScanner = 'grep';
+    return cachedScanner;
+  }
+  throw new Error('Scout requires ripgrep or grep on PATH — neither was found');
+}
+
+async function binaryRuns(binary: 'rg' | 'grep'): Promise<boolean> {
+  try {
+    const proc = Bun.spawn([binary, '--version'], { stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+function toPosix(path: string): string {
+  return path.split('\\').join('/');
+}
+
+export interface ScoutCorpus {
+  dirs: string[];
+  files: ScoutCorpusFile[];
+  excludedPaths: string[];
+}
+
+export interface ScoutCorpusFile {
+  path: string;
+  url?: string;
+}

package/src/ai/scout.ts

@@ -0,0 +1,173 @@
+import dedent from 'dedent';
+import { tag } from '../utils/logger.ts';
+import { loop } from '../utils/loop.ts';
+import type { Agent } from './agent.ts';
+import type { Provider } from './provider.ts';
+import { type ScoutCorpus, createScoutTools, excludeCorpusUrls } from './scout/tools.ts';
+
+const MAX_ITERATIONS = 3;
+const MAX_TOOL_ROUNDTRIPS = 5;
+const CACHE_LIMIT = 40;
+const URL_LISTING_LIMIT = 40;
+
+export class Scout implements Agent {
+  emoji = '🔎';
+  private cache = new Map<string, string>();
+
+  constructor(
+    private provider: Provider,
+    private corpus: ScoutCorpus
+  ) {}
+
+  isAvailable(): boolean {
+    return this.corpus.files.length > 0;
+  }
+
+  async collectDocs(query: ScoutQuery): Promise<string> {
+    if (!this.isAvailable()) return '';
+
+    const cacheKey = `${query.url || ''}|${query.feature || ''}|${query.excludeUrls.join(',')}`;
+    const cached = this.cache.get(cacheKey);
+    if (cached !== undefined) return cached;
+
+    const corpus = excludeCorpusUrls(this.corpus, query.excludeUrls);
+    if (corpus.files.length === 0) return '';
+
+    const result = await this.runSession(corpus, query);
+    if (result === null) return '';
+
+    if (this.cache.size > CACHE_LIMIT) this.cache.clear();
+    this.cache.set(cacheKey, result);
+    return result;
+  }
+
+  private async runSession(corpus: ScoutCorpus, query: ScoutQuery): Promise<string | null> {
+    const { tools, scanner, getResult, finishFromText } = await createScoutTools(corpus);
+    const conversation = this.provider.startConversation(this.buildSystemPrompt(Object.keys(tools), corpus, query, scanner), 'scout', this.provider.getAgenticModel('scout'));
+    conversation.addUserText(this.buildTaskPrompt(query));
+
+    tag('info').log(`Scout: collecting documentation for ${query.feature || query.url || 'the current page'}`);
+
+    let failed = false;
+    await loop(
+      async ({ stop, iteration }) => {
+        const invokeResult = await this.provider.invokeConversation(conversation, tools, {
+          maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
+          agentName: 'scout',
+        });
+
+        if (!invokeResult?.toolExecutions?.length) {
+          finishFromText(invokeResult?.response?.text);
+          stop();
+          return;
+        }
+
+        if (iteration >= MAX_ITERATIONS) {
+          const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
+          finishFromText(final?.response?.text);
+          stop();
+        }
+      },
+      {
+        maxAttempts: MAX_ITERATIONS,
+        observability: { name: `scout: ${query.feature || query.url || 'docs'}`, agent: 'scout' },
+        catch: async ({ error, stop }) => {
+          failed = true;
+          tag('warning').log(`Scout error: ${(error as Error).message}`);
+          stop();
+        },
+      }
+    );
+
+    if (failed) return null;
+
+    const digest = getResult();
+    if (digest) {
+      const preview = digest.slice(0, 600);
+      const ellipsis = digest.length > 600 ? '…' : '';
+      tag('info').log(`Scout digest:\n${preview}${ellipsis}`);
+    }
+    return digest;
+  }
+
+  private buildSystemPrompt(toolNames: string[], corpus: ScoutCorpus, query: ScoutQuery, scanner: 'rg' | 'grep'): string {
+    const urls = corpus.files.map((file) => file.url).filter(Boolean) as string[];
+    const urlless = corpus.files.filter((file) => !file.url);
+    let pagesListing = '';
+    if (urls.length > 0) {
+      const listing = urls
+        .slice(0, URL_LISTING_LIMIT)
+        .map((url) => `- ${url}`)
+        .join('\n');
+      pagesListing = `Documented pages:\n${listing}`;
+      const remaining = urls.length - URL_LISTING_LIMIT;
+      if (remaining > 0) pagesListing += `\n…and ${remaining} more — find them with ${scanner}`;
+    }
+    if (urlless.length > 0) {
+      const listing = urlless
+        .slice(0, URL_LISTING_LIMIT)
+        .map((file) => `- ${toPosix(file.path)}`)
+        .join('\n');
+      pagesListing += `\nFiles with no page URL (hand-written docs):\n${listing}`;
+    }
+
+    const prompt = dedent`
+      You are Scout — a documentation retrieval agent. You find collected documentation relevant to a testing focus and report it for test planning.
+
+      You never see the application itself. The documentation corpus is your only source of truth.
+
+      CORPUS:
+      ${corpus.files.length} markdown files under:
+      - ${corpus.dirs.map(toPosix).join('\n- ')}
+      ${pagesListing}
+
+      These pages are already provided to the planner in full — do not re-report them:
+      ${query.excludeUrls.map((url) => `- ${url}`).join('\n') || '- none'}
+
+      AVAILABLE TOOLS:
+      ${toolNames.join(', ')}.
+      Use tool names exactly as listed. Do not invent aliases or combined names.
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
+
+      SCANNER:
+      ${scanner} is the search command. Scan the working directory through bash() — explore freely, pipelines, globs and repeated searches are fine. Read files with readFile().
+
+      WORKFLOW:
+      1. Scan with ${scanner} using plain prose words from the focus — feature names, page purposes, capabilities
+      2. Read the files whose hits look most relevant
+      3. Report the digest as your final message — no tool call is needed to finish
+
+      RULES:
+      - Report only what the documentation states. Never fill gaps with assumptions about the application
+      - Keep verified capabilities and unverified possibilities distinguishable, the way the documentation marks them
+      - Name the page URL each item belongs to, so scenarios anchor to real routes
+      - Explore briefly: a few scans and reads are enough, then report
+      - A short accurate digest beats a long loose one; reporting that nothing relevant exists is a valid answer
+    `;
+
+    const customPrompt = this.provider.getSystemPromptForAgent('scout');
+    if (customPrompt) return `${prompt}\n\n${customPrompt}`;
+    return prompt;
+  }
+
+  private buildTaskPrompt(query: ScoutQuery): string {
+    return dedent`
+      Page URL: ${query.url || 'Unknown'}
+      Page title: ${query.title || 'Unknown'}
+      Focus: ${query.feature || 'the page as a whole'}
+
+      Report the documented capabilities, states and transitions a test planner could turn into scenarios.
+    `;
+  }
+}
+
+function toPosix(path: string): string {
+  return path.split('\\').join('/');
+}
+
+export interface ScoutQuery {
+  url?: string;
+  title?: string;
+  feature?: string;
+  excludeUrls: string[];
+}

package/src/ai/tools.ts

@@ -1,17 +1,18 @@
 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 { ExecutedStep } from '../action.ts';
 import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
 import { type Task, TestResult } from '../test-plan.js';
+import { ariaRefSelector, describeRef, refIsGone } from '../utils/aria-ref.ts';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { cleanHtmlSnippet } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { pause } from '../utils/loop.js';
+import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
@@ -66,7 +67,6 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
           2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
-          5. I.clickXY(x, y) - coordinates fallback
           After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
         `),
         explanation: z.string().describe('Why you are clicking this element'),
@@ -79,11 +79,21 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
           return failedToolResult('click', 'No commands provided');
         }
 
-        const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
+        const trimmedCommands = rawCommands.map((cmd) => cmd.trim());
+        const coordinateCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.clickXY'));
+
+        if (coordinateCommands.length > 0) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('click', `Coordinate commands are not locators: ${coordinateCommands.join(', ')}. A coordinate click always runs, so it cannot tell you whether the element was there.`, {
+            suggestion: 'Name the element instead. Use visualClick() when you can see the target but cannot address it, or form() for a deliberate coordinate click such as dismissing a layer.',
+          });
+        }
+
+        const invalidCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
 
         if (invalidCommands.length > 0) {
           activeNote.commit(TestResult.FAILED);
-          return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() or I.clickXY() commands.`, {
+          return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() commands.`, {
             suggestion: 'Use form() tool for typing text or multiple actions, or exitIframe() to leave iframe context.',
           });
         }
@@ -111,8 +121,25 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
 
           if (success) {
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
+
+            if (!hasObservablePageChange(toolResult)) {
+              activeNote.commit(TestResult.FAILED);
+              return failedToolResult('click', 'Click executed, but no observable page change was captured.', {
+                ...toolResult,
+                attempts,
+                code: command,
+                suggestion: 'Treat the element as not clicked. It may be covered by another layer, disabled, or the locator may have matched a non-interactive ancestor. Re-locate via xpathCheck(), which reports whether the element is covered or offscreen, before retrying.',
+              });
+            }
+
             await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-            return successToolResult('click', { ...toolResult, attempts, code: command }, action);
+            const data: Record<string, any> = { ...toolResult, attempts, code: command };
+            const notExecuted = commands.slice(i + 1);
+            if (notExecuted.length) {
+              data.notExecuted = notExecuted;
+              data.suggestion = `SKIPPED: ${notExecuted.join('; ')}`;
+            }
+            return successToolResult('click', data, action);
           }
         }
 
@@ -461,10 +488,18 @@ export function createRefTools({ explorer, stateManager }: ToolDeps, task: Task)
       }),
       execute: async ({ ref, element }) => {
         const activeNote = task.startNote(`Click ${element}`);
+
+        if (await refIsGone(explorer, ref)) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('clickRef', `Ref ${ref} names no element on the page any more.`, {
+            suggestion: 'The page has been rebuilt since you were given that ref. Call context() and use the ref it gives, or fall back to click() with a locator.',
+          });
+        }
+
         const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
         const action = explorer.action();
         const named = await describeRef(explorer, ref);
-        const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+        const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
 
         if (!(await action.attempt(run, `Click ${element}`))) {
           activeNote.commit(TestResult.FAILED);
@@ -1169,21 +1204,6 @@ export async function commitNote(activeNote: any, result: TestResult, toolResult
   activeNote.commit(result);
 }
 
-async function describeRef(explorer: any, ref: string): Promise<{ role: string; text: string } | null> {
-  return Promise.resolve(
-    explorer?.withPage?.((page: any) =>
-      page.locator(`aria-ref=${ref}`).evaluate((el: any) => {
-        const tag = el.tagName.toLowerCase();
-        const roles: Record<string, string> = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
-        const role = el.getAttribute('role') || roles[tag] || tag;
-        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
-        if (!text) return null;
-        return { role, text };
-      })
-    )
-  ).catch(() => null);
-}
-
 async function hasFocusedElement(explorer: any): Promise<boolean> {
   return explorer.withPage((page: any) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
 }
@@ -1238,6 +1258,7 @@ function hasObservablePageChange(data?: Record<string, any>): boolean {
   if (data.pageDiff.urlChanged === true) return true;
   if (data.pageDiff.ariaChanges) return true;
   if (data.pageDiff.messages?.length) return true;
+  if (data.pageDiff.requests?.length) return true;
   return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 
@@ -1248,12 +1269,11 @@ export async function failedToolResult(action: string, message: string, data?: R
   }
 
   const errorTexts = [message, ...(data?.attempts?.map((a: any) => a.error || '') || [])];
-  const hasMultipleElements = errorTexts.some((t: string) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN));
-  const multipleElementsSuggestion = hasMultipleElements ? getMultipleElementsSuggestion() : null;
-  if (multipleElementsSuggestion) {
-    result.suggestion = multipleElementsSuggestion;
+  if (errorTexts.some((t: string) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
+    const matched = await extractWebElements(error);
+    result.suggestion = getMultipleElementsSuggestion();
     result.multipleElementsDetected = true;
-    result.elements = await formatMatchedElements(error);
+    result.elements = formatElementList(matched);
     return result;
   }
 
@@ -1269,8 +1289,9 @@ export async function failedToolResult(action: string, message: string, data?: R
 function getMultipleElementsSuggestion(): string {
   return dedent`
     Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
-    Read the numbered elements list and click the one you meant by its number:
+    Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
@@ -1294,7 +1315,7 @@ export function clickFailureSuggestion(attempts: Array<{ error?: string }>): str
   }
 
   if (errors.some((e) => e.includes('is not visible'))) {
-    return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
+    return 'Element is in the DOM but not visible. Reveal it — scroll to it, expand its section, open the panel holding it — or, when the page carries several copies of the same control, target the one that is on screen.';
   }
 
   if (errors.some((e) => e.includes('SyntaxError'))) {
@@ -1319,19 +1340,20 @@ const MAX_DISAMBIGUATE_TEXT = 80;
 const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 
-async function extractWebElements(error: Error | null | undefined): Promise<Array<{ xpath: string; html: string; text: string }> | null> {
+async function extractWebElements(error: Error | null | undefined): Promise<MatchedElement[] | null> {
   if (!error || error.name !== 'MultipleElementsFound') return null;
 
-  const elements = (error as any).webElements as Array<{ toAbsoluteXPath: () => Promise<string>; toOuterHTML: () => Promise<string>; getText: () => Promise<string | null> }> | undefined;
+  const elements = (error as any).webElements as Array<{ toAbsoluteXPath: () => Promise<string>; toOuterHTML: () => Promise<string>; getText: () => Promise<string | null>; isVisible?: () => Promise<boolean> }> | undefined;
   if (!elements?.length) return null;
 
-  const result: Array<{ xpath: string; html: string; text: string }> = [];
+  const result: MatchedElement[] = [];
   for (let i = 0; i < Math.min(elements.length, MAX_DISAMBIGUATE_ELEMENTS); i++) {
     try {
       const xpath = await elements[i].toAbsoluteXPath();
       const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
       const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
-      result.push({ xpath, html, text });
+      const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
+      result.push({ xpath, html, text, visible });
     } catch (e) {
       debugLog('Failed to get details for element %d: %s', i, e);
     }
@@ -1339,14 +1361,22 @@ async function extractWebElements(error: Error | null | undefined): Promise<Arra
   return result.length > 0 ? result : null;
 }
 
-function formatElementList(details: Array<{ xpath: string; html: string; text: string }>): string {
-  return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+function formatElementList(matched: MatchedElement[] | null): string {
+  if (!matched) return 'Could not fetch element details. Repeat the action to get better info.';
+  return matched
+    .map((el, i) => {
+      const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
+      if (el.visible !== undefined) lines.push(`Visible: ${el.visible}`);
+      const wrapped = matched.map((_, j) => j).filter((j) => j !== i && matched[j].xpath.startsWith(`${el.xpath}/`));
+      if (wrapped.length) lines.push(`Wraps: element ${wrapped.map((j) => j + 1).join(', ')}`);
+      lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
+      return lines.join('\n');
+    })
+    .join('\n\n');
 }
 
 export async function formatMatchedElements(error: Error | null | undefined): Promise<string | null> {
-  const details = await extractWebElements(error);
-  if (!details) return 'Could not fetch element details. Repeat the action to get better info.';
-  return formatElementList(details);
+  return formatElementList(await extractWebElements(error));
 }
 
 function getNotFoundSuggestion(errorMessage: string): string | null {
@@ -1362,3 +1392,10 @@ function getNotFoundSuggestion(errorMessage: string): string | null {
     4. Prefer ARIA locators: { "role": "button", "text": "visible text" }
   `;
 }
+
+interface MatchedElement {
+  xpath: string;
+  html: string;
+  text: string;
+  visible?: boolean;
+}