explorbot 0.5.3 → 0.5.4

package/dist/src/ai/pilot.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { ConfigParser } from "../config.js";
 import { Stats } from "../stats.js";
-import { TestResult, TestStatus } from "../test-plan.js";
+import { SettledExpectation, TestResult, TestStatus } from "../test-plan.js";
 import { collectInteractiveNodes } from "../utils/aria.js";
 import { ErrorPageError } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
@@ -26,6 +26,11 @@ const OUTCOME_STATUS = {
     'The run shows this outcome happened.': 'passed',
     'The run shows this outcome did not happen.': 'failed',
 };
+const CONTRADICTION_RESOLUTION = {
+    'The page structure agrees with the screenshot, and the outcome happened.': { status: 'passed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+    'The page structure agrees with the screenshot, and the outcome did not happen.': { status: 'failed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+    'The page structure agrees with the run log: the page holds it, but the screenshot does not show it.': { status: 'contradiction', resolution: 'the page structure agrees with the run log: the page holds it but does not display it, a likely rendering bug' },
+};
 export class Pilot {
     emoji = '🧭';
     provider;
@@ -544,7 +549,7 @@ export class Pilot {
             settledByJudge = await this.settleByJudge(task, undecided);
         undecided = undecided.filter((text) => !settledByJudge.has(text));
         if (!undecided.length)
-            return task.expected.map((text) => ({ text, status: settledByJudge.get(text) || decided(text) }));
+            return task.expected.map((text) => new SettledExpectation(text, settledByJudge.get(text) || decided(text)));
         const schema = z.object({
             outcomes: z.array(z.object({
                 expectation: z.string().describe('The expected outcome, repeated exactly as it was given'),
@@ -607,17 +612,39 @@ export class Pilot {
         if (!response)
             response = await settle(userContent, this.provider.getAgenticModel('pilot'));
         const judged = new Map((response?.object?.outcomes || []).map((outcome) => [outcome.expectation, outcome]));
-        return task.expected.map((text) => {
+        const settled = task.expected.map((text) => {
             const byJudge = settledByJudge.get(text);
             if (byJudge)
-                return { text, status: byJudge };
+                return new SettledExpectation(text, byJudge);
             if (!undecided.includes(text))
-                return { text, status: decided(text) };
+                return new SettledExpectation(text, decided(text));
             const outcome = judged.get(text);
             if (!outcome)
-                return { text, status: 'unverified' };
-            return { text, status: outcome.status || 'unverified', evidence: outcome.evidence };
+                return new SettledExpectation(text, 'unverified');
+            return new SettledExpectation(text, outcome.status || 'unverified', outcome.evidence);
         });
+        return this.resolveContradictions(settled, finalState);
+    }
+    async resolveContradictions(outcomes, finalState) {
+        const judge = this.judge;
+        if (!judge || !finalState)
+            return outcomes;
+        if (!outcomes.some((outcome) => outcome.contradicted))
+            return outcomes;
+        const page = finalState.getCompactARIA().slice(0, JUDGE_PAGE_CAP);
+        return Promise.all(outcomes.map(async (outcome) => {
+            if (!outcome.contradicted)
+                return outcome;
+            const decision = await judge.decide(`The screenshot and the run log disagree about the expected outcome: ${outcome.text}. Which side does the page structure support?`, [...Object.keys(CONTRADICTION_RESOLUTION), UNDECIDED], {
+                expectation: outcome.text,
+                disagreement: outcome.evidence || '',
+                page,
+            });
+            const resolved = CONTRADICTION_RESOLUTION[decision.value ?? ''];
+            if (!resolved)
+                return outcome;
+            return outcome.resolve(resolved.status, resolved.resolution);
+        }));
     }
     async settleByJudge(task, expectations) {
         const settled = new Map();

package/dist/src/ai/researcher.js

@@ -77,7 +77,7 @@ export class Researcher extends ResearcherBase {
     `;
     }
     async research(state, opts = {}) {
-        const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
+        const { screenshot = false, force = false, deep = false, data = false, fix = true, light = false } = opts;
         const maxRetries = this.settings.retries ?? 2;
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
@@ -103,6 +103,8 @@ export class Researcher extends ResearcherBase {
         return Observability.run(sessionName, { tags: ['researcher'], sessionId: stateHash }, async () => {
             const displayUrl = state.fullUrl || state.url;
             tag('info').log(`Researching ${displayUrl} to understand the context...`);
+            if (light)
+                tag('info').log('Light research: single pass, locator verification skipped');
             setActivity(`${this.emoji} Researching...`, 'action');
             await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
             await this.hooksRunner.runBeforeHook('researcher', state.url);
@@ -135,7 +137,7 @@ export class Researcher extends ResearcherBase {
                 }
             }
             const isOnCurrentState = this.actionResult.getStateHash() === this.stateManager.getCurrentState()?.hash;
-            this.hasScreenshotToAnalyze = screenshot && this.provider.hasVision() && isOnCurrentState;
+            this.hasScreenshotToAnalyze = !light && screenshot && this.provider.hasVision() && isOnCurrentState;
             const conversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
             const prompt = await this.buildResearchPrompt();
             conversation.addUserText(prompt);
@@ -164,12 +166,12 @@ export class Researcher extends ResearcherBase {
             // Stage 2: Test containers + locators
             result.parseLocators();
             debugLog(`Extracted ${result.locators.length} locators from research`);
-            if (!interrupted() && result.locators.length === 0 && retriesLeft > 0) {
+            if (!light && !interrupted() && result.locators.length === 0 && retriesLeft > 0) {
                 tag('warning').log(`No locators parsed, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
                 await new Promise((r) => setTimeout(r, 1000));
                 return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 });
             }
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 const brokenContainers = await this.resolveContainers(result);
                 const containerCount = result.containers.length;
                 if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
@@ -187,7 +189,7 @@ export class Researcher extends ResearcherBase {
                 await this.testLocators(toTest);
             }
             // Stage 3: Fix broken sections via AI conversation continuation
-            if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
+            if (!light && !interrupted() && fix && result.locators.some((l) => l.valid === false)) {
                 await this.fixBrokenSections(result, activeConversation);
             }
             // Focused section: unified Playwright probe (HTML+CSS+visibility).
@@ -227,11 +229,11 @@ export class Researcher extends ResearcherBase {
                 }
             }
             // Stage 5: Backfill broken elements
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 await this.backfillCoordinates(result);
                 await this.backfillBrokenLocators(result);
             }
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 await this.detectPagination(result);
             }
             // Focused section: final fallback (vision-only — without a screenshot we don't infer focus)
@@ -258,7 +260,7 @@ export class Researcher extends ResearcherBase {
             }
             result.cleanup();
             let researchFile = null;
-            if (stateHash) {
+            if (stateHash && !light) {
                 researchFile = saveResearch(researchState, result.text, combinedHtml);
             }
             const summaryText = mdq(result.text).query('section2(/^summary/i)').query('paragraph[0]').text().trim();

package/dist/src/ai/tools.js

@@ -91,7 +91,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                 const attempts = [];
                 let ambiguityError = null;
                 for (let i = 0; i < commands.length; i++) {
-                    const command = transformContainsCommand(commands[i]);
+                    let command = transformContainsCommand(commands[i]);
                     let success = await action.attempt(command, explanation);
                     const attempt = { command, success };
                     if (action.lastError)
@@ -104,9 +104,14 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                             const index = await judge.pick(PICK_ELEMENT_QUESTION, labels, { intent: explanation, task: task.description });
                             if (index)
                                 success = await action.attemptExactElementIndex(command, index, explanation);
+                            if (success)
+                                command = action.executedSteps.map((step) => step.command).join('\n') || command;
                         }
                     }
                     if (success) {
+                        attempt.command = command;
+                        attempt.success = true;
+                        attempt.error = undefined;
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
                         if (!hasObservablePageChange(toolResult)) {
                             activeNote.commit(TestResult.FAILED);

package/dist/src/explorbot.js

@@ -125,7 +125,7 @@ export class ExplorBot {
         await this.visit(this.options.from || '/');
     }
     async visit(url) {
-        return this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
+        await this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
     }
     async openTab() {
         await this.explorer.openTab();

package/dist/src/test-plan.d.ts

@@ -33,6 +33,17 @@ export declare class ActiveNote {
     getMessage(): string;
     getStartTime(): number;
 }
+export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
+export declare class SettledExpectation {
+    readonly text: string;
+    readonly status: SettledStatus;
+    readonly evidence?: string;
+    readonly resolution?: string;
+    constructor(text: string, status: SettledStatus, evidence?: string, resolution?: string);
+    get failed(): boolean;
+    get contradicted(): boolean;
+    resolve(status: SettledStatus, resolution: string): SettledExpectation;
+}
 export interface StepData {
     text: string;
     duration?: number;

package/dist/src/test-plan.js

@@ -41,6 +41,27 @@ export class ActiveNote {
         return this.startTime;
     }
 }
+export class SettledExpectation {
+    text;
+    status;
+    evidence;
+    resolution;
+    constructor(text, status, evidence, resolution) {
+        this.text = text;
+        this.status = status;
+        this.evidence = evidence;
+        this.resolution = resolution;
+    }
+    get failed() {
+        return this.status === 'failed';
+    }
+    get contradicted() {
+        return this.status === 'contradiction';
+    }
+    resolve(status, resolution) {
+        return new SettledExpectation(this.text, status, this.evidence, resolution);
+    }
+}
 export class Task {
     id;
     description;

package/dist/src/utils/code-extractor.d.ts

@@ -1 +1,2 @@
 export declare function extractCodeBlocks(aiResponse: string): string[];
+export declare function splitTopLevel(code: string, separator: string): string[];

package/dist/src/utils/code-extractor.js

@@ -1,6 +1,9 @@
 import { createDebug } from './logger.js';
 const debugLog = createDebug('explorbot:code-extractor');
 const JS_LANGUAGES = new Set(['', 'js', 'javascript']);
+const QUOTES = ["'", '"', '`'];
+const OPENING_BRACKETS = ['(', '[', '{'];
+const CLOSING_BRACKETS = [')', ']', '}'];
 export function extractCodeBlocks(aiResponse) {
     const codeBlockRegex = /```([^\n`]*)\n([\s\S]*?)\n```/g;
     const codeBlocks = [];
@@ -22,3 +25,40 @@ export function extractCodeBlocks(aiResponse) {
     }
     return codeBlocks;
 }
+export function splitTopLevel(code, separator) {
+    const parts = [];
+    let current = '';
+    let depth = 0;
+    let quote = '';
+    for (let i = 0; i < code.length; i++) {
+        const char = code[i];
+        if (quote) {
+            current += char;
+            if (char === '\\')
+                current += code[++i] || '';
+            if (char === quote)
+                quote = '';
+            continue;
+        }
+        if (char === '/' && code[i + 1] === '/') {
+            while (i + 1 < code.length && code[i + 1] !== '\n')
+                i++;
+            continue;
+        }
+        if (char === separator && depth <= 0) {
+            parts.push(current);
+            current = '';
+            depth = 0;
+            continue;
+        }
+        current += char;
+        if (QUOTES.includes(char))
+            quote = char;
+        if (OPENING_BRACKETS.includes(char))
+            depth++;
+        if (CLOSING_BRACKETS.includes(char))
+            depth--;
+    }
+    parts.push(current);
+    return parts;
+}

package/dist/src/utils/html.d.ts

@@ -5,6 +5,7 @@ export declare const EXPLORBOT_ATTRS: {
     readonly coveredBy: "data-explorbot-covered-by";
     readonly context: "data-explorbot-context";
     readonly eidx: "data-explorbot-eidx";
+    readonly hidden: "data-explorbot-hidden";
     readonly hit: "data-explorbot-hit";
     readonly variant: "data-explorbot-variant";
 };
@@ -40,6 +41,7 @@ export declare const ELEMENT_EXTRACTION_CONFIG: {
         readonly coveredBy: "data-explorbot-covered-by";
         readonly context: "data-explorbot-context";
         readonly eidx: "data-explorbot-eidx";
+        readonly hidden: "data-explorbot-hidden";
         readonly hit: "data-explorbot-hit";
         readonly variant: "data-explorbot-variant";
     };

package/dist/src/utils/html.js

@@ -70,6 +70,7 @@ export const EXPLORBOT_ATTRS = {
     coveredBy: 'data-explorbot-covered-by',
     context: 'data-explorbot-context',
     eidx: 'data-explorbot-eidx',
+    hidden: 'data-explorbot-hidden',
     hit: 'data-explorbot-hit',
     variant: 'data-explorbot-variant',
 };
@@ -159,6 +160,20 @@ export function captureHtmlForSnapshot() {
                 .join(','));
         }
     }
+    const liveElements = Array.from(document.body?.querySelectorAll('*') || []);
+    const clonedElements = Array.from(clone.querySelector('body')?.querySelectorAll('*') || []);
+    for (let i = 0; i < liveElements.length; i++) {
+        const source = liveElements[i];
+        if (source.matches('input, textarea, select, option, optgroup'))
+            continue;
+        if (source.checkVisibility())
+            continue;
+        if (!source.parentElement?.checkVisibility())
+            continue;
+        if (getComputedStyle(source).display === 'contents')
+            continue;
+        clonedElements[i]?.setAttribute('data-explorbot-hidden', 'true');
+    }
     return clone.outerHTML;
 }
 export function extractElementData(el, config) {
@@ -1347,7 +1362,27 @@ function getAttribute(element, name) {
     const attr = element.attrs.find((a) => a.name === name);
     return attr?.value;
 }
+function getImgAlt(element) {
+    let alt = '';
+    function processNode(node) {
+        if (alt)
+            return;
+        if ('tagName' in node) {
+            const el = node;
+            if (el.tagName.toLowerCase() === 'img') {
+                alt = getAttribute(el, 'alt') || '';
+                return;
+            }
+        }
+        if ('childNodes' in node)
+            node.childNodes.forEach(processNode);
+    }
+    processNode(element);
+    return alt;
+}
 function hasHiddenClass(element) {
+    if (getAttribute(element, EXPLORBOT_ATTRS.hidden))
+        return true;
     const classAttr = element.attrs.find((attr) => attr.name === 'class');
     if (!classAttr)
         return false;
@@ -1393,7 +1428,7 @@ export function extractLinks(html) {
                 if (href) {
                     const shouldSkip = skipPrefixes.some((prefix) => href.startsWith(prefix));
                     if (!shouldSkip) {
-                        const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element);
+                        const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element) || getImgAlt(element);
                         const title = sanitizeLinkTitle(rawTitle);
                         if (title && title.length <= 100) {
                             const key = `${href}|${title}`;

package/dist/src/utils/mdq/cli.js

@@ -5,7 +5,7 @@ const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend
 export async function runMdq(argv, readStdin) {
     const program = new Command();
     program
-        .name('mdq')
+        .name('mdq-cli')
         .description('query and edit markdown')
         .argument('[selector]', 'markdown selector')
         .argument('[file]', 'file to read; stdin when omitted')
@@ -29,6 +29,8 @@ export async function runMdq(argv, readStdin) {
         program.parse(argv, { from: 'user' });
     }
     catch (error) {
+        if (error.code === 'commander.helpDisplayed')
+            return { output: program.helpInformation(), code: 0 };
         return { output: String(error.message), code: 2 };
     }
     const options = program.opts();

package/dist/src/utils/web-sandbox.js

@@ -1,16 +1,16 @@
 import { faker } from '@faker-js/faker';
 import { hopeThat, retryTo, tryTo, within } from 'codeceptjs/lib/effects';
 import step from 'codeceptjs/steps';
+import { splitTopLevel } from "./code-extractor.js";
 const SHADOWED_GLOBALS = ['process', 'global', 'globalThis', 'fetch', 'Bun', 'require', 'module', 'exports'];
 const ALLOWED_COMMAND_HEADS = ['I.', 'page.', 'await page.', 'await I.'];
 const PLAYWRIGHT_COMMAND_HEADS = ['page.', 'await page.'];
 const PLAYWRIGHT_ARG_NAMES = ['page'];
 const CODECEPT_ARG_NAMES = ['I', 'tryTo', 'retryTo', 'within', 'hopeThat', 'step', 'faker'];
 export function sanitizeCodeBlock(code) {
-    return code
-        .split('\n')
-        .map((line) => line.trim())
-        .filter((line) => ALLOWED_COMMAND_HEADS.some((head) => line.startsWith(head)))
+    return splitTopLevel(code, '\n')
+        .map((statement) => statement.trim())
+        .filter((statement) => ALLOWED_COMMAND_HEADS.some((head) => statement.startsWith(head)))
         .join('\n');
 }
 export function hasPlaywrightCommands(code) {

package/docs/doc-collection/basics.md

@@ -21,6 +21,19 @@ The collector starts at the path you give it. For each page it:
 
 It repeats this until the queue is empty or the page budget is spent. Only same-origin links are followed.
 
+## Research depth
+
+In static mode the Researcher runs in a **light, single pass**: one AI call maps the sections and interactive elements, and the locator validation, repair conversations, and screenshot annotation passes of a full research run are skipped. Docs describe pages rather than click them, so unverified locators are a fair trade for roughly one AI call per page.
+
+Interactive mode needs locators it can actually click, so it keeps the full pipeline: every locator is validated in the browser, broken ones get fixed, and a vision pass adds coordinates. Override the automatic choice with `research`:
+
+```ts
+docs: {
+  research: 'full', // always run the verified pipeline
+  // research: 'light', // single pass even in interactive mode
+}
+```
+
 ## Configure
 
 The collector runs on your regular Explorbot setup — the AI provider and browser come from `explorbot.config.js` (see [configuration](../reference/configuration.md)). Crawl behavior lives in a separate file: `docbot.config.ts` (`.js` and `.mjs` work too).

package/docs/web-testing/researcher.md

@@ -155,6 +155,14 @@ Expands hidden elements (dropdowns, accordions, tabs) to discover more UI. Click
 
 Extracts domain-specific content (articles, products, users) as structured data.
 
+#### Light Research
+
+```ts
+researcher.research(state, { light: true });
+```
+
+A single-pass mode for consumers that describe pages instead of acting on them. Stage 1 runs as usual; stages 2–5 (locator testing, AI fixing, the visual annotation pass, backfills, and pagination probing) are skipped, so the whole run is one AI call with no browser verification roundtrips. Locators in the UI map come straight from the model and are not verified; a light run never writes to the shared research cache, so it cannot replace a verified result. The [doc collector](../doc-collection/basics.md#research-depth) uses this mode by default.
+
 ## Page Sections
 
 The Researcher breaks each page into sections by UI purpose. Sections are identified in priority order:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/rules/navigator/output.md

@@ -1,11 +1,11 @@
 <rules>
-Do not invent locators, focus only on locators from HTML PAGE.
+Do not invent locators, focus only on locators from the <page> context.
 Provide up to {{maxAttempts}} various code suggestions to achieve the result.
 If there was already successful solution in <experience> use it as a first solution.
 
 If no successful solution was found in <experience> propose codeblocks for each area that can help to achieve the result.
 Do not stick only to the first found element as it might be hidden or not availble on the page.
-If you think HTML contains several areas that can help to achieve the result, propose codeblocks for each such area.
+If you think the page contains several areas that can help to achieve the result, propose codeblocks for each such area.
 Use exact locators that can pick the elements from each areas.
 Detect such duplicated areas by looking for duplicate IDs, data-ids, forms, etc.
 
@@ -24,7 +24,7 @@ Your response must start explanation of what you are going to do to achive the r
 It is important to explain intention before proposing code.
 Response must also valid CodeceptJS code in code blocks.
 Propose codeblock from successful solutions in <experience> first if they exist.
-Use only locators from HTML PAGE that was passed in <page> context.
+Use only locators from the <page> context.
 </output>
 
 

package/src/action.ts

@@ -589,6 +589,10 @@ export const attachStepLogger = (target: ExecutedStep[], assertionsTarget?: Arra
     if (batchFailed) return;
 
     const executed: ExecutedStep = { command: step.toCode(), success: !error };
+    if (Object.keys(step.opts || {}).length) {
+      const args = [step.humanizeArgs(), `step.opts(${JSON.stringify(step.opts)})`].filter(Boolean).join(', ');
+      executed.command = `${step.prefix}${step.actor}.${step.title}(${args})${step.suffix}`;
+    }
     if (error) {
       executed.error = errorToString(error);
       batchFailed = true;

package/src/ai/driller.ts

@@ -6,6 +6,7 @@ import { setActivity } from '../activity.ts';
 import { Observability } from '../observability.ts';
 import { Plan, Test, TestResult } from '../test-plan.ts';
 import { collectInteractiveNodes } from '../utils/aria.ts';
+import { splitTopLevel } from '../utils/code-extractor.ts';
 import { EXPLORBOT_ATTRS, HTML_COMPOSITE_AREA_HINTS, HTML_COMPOSITE_TARGET_ROLES, HTML_EXTRACTION_LIMITS, HTML_FORM_CONTROL_ROLES, HTML_FORM_CONTROL_TAGS, HTML_INTERACTIVE_ROLES, HTML_SELECTORS, getComponentScopeHtmlExtractorSource, inferHtmlRole } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop, pause } from '../utils/loop.ts';
@@ -1011,39 +1012,7 @@ function countTopLevelArgCount(line: string): number {
   const end = line.lastIndexOf(')');
   if (start === -1 || end === -1 || end <= start + 1) return 0;
 
-  const body = line.slice(start + 1, end);
-  let count = 1;
-  let depth = 0;
-  let quote = '';
-
-  for (let i = 0; i < body.length; i++) {
-    const char = body[i];
-    const escaped = body[i - 1] === '\\';
-
-    if (quote) {
-      if (char === quote && !escaped) quote = '';
-      continue;
-    }
-
-    if (char === '"' || char === "'" || char === '`') {
-      quote = char;
-      continue;
-    }
-
-    if (char === '(' || char === '[' || char === '{') {
-      depth++;
-      continue;
-    }
-
-    if (char === ')' || char === ']' || char === '}') {
-      depth = Math.max(0, depth - 1);
-      continue;
-    }
-
-    if (char === ',' && depth === 0) count++;
-  }
-
-  return count;
+  return splitTopLevel(line.slice(start + 1, end), ',').length;
 }
 
 function buildClassSelector(tag: string, classes: string[]): string {

package/src/ai/navigator.ts

@@ -136,11 +136,11 @@ class Navigator implements Agent {
     return matchesNavigationUrl(expectedUrl, currentUrl);
   }
 
-  async visit(url: string): Promise<void> {
-    return this.visitOnce(url);
+  async visit(url: string, opts: { recover?: boolean } = {}): Promise<boolean> {
+    return this.visitOnce(url, opts.recover !== false);
   }
 
-  private async visitOnce(url: string): Promise<void> {
+  private async visitOnce(url: string, recover: boolean): Promise<boolean> {
     try {
       const action = this.explorer.action();
 
@@ -153,7 +153,10 @@ class Navigator implements Agent {
 
       await this.hooksRunner.runBeforeHook('navigator', url);
 
-      if (!this.isOnExpectedPage(url, action.stateManager)) {
+      if (!recover && action.lastError) throw new Error(`Navigation to ${url} failed: ${action.lastError.message}`);
+
+      const arrived = this.isOnExpectedPage(url, action.stateManager);
+      if (recover && !arrived) {
         const actualPath = action.stateManager.getCurrentState()?.url || '';
         const actionResult = action.actionResult || ActionResult.fromState(action.stateManager.getCurrentState()!);
         const originalMessage = `Navigate to: ${url}. Current page: ${actualPath}`;
@@ -177,6 +180,7 @@ class Navigator implements Agent {
       }
       await this.explorer.capture({ screenshot: true });
       await this.hooksRunner.runAfterHook('navigator', url);
+      return arrived || recover;
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       if (errorMessage.includes('ERR_CONNECTION_REFUSED')) {
@@ -284,7 +288,7 @@ class Navigator implements Agent {
             return;
           }
           tag('operation').log('Feeding failures back to AI for a new batch...');
-          conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, actionResult));
+          conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, action.actionResult ?? actionResult));
           htmlContextAdded = true;
           codeBlocks = [];
           batchFailures.length = 0;
@@ -384,10 +388,6 @@ class Navigator implements Agent {
 
       <page>
         ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.combinedHtml()}
-        </page_html>
       </page>
 
       <task>
@@ -397,6 +397,8 @@ class Navigator implements Agent {
         Propose different solutions to achieve the result.
         Solution should be valid CodeceptJS code.
         Use only data from the <page> context to plan the solution.
+        The page is given as an ARIA snapshot only: use ARIA and text locators from it.
+        Full HTML is provided if these solutions fail.
         Try various ways to achieve the result
       </task>
 
@@ -813,7 +815,9 @@ class Navigator implements Agent {
 
           const verified = await action.attempt(codeBlock, message);
           const proof = action.assertionSteps.map(renderAssertion).filter(Boolean);
-          results.push({ code: codeBlock, passed: verified, proof });
+          const result: AssertionResult = { code: codeBlock, passed: verified, proof };
+          if (!verified && action.lastError) result.error = action.lastError.message;
+          results.push(result);
 
           if (verified) {
             tag('success').log('Verification passed');
@@ -862,6 +866,6 @@ class Navigator implements Agent {
 
 type BatchFailure = { code: string; error: string; ariaChanges?: string | null; urlAfter?: string };
 
-export type AssertionResult = { code: string; passed: boolean; proof: string[] };
+export type AssertionResult = { code: string; passed: boolean; proof: string[]; error?: string };
 
 export { Navigator };