explorbot 0.4.5 → 0.4.7

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -101,7 +101,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "4.0.0-rc.16",
+    "codeceptjs": "^4.2.0-beta.3",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",
@@ -123,8 +123,8 @@
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.62",
-    "playwright-core": "^1.62",
+    "playwright": "^1.63",
+    "playwright-core": "^1.63",
     "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",

package/dist/rules/researcher/pagination.md

@@ -0,0 +1,6 @@
+<pagination>
+When a section is a list that continues beyond what is shown, add one line under its `> Container:` line:
+`> Pagination: controls` — it has page numbers (1, 2, 3), prev/next arrows, or a "load more" button.
+`> Pagination: infinite` — it has none of those and loads more as it is scrolled.
+Sorting, filtering and switching tabs are not pagination — omit the line then.
+</pagination>

package/dist/src/action-result.d.ts

@@ -37,6 +37,8 @@ export interface PageDiff {
     currentUrl: string;
     ariaChanges?: string | null;
     ariaChangeCount?: number;
+    ariaAdded?: number;
+    ariaRemoved?: number;
     messages?: string[];
     requests?: NetworkCall[];
     consoleErrors?: string[];
@@ -137,6 +139,8 @@ export declare class Diff {
     _messages: string[];
     _ariaDiffResult: string | null;
     _ariaChangeCount: number;
+    _ariaAdded: number;
+    _ariaRemoved: number;
     _isSameUrl: boolean;
     constructor(current: ActionResult, previous: ActionResult | null);
     static create(current: ActionResult, previous: ActionResult | null): Promise<Diff>;
@@ -147,6 +151,8 @@ export declare class Diff {
     cleanedHtmlParts(): Promise<HtmlDiffPart[]>;
     get ariaChanged(): string | null;
     get ariaChangeCount(): number;
+    get ariaAdded(): number;
+    get ariaRemoved(): number;
     get htmlDiff(): HtmlDiffResult | null;
     get messages(): string[];
     get similarity(): number;

package/dist/src/action-result.js

@@ -451,6 +451,8 @@ export class ActionResult {
         if (diff.ariaChanged) {
             pageDiff.ariaChanges = diff.ariaChanged;
             pageDiff.ariaChangeCount = diff.ariaChangeCount;
+            pageDiff.ariaAdded = diff.ariaAdded;
+            pageDiff.ariaRemoved = diff.ariaRemoved;
         }
         if (this.overlay.isOpen && (!previousState.overlay.isOpen || previousState.overlay.name !== this.overlay.name)) {
             pageDiff.areaOfInterest = this.overlay.describe();
@@ -542,6 +544,8 @@ export class Diff {
     _messages = [];
     _ariaDiffResult = null;
     _ariaChangeCount = 0;
+    _ariaAdded = 0;
+    _ariaRemoved = 0;
     _isSameUrl;
     constructor(current, previous) {
         this.current = current;
@@ -590,6 +594,12 @@ export class Diff {
     get ariaChangeCount() {
         return this._ariaChangeCount;
     }
+    get ariaAdded() {
+        return this._ariaAdded;
+    }
+    get ariaRemoved() {
+        return this._ariaRemoved;
+    }
     get htmlDiff() {
         return this._htmlDiffResult;
     }
@@ -614,5 +624,7 @@ export class Diff {
         const ariaDiff = diffAriaSnapshots(this.previous.ariaSnapshot, this.current.ariaSnapshot);
         this._ariaDiffResult = ariaDiff.text;
         this._ariaChangeCount = ariaDiff.count;
+        this._ariaAdded = ariaDiff.added;
+        this._ariaRemoved = ariaDiff.removed;
     }
 }

package/dist/src/ai/planner.js

@@ -404,12 +404,16 @@ export class Planner extends PlannerBase {
         `);
             }
         }
+        let activeRegion = '';
+        if (state.overlay.isOpen)
+            activeRegion = `Active region: ${state.overlay.describe()} — the user's current focus area. Plan tests for the controls inside it first.`;
         conversation.addUserText(dedent `
       ${this.buildApproach(style)}
 
       <context>
       URL: ${state.url || 'Unknown'}
       Title: ${state.title || 'Unknown'}
+      ${activeRegion}
       </context>
     `);
         if (this.fisherman) {

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

@@ -38,7 +38,7 @@ export declare function WithDeepAnalysis<T extends Constructor>(Base: T): {
         }>): Promise<void>;
         _executeAndAnalyze(commands: string[], description: string, state: WebPageState, originalAria: string, alreadyExpanded: string[]): Promise<ExpansionOutcome>;
         _restorePageState(url: string, originalAria: string): Promise<void>;
-        _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[]): Promise<string | null>;
+        _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[], containerCss?: string | null): Promise<string | null>;
         _deduplicateExpandedSections(sections: string[]): string[];
         _summarizeExpanded(expandedSections: string[]): string[];
         _sectionFingerprint(sectionMarkdown: string): string | null;

package/dist/src/ai/researcher/deep-analysis.js

@@ -85,7 +85,7 @@ export function WithDeepAnalysis(Base) {
                 .filter((s) => s.elements.length > 0)
                 .map((s) => s.rawMarkdown));
             tag('substep').log(`Researching overlay: ${region.name}`);
-            const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
+            const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded, region.root);
             if (!sectionMarkdown) {
                 debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
                 return null;
@@ -367,9 +367,9 @@ export function WithDeepAnalysis(Base) {
             }
             await new Promise((r) => setTimeout(r, 500));
             let diff;
+            let currAR;
             try {
-                await this.explorer.capture();
-                const currAR = ActionResult.fromState(this.stateManager.getCurrentState());
+                currAR = await this.explorer.capture();
                 diff = await currAR.diff(previousState);
             }
             catch (err) {
@@ -388,7 +388,7 @@ export function WithDeepAnalysis(Base) {
                 debugLog(`No changes from: ${description.slice(0, 80)}`);
                 return { status: 'none', code: clickCode };
             }
-            const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded);
+            const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded, currAR.overlay.root);
             await this._restorePageState(state.url, originalAria);
             if (!sectionMarkdown)
                 return { status: 'none', code: clickCode };
@@ -413,7 +413,7 @@ export function WithDeepAnalysis(Base) {
                 tag('warning').log(`navigateTo failed during restore: ${err instanceof Error ? err.message : err}`);
             }
         }
-        async _analyzeExpandedAction(code, description, diff, alreadyExpanded) {
+        async _analyzeExpandedAction(code, description, diff, alreadyExpanded, containerCss = null) {
             const alreadyHint = alreadyExpanded.length > 0 ? `\nAlready expanded sections:\n${alreadyExpanded.join('\n')}` : '';
             let intro;
             if (code) {
@@ -473,7 +473,15 @@ export function WithDeepAnalysis(Base) {
             const sections = parseResearchSections(text);
             if (sections.length === 0)
                 return null;
-            return sections[0].rawMarkdown;
+            const sectionMarkdown = sections[0].rawMarkdown;
+            if (!containerCss)
+                return sectionMarkdown;
+            let heading = mdq(sectionMarkdown).query('h3[0]');
+            if (heading.count() === 0)
+                heading = mdq(sectionMarkdown).query('h2[0]');
+            if (heading.count() === 0)
+                return sectionMarkdown;
+            return heading.replace(`${heading.text().trimEnd()}\n\n> Container: '${containerCss}'\n\n`);
         }
         _deduplicateExpandedSections(sections) {
             const seen = new Set();

package/dist/src/ai/researcher/locators.js

@@ -281,7 +281,7 @@ export function WithLocators(Base) {
             if (sectionQuery.count() === 0)
                 sectionQuery = mdq(result.text).query(`section3(~"${escaped}")`);
             if (newCss) {
-                result.text = sectionQuery.query('blockquote[0]').replace(`Container: '${newCss}'`);
+                result.text = sectionQuery.query('blockquote[0]').setKeyValue('Container', `'${newCss}'`);
             }
             else {
                 result.text = sectionQuery.query('blockquote[0]').replace('');

package/dist/src/ai/researcher/pagination.d.ts

@@ -0,0 +1,16 @@
+import type Explorer from '../../explorer.js';
+import { type ListMeasure, type PaginationStrategy } from '../../utils/pagination.js';
+import { type Constructor } from './mixin.js';
+import type { ResearchResult } from './research-result.js';
+export declare function WithPagination<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        explorer: Explorer;
+        detectPagination(result: ResearchResult): Promise<void>;
+        probeSection(css: string): Promise<PaginationStrategy | null>;
+        measure(css: string): Promise<ListMeasure | null>;
+        recordPagination(result: ResearchResult, name: string, strategy: PaginationStrategy): void;
+    };
+} & T;
+export interface PaginationMethods {
+    detectPagination(result: ResearchResult): Promise<void>;
+}

package/dist/src/ai/researcher/pagination.js

@@ -0,0 +1,62 @@
+import { mdq } from "../../utils/markdown-query.js";
+import { inspectList, restoreScroll } from "../../utils/pagination.js";
+import { debugLog } from "./mixin.js";
+import { extractPaginationFromBlockquote, parseDataSections, parseResearchSections } from "./parser.js";
+export function WithPagination(Base) {
+    return class extends Base {
+        async detectPagination(result) {
+            const sections = [...parseResearchSections(result.text), ...parseDataSections(result.text)];
+            for (const section of sections) {
+                const css = section.containerCss;
+                if (!css)
+                    continue;
+                if (extractPaginationFromBlockquote(section.rawMarkdown))
+                    continue;
+                const strategy = await this.probeSection(css);
+                if (!strategy)
+                    continue;
+                this.recordPagination(result, section.name, strategy);
+                debugLog(`Pagination in "${section.name}": ${strategy}`);
+            }
+        }
+        async probeSection(css) {
+            const before = await this.measure(css);
+            if (!before)
+                return null;
+            if (before.hasPagingControls)
+                return 'controls';
+            if (before.isFeed)
+                return 'infinite';
+            if (!before.scrolls)
+                return null;
+            const action = this.explorer.action();
+            const scrolled = await action.attempt(`I.scrollTo('${css} > *:last-child')`).catch(() => false);
+            if (!scrolled)
+                return null;
+            const after = await this.measure(css);
+            await this.explorer.withPage((page) => page.evaluate(restoreScroll, { css, scrollTop: before.scrollTop, pageScrollY: before.pageScrollY })).catch(() => { });
+            if (!after)
+                return null;
+            if (after.items > before.items)
+                return 'infinite';
+            return null;
+        }
+        measure(css) {
+            return this.explorer
+                .withPage((page) => page.evaluate(inspectList, css))
+                .catch((err) => {
+                debugLog(`List measurement failed for '${css}': ${err.message}`);
+                return null;
+            });
+        }
+        recordPagination(result, name, strategy) {
+            const escaped = name.replace(/"/g, '\\"');
+            let sectionQuery = mdq(result.text).query(`section2(~"${escaped}")`);
+            if (sectionQuery.count() === 0)
+                sectionQuery = mdq(result.text).query(`section3(~"${escaped}")`);
+            if (sectionQuery.count() === 0)
+                return;
+            result.text = sectionQuery.query('blockquote[0]').setKeyValue('Pagination', strategy);
+        }
+    };
+}

package/dist/src/ai/researcher/parser.d.ts

@@ -1,3 +1,4 @@
+import type { PaginationStrategy } from '../../utils/pagination.js';
 export interface ResearchElement {
     name: string;
     type: string | null;
@@ -23,6 +24,8 @@ export declare const RESEARCH_COLUMN_ORDER: string[];
 export declare function mapRowToElement(row: Record<string, string>): ResearchElement | null;
 export declare function extractContainerFromBlockquote(sectionMarkdown: string): string | null;
 export declare function parseResearchSections(markdown: string): ResearchSection[];
+export declare function parseDataSections(markdown: string): ResearchSection[];
+export declare function extractPaginationFromBlockquote(sectionMarkdown: string): PaginationStrategy | null;
 export declare function extractValidContainers(researchText: string, opts?: {
     exclude?: string[];
 }): Array<{

package/dist/src/ai/researcher/parser.js

@@ -57,13 +57,10 @@ export function mapRowToElement(row) {
     };
 }
 export function extractContainerFromBlockquote(sectionMarkdown) {
-    const bq = mdq(sectionMarkdown).query('blockquote[0]').text().trim();
-    if (!bq)
+    const entry = mdq(sectionMarkdown).query('blockquote[0]').keyValue().container;
+    if (!entry)
         return null;
-    const match = bq.match(/Container:\s*(.+)/i);
-    if (!match)
-        return null;
-    const css = normalizeLocatorValue(match[1]);
+    const css = normalizeLocatorValue(entry);
     if (!css || !/^[.#\[\w]/.test(css))
         return null;
     return css;
@@ -80,6 +77,25 @@ export function parseResearchSections(markdown) {
         return { name: section.name, containerCss, elements, rawMarkdown: section.rawMarkdown, isExtended };
     });
 }
+export function parseDataSections(markdown) {
+    return parseSections(markdown)
+        .filter((s) => s.name.toLowerCase().startsWith('data:'))
+        .map((section) => ({
+        name: section.name,
+        containerCss: extractContainerFromBlockquote(section.rawMarkdown),
+        elements: [],
+        rawMarkdown: section.rawMarkdown,
+        isExtended: false,
+    }));
+}
+export function extractPaginationFromBlockquote(sectionMarkdown) {
+    const value = mdq(sectionMarkdown).query('blockquote[0]').keyValue().pagination?.toLowerCase();
+    if (value === 'controls')
+        return 'controls';
+    if (value === 'infinite')
+        return 'infinite';
+    return null;
+}
 export function extractValidContainers(researchText, opts) {
     const exclude = opts?.exclude || [];
     return parseResearchSections(researchText)

package/dist/src/ai/researcher/sections.js

@@ -63,7 +63,7 @@ export function WithSections(Base) {
         }
         async _researchSingleSection(name, description, ariaSnapshot, focusCss) {
             const currentUrl = this.stateManager.getCurrentState()?.url || '';
-            const rules = RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl);
+            const rules = RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules', 'pagination'], currentUrl);
             const url = this.actionResult?.url || 'Unknown';
             const title = this.actionResult?.title || 'Unknown';
             let focusHint = '';

package/dist/src/ai/researcher.js

@@ -18,6 +18,7 @@ import { WithCoordinates } from "./researcher/coordinates.js";
 import { WithDeepAnalysis } from "./researcher/deep-analysis.js";
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from "./researcher/focus.js";
 import { WithLocators } from "./researcher/locators.js";
+import { WithPagination } from "./researcher/pagination.js";
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from "./researcher/parser.js";
 import { ResearchResult } from "./researcher/research-result.js";
 import { WithSections } from "./researcher/sections.js";
@@ -33,7 +34,7 @@ export const POSSIBLE_SECTIONS = {
     menu: 'page menu (toolbar, context actions, filters, dropdowns)',
     navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
-const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent))));
+const ResearcherBase = WithSections(WithPagination(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent)))));
 export class Researcher extends ResearcherBase {
     ACTION_TOOLS = ['click'];
     emoji = '🔍';
@@ -230,6 +231,9 @@ export class Researcher extends ResearcherBase {
                 await this.backfillCoordinates(result);
                 await this.backfillBrokenLocators(result);
             }
+            if (!interrupted()) {
+                await this.detectPagination(result);
+            }
             // Focused section: final fallback (vision-only — without a screenshot we don't infer focus)
             if (this.hasScreenshotToAnalyze && !hasFocusedSection(result.text)) {
                 const sections = parseResearchSections(result.text);
@@ -366,7 +370,7 @@ export class Researcher extends ResearcherBase {
 
       ${generalLocatorRuleText}
 
-      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl)}
+      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules', 'pagination'], currentUrl)}
 
       <section_identification>
       Identify page sections in this priority order:
@@ -439,6 +443,7 @@ export class Researcher extends ResearcherBase {
       - When a section contains a list of similar data items (records, entities, rows — content that varies by data, not by app UI), output it as a Data section with NO table.
       - Data section heading MUST be a level-2 heading (##) that starts exactly with "Data:" — for example: "## Data: Suites List". Do NOT use ### or add section numbers.
       - Data sections must NOT include a UI map table. Only include the container and a brief summary line.
+      - When the data list has controls that move between pages of the collection, add "> Pagination: controls" under its container.
       - Example data section:
 
       ## Data: Suites List

package/dist/src/ai/rules.js

@@ -332,6 +332,22 @@ export const actionRule = dedent `
   For checkboxes, prefer I.checkOption/I.uncheckOption over I.click.
 
 
+  ### I.scrollTo
+
+  scrolls until the element is in view
+
+  I.scrollTo(<locator>)
+
+  Scrolls every scrollable ancestor of the target, so it reaches an element inside a container
+  that has its own scrollbar. I.scrollPageToBottom() moves only the page itself.
+
+  <example>
+    I.scrollTo('.rows > *:last-child');
+    I.scrollTo({ role: 'listitem', text: 'Last entry' });
+    I.scrollPageToBottom();
+  </example>
+
+
   ### I.fillField
 
   fills the field with the given value

package/dist/src/ai/scout.js

@@ -47,12 +47,18 @@ export class Scout {
                 maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
                 agentName: 'scout',
             });
+            const responseText = invokeResult?.response?.text;
+            if (responseText?.trim()) {
+                finishFromText(responseText);
+                stop();
+                return;
+            }
             if (!invokeResult?.toolExecutions?.length) {
-                finishFromText(invokeResult?.response?.text);
                 stop();
                 return;
             }
-            if (iteration >= MAX_ITERATIONS) {
+            if (iteration >= MAX_ITERATIONS - 1) {
+                conversation.addUserText('Exploration time is over. Report your findings now as your final message.');
                 const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
                 finishFromText(final?.response?.text);
                 stop();

package/dist/src/ai/tools.d.ts

@@ -1,5 +1,5 @@
-import type { ExecutedStep } from '../action.js';
 import { ActionResult, type PageDiff } from '../action-result.js';
+import type { ExecutedStep } from '../action.js';
 import { type ExperienceTracker } from '../experience-tracker.js';
 import { type Task } from '../test-plan.js';
 import type { ToolDeps } from './agent.js';

package/dist/src/ai/tools.js

@@ -5,13 +5,13 @@ import { ActionResult } from "../action-result.js";
 import { renderExperienceRecipes } from "../experience-tracker.js";
 import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
+import { ariaRefSelector, describeRef, refIsGone } from "../utils/aria-ref.js";
 import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
-import { ariaRefSelector, describeRef, refIsGone } from "../utils/aria-ref.js";
+import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
@@ -109,7 +109,13 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                             });
                         }
                         await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-                        return successToolResult('click', { ...toolResult, attempts, code: command }, action);
+                        const data = { ...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);
                     }
                 }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
@@ -305,6 +311,7 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
         - Working with iframes (switch context with I.switchTo)
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
+        - Reaching items further down a list (I.scrollTo)
 
         Example - filling a form with context (PREFERRED):
         I.fillField('Username', 'John', '.login-form')
@@ -359,10 +366,10 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                     }
                     if (!hasObservablePageChange(toolResult)) {
                         activeNote.commit(TestResult.FAILED);
-                        return failedToolResult('form', 'Form command executed, but no observable page or form-state change was captured.', {
+                        return failedToolResult('form', 'Command executed, but nothing on the page changed: no navigation, no ARIA change, no HTML change and no request.', {
                             ...toolResult,
                             code: codeBlock,
-                            suggestion: 'Treat the field/form action as not completed. Re-locate the editable control, check whether another UI layer is active, then retry and verify the field value before submitting.',
+                            suggestion: 'The command ran without reaching anything. Re-locate the target, check whether another UI layer is active, then retry. If the goal was to load more of a list, no change means the collection has ended.',
                         });
                     }
                     await commitNote(activeNote, TestResult.PASSED, toolResult, action);
@@ -1074,7 +1081,13 @@ export function successToolResult(action, data, source) {
     return result;
 }
 export function isMajorPageChange(pageDiff) {
-    return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+    if (pageDiff.urlChanged === true)
+        return false;
+    if ((pageDiff.ariaChangeCount ?? 0) < LARGE_ARIA_CHANGE_THRESHOLD)
+        return false;
+    if (pageDiff.ariaRemoved === 0 && (pageDiff.ariaAdded ?? 0) > 0)
+        return false;
+    return true;
 }
 export function hasFailedRequest(pageDiff) {
     return (pageDiff.requests ?? []).some((request) => request.status >= 400);
@@ -1109,7 +1122,7 @@ export async function failedToolResult(action, message, data, error) {
     const errorTexts = [message, ...(data?.attempts?.map((a) => a.error || '') || [])];
     if (errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
         const matched = await extractWebElements(error);
-        result.suggestion = getMultipleElementsSuggestion(matched);
+        result.suggestion = getMultipleElementsSuggestion();
         result.multipleElementsDetected = true;
         result.elements = formatElementList(matched);
         return result;
@@ -1121,16 +1134,12 @@ export async function failedToolResult(action, message, data, error) {
     }
     return result;
 }
-function getMultipleElementsSuggestion(matched) {
-    const visible = (matched || []).filter((element) => element.visible !== false);
-    let onlyVisible = '';
-    if (matched && visible.length === 1)
-        onlyVisible = `\nOnly element ${matched.indexOf(visible[0]) + 1} is on screen, so that is the one to act on.`;
+function getMultipleElementsSuggestion() {
     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 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.${onlyVisible}
+    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.
   `;
@@ -1197,6 +1206,9 @@ function formatElementList(matched) {
         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');
     })

package/dist/src/api/spec-reader.d.ts

@@ -1,5 +1,6 @@
 export declare function validateSpecs(specs?: string[]): void;
 export declare function loadSpec(specPaths: string[], outputDir: string): Promise<any>;
 export declare function extractEndpointDefinition(schema: any, endpoint: string, baseEndpoint?: string): string;
+export declare function resolveEndpoints(schema: any, pattern: string, baseEndpoint?: string): string[];
 export declare function searchEndpoints(schema: any, query: string, baseEndpoint?: string): string;
 export declare function listAllEndpoints(schema: any, baseEndpoint?: string): string;