explorbot 0.1.12 → 0.1.13

package/dist/src/ai/pilot.js

@@ -69,16 +69,17 @@ export class Pilot {
         const stateContext = this.buildStateContext(currentState);
         const notes = task.notesToString() || 'No notes recorded.';
         let visualAnalysis = '';
+        let screenshotState = null;
         if (this.provider.hasVision()) {
             try {
                 const action = this.explorer.createAction();
-                const screenshotState = await action.caputrePageWithScreenshot();
+                screenshotState = await action.caputrePageWithScreenshot();
                 if (screenshotState.screenshot) {
                     visualAnalysis = (await this.researcher.answerQuestionAboutScreenshot(screenshotState, `Describe current page state relevant to: ${task.scenario}`)) || '';
                 }
             }
             catch {
-                // vision not available, continue without
+                screenshotState = null;
             }
         }
         const schema = z.object({
@@ -140,28 +141,24 @@ export class Pilot {
                 task.finish(TestResult.FAILED);
                 return false;
             }
-            if (result.requestVerification && navigator) {
+            if (result.decision === 'pass' && result.requestVerification && navigator) {
                 tag('substep').log(`Pilot requesting verification: ${result.requestVerification}`);
-                try {
-                    const verifyResult = await navigator.verifyState(result.requestVerification, currentState);
-                    if (verifyResult.verified) {
-                        if (verifyResult.assertionSteps?.length) {
-                            this.explorer.getPlaywrightRecorder().recordVerification(verifyResult.assertionSteps);
-                        }
-                        tag('substep').log(`Pilot verified: ${result.requestVerification}`);
-                    }
-                    else {
-                        tag('substep').log(`Pilot verification failed: ${result.requestVerification}`);
-                        if (result.decision === 'pass') {
-                            const flipMessage = `Verification "${result.requestVerification}" did not match the page. Adjust approach and re-verify before finishing.`;
-                            result.decision = 'continue';
-                            result.reason = flipMessage;
-                            result.guidance = result.guidance ?? flipMessage;
-                        }
+                const verifyResult = await navigator.verifyState(result.requestVerification, currentState).catch(() => null);
+                if (verifyResult?.verified) {
+                    if (verifyResult.assertionSteps?.length) {
+                        this.explorer.getPlaywrightRecorder().recordVerification(verifyResult.assertionSteps);
                     }
                 }
-                catch (verifyErr) {
-                    tag('warning').log(`Pilot verification errored: ${verifyErr.message}`);
+                else {
+                    let answer = null;
+                    if (screenshotState?.screenshot) {
+                        answer = await this.researcher.answerQuestionAboutScreenshot(screenshotState, `Does the screen confirm: "${result.requestVerification}"? Answer YES or NO only.`);
+                    }
+                    if (!(answer || '').trim().toUpperCase().startsWith('YES')) {
+                        task.addNote(`Pilot: verification failed — ${result.requestVerification}`, TestResult.FAILED);
+                        task.finish(TestResult.FAILED);
+                        return false;
+                    }
                 }
             }
             tag('info').log(`Pilot: ${result.decision} — ${result.reason}`);
@@ -348,6 +345,8 @@ export class Pilot {
       - If no verification was done → prefer "continue" with guidance telling tester what to verify.
       - If verify assertion describes a state that was ALREADY TRUE before the test started, the verification proves nothing — reject with "continue".
 
+      requestVerification — pick assertions DOM can actually express. Some content is not assertable via DOM (iframe text, canvas, custom widgets, Monaco/CodeMirror editors). When the scenario goal lives in such a region, target a STABLE LANDMARK (container element, ARIA role, the parent that wraps the widget) rather than literal text inside it. Your "pass" verdict is honored even if the DOM assertion can't be made — pick the strongest landmark you can.
+
       GUIDANCE FIELD: When decision is "continue", you MUST provide "guidance" — a specific actionable instruction:
       - If evidence is insufficient: tell tester to verify with see()/verify(), specify WHAT to check
       - If approach was wrong: tell tester to try a different method, suggest which one
@@ -420,7 +419,7 @@ export class Pilot {
         Be concise and specific. Tester will follow your plan.
       `, 'pilot.planTest', { tools: true, planningOnly: true, maxToolRoundtrips: 3, task });
     }
-    async reviewNewPage(task, currentState) {
+    async reviewNewPage(task, currentState, testerConversation) {
         if (!this.conversation)
             return '';
         tag('substep').log('Pilot reviewing new page...');
@@ -430,7 +429,13 @@ export class Pilot {
         if (!pageSummary)
             return '';
         const stateContext = this.buildStateContext(currentState);
+        const toolCalls = testerConversation
+            .getToolExecutions()
+            .filter((t) => t.wasSuccessful)
+            .slice(-this.stepsToReview);
+        const actionsContext = this.formatActions(toolCalls);
         this.conversation.cleanupTag('page_summary', '...trimmed...', 1);
+        this.conversation.cleanupTag('recent_actions', '...trimmed...', 2);
         return this.sendToPilot(dedent `
         Navigated to new page.
         START URL: ${task.startUrl}
@@ -443,6 +448,10 @@ export class Pilot {
         ${pageSummary}
         </page_summary>
 
+        <recent_actions>
+        ${actionsContext || 'None'}
+        </recent_actions>
+
         ${this.formatExpectations(task)}
 
         First: evaluate whether this navigation makes sense for the scenario goal. If the page is unrelated, instruct Tester to back() or reset(). Then plan next steps.

package/dist/src/ai/rules.js

@@ -272,11 +272,9 @@ export const actionRule = dedent `
     I.fillField('Description', 'Hello world', '.editor'); // works for rich text / code editors too
   </example>
 
-  I.fillField handles plain inputs, textareas, contenteditable regions, and rich text / code editors
-  (Monaco, ProseMirror, CodeMirror, TipTap, Quill, Draft.js, Slate, etc.) transparently.
-  ALWAYS use I.fillField for rich editors — target the editor container or its nearest label/heading with a normal locator.
-  Do NOT open the editor with raw JS (executeScript, page.evaluate), do NOT dispatch synthetic events,
-  do NOT call the editor's own API (monaco.editor.setValue, view.dispatch, etc.) to write text.
+  I.fillField handles plain inputs, textareas, contenteditable regions, and rich text / code editors transparently.
+  ALWAYS use I.fillField for rich text / code editors — target the editor container or its nearest label/heading with a normal locator.
+  If I.fillField does not work, I.type into the focused element is the fallback.
 
   ### I.type
 

package/dist/src/ai/session-analyst.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import dedent from 'dedent';
+import { outputPath } from "../config.js";
+import { Stats } from "../stats.js";
+export class SessionAnalyst {
+    emoji = '🧐';
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async analyze(tests) {
+        const eligible = tests.filter((t) => t.startTime != null);
+        if (eligible.length === 0)
+            return '';
+        const model = this.provider.getModelForAgent('analyst');
+        const customPrompt = this.provider.getSystemPromptForAgent('analyst', undefined);
+        const systemPrompt = dedent `
+      You write a brief end-of-session report after autonomous exploratory testing. Your reader is a developer who needs to know in seconds: what is broken, how to reproduce it, and which results were inconclusive.
+
+      Output MARKDOWN. No JSON, no preamble, no closing remarks. Start with the heading.
+
+      ## Clustering
+      Group by ROOT CAUSE, not by scenario. If three tests fail for the same dropdown, that is ONE defect listing all three test refs (#3, #5, #7). Do not produce one cluster per test.
+
+      ## Bucketing
+      Use the FINAL verdict (the test's \`result\` field) as the starting point. Mid-test errors that the automation recovered from do NOT make a passed test unreliable.
+
+      - **Defect** — real product bug. \`result: failed\` AND the failure reflects the app misbehaving (not the automation). The automation completed its interactions, the app contradicted the expected outcome. Severity required.
+      - **UX issue** — app works but the UI is ambiguous, controls are hidden, or labels are unclear. Worth flagging to design.
+      - **Execution issue** — the FINAL verdict is unreliable. Only two cases:
+        1. \`result: failed\` AND the failure was automation, environment, or UI/UX (locator missing, timeout, AI loop, navigation stuck, modal trapped focus, no accessible label) — i.e. the test could not conclude whether the app works.
+        2. \`result: passed\` AND clear evidence in the log shows the user-visible goal was NOT achieved (no confirmation visible, no state change verified, the assertion was vacuous).
+
+      A test that passed and shows no contrary evidence belongs in NO section. Do not list passed tests just because the log contains intermediate retries or recovered failures.
+
+      ## Severity emoji (defects only)
+      - 🔴 critical or high — core flow blocked, data loss, security
+      - 🟡 medium — partial breakage with workaround
+      - 🟢 low — cosmetic
+
+      ## Required format
+
+      # Session Analysis
+
+      <one sentence: total tests, defect count, headline finding>
+
+      ## Defects
+
+      ### 🔴 <plain-English title of the BUG, not the scenario name>
+      Affects: #3, #5, #7
+      Reproduce:
+        1. <concrete UI step a person can replay>
+        2. <next step>
+      Evidence: <one short observation from the test log>
+
+      ### 🟡 <next defect>
+      ...
+
+      ## UX issues
+
+      - **<title>** — #4
+        <one short evidence line>
+
+      ## Execution Issues
+
+      - **<short test name or scenario phrase>** — <plain-English one-liner: what made the result unreliable>
+      - **<…>** — <…>
+
+      ## Rules
+      - Defects first, sorted by severity descending. Omit any section that has zero entries.
+      - Defect title describes the BUG ("Run-type dropdown does not filter"), never the scenario name.
+      - Reproduce steps are concrete UI actions derived from the log: URL + clicks + inputs. Imperative, one short line each.
+      - Evidence is the smallest factual observation from notes/steps that supports the claim — what was OBSERVED in the page (HTML, message, missing element). Never quote the test's \`result\` field as evidence; that is a tautology.
+      - **Execution Issues** entries must explain what actually went wrong in concrete terms a human understands: "could not find a Submit button after navigation", "page reloaded before the assertion ran", "passed without ever seeing a confirmation message", "marked failed but the new item appears in the list", "modal trapped focus and tests could not click outside", "ARIA tree had no labelled controls". Avoid jargon like "locator failed" without context. Never write category prefixes ("execution:", "false-positive:") — the section header already says it. No emoji on these entries.
+      - Do NOT include a passed test in any section unless evidence proves its goal was not achieved. Intermediate retries or recovered errors in the log are not grounds for listing a passed test.
+      - No editorialising, no restating the scenario verbatim, no closing summary.
+
+      ${customPrompt || ''}
+    `;
+        const userPayload = dedent `
+      ${eligible.length} tests were executed in this session.
+
+      ${eligible.map((t, i) => this.serializeTest(t, i + 1)).join('\n\n')}
+    `;
+        const response = await this.provider.chat([
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userPayload },
+        ], model, { agentName: 'analyst' });
+        return (response?.text || '').trim();
+    }
+    writeReport(markdown) {
+        const filePath = outputPath('reports', `${Stats.sessionLabel()}.md`);
+        const dir = path.dirname(filePath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(filePath, markdown);
+        return filePath;
+    }
+    serializeTest(test, ref) {
+        const log = test
+            .getLog()
+            .slice(-30)
+            .map((entry) => `  - [${entry.type}] ${entry.content}`)
+            .join('\n');
+        return dedent `
+      <test ref="#${ref}">
+      url: ${test.startUrl || '/'}
+      scenario: ${test.scenario}
+      result: ${test.result || 'unknown'}
+      expected: ${test.expected.join(' | ') || '(none)'}
+      log:
+      ${log}
+      </test>
+    `;
+    }
+}

package/dist/src/ai/tester.js

@@ -216,7 +216,7 @@ export class Tester extends TaskAgent {
                     nextStep += await this.reinjectContextIfNeeded(iteration, currentState);
                     nextStep += await this.prepareInstructionsForNextStep(task);
                     if (isNewPage && this.pilot) {
-                        const guidance = await this.pilot.reviewNewPage(task, currentState);
+                        const guidance = await this.pilot.reviewNewPage(task, currentState, conversation);
                         if (guidance)
                             nextStep += `\n\n${guidance}`;
                     }
@@ -388,6 +388,7 @@ export class Tester extends TaskAgent {
         this.previousUrl = currentUrl;
         this.previousStateHash = currentStateHash;
         let context = '';
+        const focusArea = detectFocusArea(currentState.ariaSnapshot);
         const focusedElement = extractFocusedElement(currentState.ariaSnapshot);
         if (focusedElement) {
             const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
@@ -403,6 +404,17 @@ export class Tester extends TaskAgent {
         <no_focus>
         No element is focused
         </no_focus>
+      `;
+        }
+        if (focusArea.detected) {
+            const areaName = focusArea.name ? ` "${focusArea.name}"` : '';
+            context += dedent `
+        <focus_scope>
+        A ${focusArea.type}${areaName} is currently open above the page.
+        Scope all interactions to elements inside this ${focusArea.type}.
+        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the ${focusArea.type}.
+        Use <page_aria> to confirm the element you target is actually inside the ${focusArea.type}.
+        </focus_scope>
       `;
         }
         if (currentState.isInsideIframe) {
@@ -462,7 +474,6 @@ export class Tester extends TaskAgent {
       `;
             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) {

package/dist/src/commands/base-command.js

@@ -19,17 +19,17 @@ export class BaseCommand {
         if (this.suggestions.length === 0)
             return;
         const prefix = isInteractive() ? '/' : `${getCliName()} `;
-        tag('info').log('');
-        tag('info').log(chalk.bold('Suggested:'));
+        const commandWidth = this.suggestions.reduce((max, s) => (s.command ? Math.max(max, prefix.length + s.command.length) : max), 0);
+        const lines = [chalk.bold('Suggested:')];
         for (const { command, hint } of this.suggestions) {
-            tag('info').log('');
             if (!command) {
-                tag('info').log(chalk.dim(hint));
+                lines.push(`  ${chalk.dim(hint)}`);
                 continue;
             }
-            tag('info').log(chalk.dim(`${hint}:`));
-            tag('info').log(`  ${chalk.yellow(`${prefix}${command}`)}`);
+            const cmd = `${prefix}${command}`.padEnd(commandWidth);
+            lines.push(`  ${chalk.yellow(cmd)}  ${chalk.dim(hint)}`);
         }
+        tag('info').log(lines.join('\n'));
     }
     parseArgs(args) {
         const cmd = new Command();

package/dist/src/commands/drill-command.js

@@ -2,6 +2,7 @@ import { BaseCommand } from './base-command.js';
 export class DrillCommand extends BaseCommand {
     name = 'drill';
     description = 'Drill all components on current page to learn interactions';
+    aliases = ['driller'];
     suggestions = [
         { command: 'research', hint: 'see UI map first' },
         { command: 'navigate <page>', hint: 'go to another page' },
@@ -13,7 +14,7 @@ export class DrillCommand extends BaseCommand {
         if (!state) {
             throw new Error('No active page to drill');
         }
-        await this.explorBot.agentBosun().drill({
+        await this.explorBot.agentDriller().drill({
             knowledgePath,
             maxComponents,
             interactive: true,
@@ -24,7 +25,7 @@ export class DrillCommand extends BaseCommand {
         return match ? match[1] : undefined;
     }
     parseMaxArg(args) {
-        const match = args.match(/--max\s+(\d+)/);
+        const match = args.match(/--max-components\s+(\d+)/);
         return match ? Number.parseInt(match[1], 10) : undefined;
     }
 }

package/dist/src/commands/exit-command.js

@@ -8,6 +8,7 @@ export class ExitCommand extends BaseCommand {
     description = 'Exit the application';
     aliases = ['quit'];
     async execute(_args) {
+        await this.explorBot.printSessionAnalysis();
         await this.explorBot.getExplorer().stop();
         if (Stats.hasActivity()) {
             await new Promise((resolve) => {

package/dist/src/commands/explore-command.js

@@ -68,6 +68,7 @@ export class ExploreCommand extends BaseCommand {
             await this.explorBot.visit(mainUrl);
         const savedPath = this.explorBot.savePlans(this.completedPlans);
         this.printResults();
+        await this.explorBot.printSessionAnalysis();
         this.printNextSteps(savedPath);
     }
     async runAllStyles(pageUrl, feature, parentPlan, completedPlans) {

package/dist/src/components/AddRule.js

@@ -4,7 +4,7 @@ import { Box, Text, useInput } from 'ink';
 import React, { useEffect, useState } from 'react';
 import { AddRuleCommand } from '../commands/add-rule-command.js';
 import InputReadline from './InputReadline.js';
-const KNOWN_AGENTS = ['researcher', 'tester', 'planner', 'pilot', 'captain', 'bosun', 'navigator'];
+const KNOWN_AGENTS = ['researcher', 'tester', 'planner', 'pilot', 'captain', 'driller', 'navigator'];
 const AddRule = ({ initialAgent = '', initialName = '', onComplete, onCancel }) => {
     const [agent, setAgent] = useState(initialAgent);
     const [ruleName, setRuleName] = useState(initialName);

package/dist/src/explorbot.js

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { ActionResult } from "./action-result.js";
-import { Bosun } from "./ai/bosun.js";
 import { Captain } from "./ai/captain.js";
+import { Driller } from "./ai/driller.js";
 import { ExperienceCompactor } from "./ai/experience-compactor.js";
 import { Fisherman } from "./ai/fisherman.js";
 import { Historian } from "./ai/historian.js";
@@ -13,6 +13,7 @@ import { AIProvider } from "./ai/provider.js";
 import { Quartermaster } from "./ai/quartermaster.js";
 import { Rerunner } from "./ai/rerunner.js";
 import { Researcher } from "./ai/researcher.js";
+import { SessionAnalyst } from "./ai/session-analyst.js";
 import { Tester } from "./ai/tester.js";
 import { createAgentTools } from "./ai/tools.js";
 import { ApiClient } from "./api/api-client.js";
@@ -24,6 +25,7 @@ import Explorer from "./explorer.js";
 import { KnowledgeTracker } from "./knowledge-tracker.js";
 import { Plan } from "./test-plan.js";
 import { setVerboseMode, tag } from "./utils/logger.js";
+import { relativeToCwd } from "./utils/next-steps.js";
 import { sanitizeFilename } from "./utils/strings.js";
 export class ExplorBot {
     configParser;
@@ -38,6 +40,8 @@ export class ExplorBot {
     lastPlanError = null;
     lastSavedPlanPath = null;
     agents = {};
+    sessionPlans = [];
+    lastReportedTestCount = 0;
     constructor(options = {}) {
         this.options = options;
         this.configParser = ConfigParser.getInstance();
@@ -239,14 +243,15 @@ export class ExplorBot {
         }
         return this.agents.rerunner;
     }
-    agentBosun() {
-        return (this.agents.bosun ||= this.createAgent(({ ai, explorer }) => {
-            const researcher = this.agentResearcher();
+    agentDriller() {
+        return (this.agents.driller ||= this.createAgent(({ ai, explorer }) => {
             const navigator = this.agentNavigator();
-            const tools = createAgentTools({ explorer, researcher, navigator });
-            return new Bosun(explorer, ai, researcher, navigator, tools);
+            return new Driller(explorer, ai, navigator);
         }));
     }
+    agentSessionAnalyst() {
+        return (this.agents.sessionAnalyst ||= this.createAgent(({ ai }) => new SessionAnalyst(ai)));
+    }
     agentFisherman() {
         const fishermanConfig = this.config.ai?.agents?.fisherman;
         const hasApiConfig = !!this.config.api;
@@ -309,7 +314,7 @@ export class ExplorBot {
         }
         this.lastPlanError = null;
         try {
-            this.currentPlan = await planner.plan(feature, opts.style, opts.extend, opts.completedPlans);
+            this.setCurrentPlan(await planner.plan(feature, opts.style, opts.extend, opts.completedPlans));
         }
         catch (err) {
             this.lastPlanError = err instanceof Error ? err : new Error(String(err));
@@ -376,10 +381,45 @@ export class ExplorBot {
         if (!existsSync(planPath)) {
             throw new Error(`Plan file not found: ${planPath}`);
         }
-        this.currentPlan = Plan.fromMarkdown(planPath);
+        this.setCurrentPlan(Plan.fromMarkdown(planPath));
         return this.currentPlan;
     }
     setCurrentPlan(plan) {
         this.currentPlan = plan;
+        if (plan && !this.sessionPlans.includes(plan)) {
+            this.sessionPlans.push(plan);
+        }
+    }
+    getSessionTests() {
+        return this.sessionPlans.flatMap((p) => p.tests.filter((t) => t.startTime != null));
+    }
+    async printSessionAnalysis() {
+        const analystConfig = this.config.ai?.agents?.analyst;
+        if (analystConfig?.enabled === false)
+            return;
+        const tests = this.getSessionTests();
+        if (tests.length === 0)
+            return;
+        if (tests.length === this.lastReportedTestCount)
+            return;
+        try {
+            const markdown = await this.agentSessionAnalyst().analyze(tests);
+            if (!markdown) {
+                this.lastReportedTestCount = tests.length;
+                return;
+            }
+            tag('multiline').log(markdown);
+            const filePath = this.agentSessionAnalyst().writeReport(markdown);
+            tag('info').log(`Session report saved: ${relativeToCwd(filePath)}`);
+            const reporter = this.explorer?.getReporter();
+            if (reporter?.isEnabled()) {
+                await reporter.setRunDescription(markdown);
+            }
+            this.lastReportedTestCount = tests.length;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            tag('warning').log(`Session analysis failed: ${message}`);
+        }
     }
 }

package/dist/src/explorer.js

@@ -15,8 +15,9 @@ import { KnowledgeTracker } from './knowledge-tracker.js';
 import { PlaywrightRecorder } from "./playwright-recorder.js";
 import { Reporter } from "./reporter.js";
 import { StateManager } from './state-manager.js';
+import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from "./utils/html.js";
 import { createDebug, log, tag } from './utils/logger.js';
-import { WebElement, extractElementData } from "./utils/web-element.js";
+import { WebElement } from "./utils/web-element.js";
 const debugLog = createDebug('explorbot:explorer');
 const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
@@ -270,11 +271,11 @@ class Explorer {
     async getEidxInContainer(containerCss) {
         const page = this.playwrightHelper.page;
         try {
-            const selector = containerCss ? `${containerCss} [data-explorbot-eidx]` : '[data-explorbot-eidx]';
+            const selector = containerCss ? `${containerCss} [${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]` : `[${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]`;
             const elements = await page.locator(selector).all();
             const result = [];
             for (const el of elements) {
-                const attr = await el.getAttribute('data-explorbot-eidx');
+                const attr = await el.getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx);
                 if (attr)
                     result.push(attr);
             }
@@ -293,7 +294,7 @@ class Explorer {
             const page = this.playwrightHelper.page;
             const base = container ? page.locator(container) : page;
             const el = locator.startsWith('//') ? base.locator(`xpath=${locator}`) : base.locator(locator);
-            return await el.first().getAttribute('data-explorbot-eidx');
+            return await el.first().getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx);
         }
         catch (error) {
             if (this.isFatalBrowserError(error)) {
@@ -644,21 +645,21 @@ export async function annotatePageElements(page) {
     const elements = [];
     for (const [role, entries] of byRole) {
         try {
-            const rawList = await page.getByRole(role).evaluateAll((domElements, [data, extractFnStr]) => {
+            const rawList = await page.getByRole(role).evaluateAll((domElements, [data, extractFnStr, config]) => {
                 const extract = new Function(`return ${extractFnStr}`)();
                 const results = [];
                 let ariaIdx = 0;
                 for (const el of domElements) {
                     if (ariaIdx >= data.length)
                         break;
-                    el.setAttribute('data-explorbot-eidx', data[ariaIdx].ref);
-                    const elData = extract(el);
+                    el.setAttribute(config.attrs.eidx, data[ariaIdx].ref);
+                    const elData = extract(el, config);
                     if (elData)
                         results.push(elData);
                     ariaIdx++;
                 }
                 return results;
-            }, [entries, extractElementData.toString()]);
+            }, [entries, getElementDataExtractorSource(), ELEMENT_EXTRACTION_CONFIG]);
             for (const raw of rawList) {
                 elements.push(WebElement.fromRawData(raw, role));
             }

package/dist/src/reporter.js

@@ -14,8 +14,19 @@ export class Reporter {
         if (this.reporterEnabled && (!process.env.TESTOMATIO || config?.html)) {
             this.configureHtmlPipe();
         }
-        const pipe = process.env.TESTOMATIO && config?.html ? 'both' : process.env.TESTOMATIO ? 'testomatio' : 'html';
-        debugLog('Reporter initialized', { enabled: this.reporterEnabled, pipe });
+        if (this.reporterEnabled && config?.markdown) {
+            this.configureMarkdownPipe();
+        }
+        if (this.reporterEnabled) {
+            this.configureRunGroup(config?.runGroup);
+        }
+        debugLog('Reporter initialized', {
+            enabled: this.reporterEnabled,
+            testomatio: Boolean(process.env.TESTOMATIO),
+            html: Boolean(process.env.TESTOMATIO_HTML_REPORT_SAVE),
+            markdown: Boolean(process.env.TESTOMATIO_MARKDOWN_REPORT_SAVE),
+            runGroup: process.env.TESTOMATIO_RUNGROUP_TITLE || null,
+        });
     }
     buildTitle() {
         if (process.env.TESTOMATIO_TITLE)
@@ -39,7 +50,31 @@ export class Reporter {
     configureHtmlPipe() {
         process.env.TESTOMATIO_HTML_REPORT_SAVE = '1';
         process.env.TESTOMATIO_HTML_REPORT_FOLDER = outputPath('reports');
-        debugLog('HTML report pipe configured', { folder: process.env.TESTOMATIO_HTML_REPORT_FOLDER });
+        process.env.TESTOMATIO_HTML_FILENAME = `${Stats.sessionLabel()}.html`;
+        debugLog('HTML report pipe configured', {
+            folder: process.env.TESTOMATIO_HTML_REPORT_FOLDER,
+            filename: process.env.TESTOMATIO_HTML_FILENAME,
+        });
+    }
+    configureMarkdownPipe() {
+        process.env.TESTOMATIO_MARKDOWN_REPORT_SAVE = '1';
+        process.env.TESTOMATIO_MARKDOWN_REPORT_FOLDER = outputPath('reports');
+        process.env.TESTOMATIO_MARKDOWN_FILENAME = `${Stats.sessionLabel()}-tests.md`;
+        debugLog('Markdown report pipe configured', {
+            folder: process.env.TESTOMATIO_MARKDOWN_REPORT_FOLDER,
+            filename: process.env.TESTOMATIO_MARKDOWN_FILENAME,
+        });
+    }
+    configureRunGroup(runGroup) {
+        if (process.env.TESTOMATIO_RUNGROUP_TITLE)
+            return;
+        if (runGroup === null)
+            return;
+        if (runGroup) {
+            process.env.TESTOMATIO_RUNGROUP_TITLE = runGroup;
+            return;
+        }
+        process.env.TESTOMATIO_RUNGROUP_TITLE = `Explorbot ${new Date().toISOString().slice(0, 10)}`;
     }
     async startRun() {
         if (this.isRunStarted) {
@@ -190,6 +225,32 @@ export class Reporter {
     isEnabled() {
         return this.isRunStarted;
     }
+    async setRunDescription(text) {
+        if (!this.isRunStarted)
+            return;
+        if (!process.env.TESTOMATIO)
+            return;
+        const runId = this.client.runId;
+        if (!runId)
+            return;
+        const baseUrl = process.env.TESTOMATIO_URL || 'https://app.testomat.io';
+        const url = `${baseUrl}/api/reporter/${runId}`;
+        try {
+            const response = await fetch(url, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ api_key: process.env.TESTOMATIO, description: text }),
+            });
+            if (!response.ok) {
+                debugLog('Run description update failed:', response.status, response.statusText);
+                return;
+            }
+            debugLog('Run description updated');
+        }
+        catch (error) {
+            debugLog('Failed to update run description:', error);
+        }
+    }
     extractLastNoteMessage(test) {
         const notes = Object.values(test.notes);
         if (notes.length === 0)

package/dist/src/state-manager.js

@@ -70,8 +70,8 @@ export class StateManager {
     }
     /**
      * Extract state path from full URL
-     * Removes domain, port, protocol, and query params
-     * Keeps path and hash: /path/to/page#section
+     * Removes domain, port, protocol
+     * Keeps path, query, and hash: /path/to/page?tab=users#section
      */
     /**
      * Update current state from ActionResult and record transition if state changed
@@ -418,7 +418,8 @@ export class StateManager {
 export function normalizeUrl(url) {
     try {
         const parsed = new URL(url, 'http://localhost');
-        return parsed.pathname.replace(/^\/+|\/+$/g, '');
+        const path = parsed.pathname.replace(/^\/+|\/+$/g, '');
+        return `${path}${parsed.search}${parsed.hash}`;
     }
     catch {
         return url.replace(/^\/+|\/+$/g, '');