explorbot 0.1.4 → 0.1.6

package/dist/rules/planner/styles/curious.md

@@ -1,5 +1,12 @@
 Detect new valid paths that previous tests missed. Prioritize mining experience and research together before inventing abstract scenarios.
 
+Rank every scenario you build by the **strength of its outcome**, from strongest to weakest:
+1. **Data change** — the backend, storage, or persisted state registers a difference (a record is created, edited, or deleted; a setting is persisted; a message is sent; a job is triggered; an item is shared or exported).
+2. **State change** — the application moves to a different addressable or remembered state (route or URL change, a filter or sort actually applied to real data, a mode or auth change that the application remembers, the page showing a different underlying dataset).
+3. **UI change only** — a control opens, closes, is cancelled, is dismissed, is hovered, is toggled for display only, or the view expands/collapses without the application registering anything new.
+
+Prefer scenarios whose ending falls into category 1. Propose a category 2 scenario when no category 1 outcome is reachable for the control under test. Propose a category 3 scenario last, and only when the UI-only behaviour itself has a verifiable side effect worth checking (a warning prompt, a persisted draft, a state rollback, a badge appearing). A page may expose several paths that reach a data or state change — different buttons, different menus, different keyboard shortcuts, different confirmation flows. Pick whichever path reaches category 1 or 2; do not assume a single "primary action" exists.
+
 When <previously_tested_flows> is present, treat it as the ground truth for what already worked:
 - List items under Successful Flow describe the path that was executed
 - Lines in blockquotes (lines starting with >) are discoveries: extra fields, side panels, conditional UI, inputs called out during that run
@@ -11,7 +18,7 @@ When <previously_tested_flows> is NOT present, use <tested_scenarios> as the gro
 Read the step lines for each test to understand which controls were actually interacted with.
 Identify elements from <page_research> that appear in NO test steps — these are coverage gaps.
 
-Cross-read with <page_research>: for each form and Extended Research subsection, compare against those flows. Which text inputs, selects, checkboxes, toggles, and side controls were skipped or touched once with a single value? Prefer filling those gaps over repeating the same path.
+Cross-read with <page_research>: for each section and Extended Research subsection, compare against those flows. Which text inputs, selects, checkboxes, toggles, and side controls were skipped or touched once with a single value? Prefer filling those gaps over repeating the same path.
 
 The Type column in <page_research> tables shows the ARIA role of each element.
 Cross-reference these types with the steps listed in <tested_scenarios> or <previously_tested_flows>:
@@ -24,16 +31,22 @@ Coverage gaps to look for:
 - Action buttons that were never clicked as part of a complete workflow
 - Dependent UI: controls that appear or change based on another control's value
 
-When proposing tests for forms, prefer filling ALL visible fields — not just required ones.
+A coverage gap for an untested control is only **closed** when the scenario built around it reaches a data change or state change. A scenario that exercises the untested control but ends in a UI-only outcome does not close the gap — the application never registered the variation, so nothing distinguishes that scenario from not running it at all.
+
+Exercising an untested control and testing a UI-only dismissal (cancel, close, navigate away, discard) are **two different categories of scenario**. Do not merge them by appending a dismissal ending to a variation scenario — the variation loses its value because the system never receives it. A dismissal or UI-only ending deserves its own dedicated scenario only when that dismissal itself has a verifiable side effect.
+
+When multiple inputs or configurable controls contribute to the same outcome, prefer scenarios that configure **several of them together** before triggering the data or state change, rather than touching one control in isolation and ending there.
 Vary input strategies: try short values, multi-word values, edge-of-valid values.
-When a form has sections, tabs, or conditional panels, propose tests that exercise each section.
-If a control has downstream effects (e.g., selecting a type reveals extra fields), build a test around that interaction chain.
+When sections, tabs, or conditional panels exist, exercise each section.
+When a control has downstream effects (selecting one option reveals extra fields, toggling one setting enables another), build the scenario around that interaction chain — and still end it in a data or state change.
 
 Combinatorial coverage (valid data only):
 - For each select or equivalent, ensure each option is exercised in at least one scenario, or one scenario whose steps walk through distinct options in sequence if that fits the task constraints better
 - Exercise each checkbox or binary control in both states when behavior can differ
 - Combine checkboxes and related toggles in small sets (pairs or triples) when they plausibly change validation, visible sections, or outcomes — avoid exploding into huge Cartesian products
 
-When heavy forms are not the focus, still pursue: unvisited state transitions, follow-ups after creates (share, export, duplicate), alternative routes to the same goal, preconditions that unlock UI, and visible controls never clicked.
+Each proposed combination must be exercised in a scenario that reaches a data change or state change. Combinations that only change the UI and never reach a registerable outcome do not count as coverage — the system never distinguishes them from each other.
+
+When the page is not heavy on inputs, still pursue: unvisited state transitions, follow-ups after data-changing operations (share, export, duplicate, re-open), alternative paths to the same data change, preconditions that unlock new data-changing actions, and visible controls never clicked. Again, prioritise scenarios whose ending falls into category 1 or 2.
 
 Skip the Menu/Navigation section — we are testing THIS page.

package/dist/rules/planner/styles/normal.md

@@ -2,18 +2,18 @@ Study the page and figure out its business purpose. What is this page FOR? What
 
 Based on the page type, propose tests for COMPLETE user workflows:
 - If this is a data page (lists, tables): test CRUD operations end-to-end (create item → verify in list, edit item → verify changes saved, delete item → verify removed)
-- If this is a form page: test full submission flow, not just "form appears"
+- If the page has inputs to fill in: test the full commit flow, not just that the controls render
 - If this has filters and search: test filtering AND verify results change, not just "filter tab clicked"
 - If this has modals/dropdowns: test the ACTION inside them, not just opening/closing them
 
-Each test should end with the application in a different state than it started.
+Each test should end in a **data change** (record created/edited/deleted, setting persisted, message sent) or a **state change** (route change, filter applied to real data, mode change the app remembers). Tests ending in UI-only outcomes (open, close, hover, expand) are the weakest and should be rare.
 
 IMPORTANT: Distribute tests across DIFFERENT feature areas from the research.
 Do not propose more than 2 tests for the same feature area.
 Every Extended Research section (modal, dropdown, panel) with actionable features deserves at least one test.
-Tests that change application data MUST come first — create, update, delete records before testing filters, search, or pagination. You are aiming to change application state.
+Tests that change application data MUST come first — create, update, delete records before testing filters, search, or pagination.
 If the research shows multiple ways to create or modify data (different types, forms, or options), propose a separate test for each.
-View only tests (tab switching, pagination, view toggles) should be proposed only after  data-changing interactions are covered.
+UI-only tests (tab switching, pagination, view toggles) should be proposed only after data-changing and state-changing interactions are covered.
 
 Skip the Menu/Navigation section — we are testing THIS page.
 

package/dist/rules/planner/styles/psycho.md

@@ -1,14 +1,17 @@
-Stress-test the page by filling invalid, empty, and extreme values into every input.
+Stress-test the page by feeding invalid, empty, or extreme values to its controls and committing.
 
-Focus on:
-- Empty states: submit forms with no data, clear required fields, remove default values
-- Long values: paste 10000 characters into inputs, use extremely long names and descriptions
-- Boundary values: zero, negative numbers, special characters, unicode, HTML tags in text fields
-- Invalid formats: wrong email formats, letters in number fields, SQL injection strings, script tags
-- Invalid combinations: select incompatible options, mix conflicting settings
-- Combining states: apply multiple filters at once, use conflicting form values together
-- Out-of-range values: dates in the past/future, quantities beyond limits, prices with too many decimals
+**Match attack breadth to controls reachable.** If only ONE control is reachable, attack it alone. If several are reachable, attack **all of them in the same scenario** — each with a different strange value. Never stress one while leaving the rest untouched: attacking one-at-a-time hides interaction bugs and wastes plan budget.
 
-Push every input to its limits. Find what breaks when the form receives unexpected data.
+Do not produce multiple scenarios that each isolate one control of the same section. Fold those attacks into fewer scenarios that push every reachable control strangely at once. Vary the **mix** between scenarios — which control receives SQL, which receives 10000 chars, which receives unicode, which receives a conflicting combination — not the single control under attack.
 
-Skip the Menu/Navigation section — we are testing THIS page.
+**Attack categories** (combine across controls, not one-per-scenario):
+empty • very long (10000+ chars) • boundary (zero, negative, unicode, HTML, special chars) • invalid formats (malformed email/url/number, SQL, script tags) • invalid combinations (mutually exclusive toggles together, conflicting modes) • out-of-range (far dates, quantities beyond limits, excess decimals) • dependent-UI stress (flip a control that reveals more, attack those too).
+
+**Prefer scenarios that:**
+- Push every reachable control to a different bad-data category, then commit
+- Trigger a conditional section, attack revealed and base controls together, then commit
+- Combine mutually exclusive control states with invalid values, then commit
+
+End each scenario with the state **committed** (saved, applied, sent, triggered). A scenario that enters bad data then cancels or navigates away reveals nothing — the application never received the payload.
+
+Skip the Menu/Navigation section — we are testing THIS page.

package/dist/rules/researcher/container-rules.md

@@ -0,0 +1,15 @@
+<container_rules>
+Container CSS must be a SINGLE semantic selector — one class, one id, or one attribute. No spaces, no combinators, no descendant paths.
+
+- INVALID: bare tags (`div`, `section`, `nav`), combinators (`div > .content`, `.a .b`), layout/utility classes (flex-, col-, mt-, p-, bg-, text-, items-, rounded-)
+- VALID: semantic class names that describe what the section IS (`.product-list`, `.sidebar-menu`, `.user-profile`, `.search-results`), semantic roles (`[role="dialog"]`), semantic ids (`#main-content`)
+
+The container must uniquely identify a semantic wrapper, not a path through the DOM.
+</container_rules>
+
+<css_selector_rules>
+CSS selectors inside the UI map must point to the actual interactive element (input, button, a, select), not to wrapper divs.
+
+- Prefer distinguishing attributes on the interactive element (`type`, `value`, `name`, `href`, `aria-label`) over wrapper ids.
+- For buttons with similar text, include `type` or `value` or form context to stay unique.
+</css_selector_rules>

package/dist/rules/researcher/section-example.md

@@ -0,0 +1,12 @@
+<section_example>
+## List
+
+Product catalog showing available items with sorting and filtering.
+
+> Container: '.product-list'
+
+| Element | ARIA | CSS | eidx |
+| 'Sort by price' | { role: 'button', text: 'Sort by price' } | '.sort-btn' | 3 |
+| 'Add to cart' | { role: 'button', text: 'Add to cart' } | '.add-btn' | 4 |
+| 'Product name' | { role: 'link', text: 'Widget Pro' } | 'a.product-link' | 5 |
+</section_example>

package/dist/src/ai/captain/web-mode.js

@@ -1,6 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
+import { ActionResult } from "../../action-result.js";
 import { actionRule, locatorRule, sectionContextRule } from "../rules.js";
 import { createAgentTools, createCodeceptJSTools } from "../tools.js";
 import { debugLog } from "./mixin.js";
@@ -8,13 +9,19 @@ export function WithWebMode(Base) {
     return class extends Base {
         webModeTools(ctx) {
             const explorer = ctx.explorBot.getExplorer();
+            const stateManager = explorer.getStateManager();
             const codeceptTools = createCodeceptJSTools(explorer, ctx.task);
             const agentTools = createAgentTools({
                 explorer,
                 researcher: ctx.explorBot.agentResearcher(),
                 navigator: ctx.explorBot.agentNavigator(),
+                experienceTracker: stateManager.getExperienceTracker(),
+                getState: () => {
+                    const state = stateManager.getCurrentState();
+                    return state ? ActionResult.fromState(state) : null;
+                },
             });
-            const { see, context, visualClick } = agentTools;
+            const { see, context, visualClick, learn_experience } = agentTools;
             return {
                 navigate: tool({
                     description: 'Navigate to a URL or page description using AI-powered navigation.',
@@ -91,6 +98,7 @@ export function WithWebMode(Base) {
                 see,
                 context,
                 visualClick,
+                learn_experience,
             };
         }
         webModePrompt() {

package/dist/src/ai/historian.js

@@ -16,12 +16,16 @@ export class Historian {
     experienceTracker;
     reporter;
     stateManager;
+    savedFiles = new Set();
     constructor(provider, experienceTracker, reporter, stateManager) {
         this.provider = provider;
         this.experienceTracker = experienceTracker || new ExperienceTracker();
         this.reporter = reporter;
         this.stateManager = stateManager;
     }
+    getSavedFiles() {
+        return [...this.savedFiles];
+    }
     async saveSession(task, initialState, conversation) {
         debugLog('Saving session experience');
         const result = this.determineResult(task);
@@ -363,6 +367,7 @@ export class Historian {
         const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
         const filePath = join(testsDir, `${filename}.js`);
         writeFileSync(filePath, lines.join('\n'));
+        this.savedFiles.add(filePath);
         tag('substep').log(`Saved plan tests to: ${filePath}`);
         return filePath;
     }
@@ -374,6 +379,7 @@ export class Historian {
             content = content.replace(step.original, step.healed);
         }
         writeFileSync(filePath, content);
+        this.savedFiles.add(filePath);
         tag('substep').log(`Updated test file with healed steps: ${filePath}`);
     }
     getExecutionLabel(exec, fallback) {

package/dist/src/ai/pilot.js

@@ -1,7 +1,9 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
+import { ActionResult } from "../action-result.js";
 import { ConfigParser } from "../config.js";
+import { renderExperienceToc } from "../experience-tracker.js";
 import { TestResult } from "../test-plan.js";
 import { collectInteractiveNodes, detectFocusArea, extractFocusedElement } from "../utils/aria.js";
 import { createDebug, tag } from "../utils/logger.js";
@@ -18,11 +20,13 @@ export class Pilot {
     researcher;
     explorer;
     fisherman = null;
-    constructor(provider, agentTools, researcher, explorer) {
+    experienceTracker;
+    constructor(provider, agentTools, researcher, explorer, experienceTracker) {
         this.provider = provider;
         this.agentTools = agentTools;
         this.researcher = researcher;
         this.explorer = explorer;
+        this.experienceTracker = experienceTracker || null;
     }
     setFisherman(fisherman) {
         this.fisherman = fisherman;
@@ -317,7 +321,14 @@ export class Pilot {
     }
     async sendToPilot(userText, functionId, opts = {}) {
         debugLog(`sendToPilot: ${functionId}, tools: ${!!opts.tools}, roundtrips: ${opts.maxToolRoundtrips ?? 0}`);
-        this.conversation.addUserText(userText);
+        let finalUserText = userText;
+        if (opts.tools) {
+            const tocBlock = this.getExperienceToc();
+            if (tocBlock) {
+                finalUserText = `${tocBlock}\n\n${userText}`;
+            }
+        }
+        this.conversation.addUserText(finalUserText);
         let tools = opts.tools ? this.agentTools : undefined;
         if (opts.tools && opts.task) {
             tools = { ...tools, ...this.buildPreconditionTool(opts.task) };
@@ -329,6 +340,16 @@ export class Pilot {
         });
         return result?.response?.text || '';
     }
+    getExperienceToc() {
+        if (!this.experienceTracker)
+            return '';
+        const state = this.explorer.getStateManager().getCurrentState();
+        if (!state)
+            return '';
+        const actionResult = ActionResult.fromState(state);
+        const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
+        return renderExperienceToc(toc);
+    }
     buildPreconditionTool(task) {
         return {
             precondition: tool({

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

@@ -21,6 +21,12 @@ function getFingerprintWorker() {
     }
     return fingerprintWorker;
 }
+export function clearResearchCache() {
+    for (const key of Object.keys(memoryCache))
+        delete memoryCache[key];
+    for (const key of Object.keys(memoryCacheTimestamps))
+        delete memoryCacheTimestamps[key];
+}
 export function getCachedResearch(hash) {
     if (!hash)
         return '';

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

@@ -1,8 +1,10 @@
 import dedent from 'dedent';
 import { ActionResult } from '../../action-result.js';
-import { diffAriaSnapshots } from "../../utils/aria.js";
+import { detectFocusArea, diffAriaSnapshots } from "../../utils/aria.js";
 import { executionController } from "../../execution-controller.js";
 import { tag } from '../../utils/logger.js';
+import { mdq } from "../../utils/markdown-query.js";
+import { getCachedResearch, saveResearch } from "./cache.js";
 import { debugLog } from "./mixin.js";
 import { parseResearchSections } from "./parser.js";
 const DEFAULT_MAX_EXPANDABLE_CLICKS = 10;
@@ -53,6 +55,48 @@ export function WithDeepAnalysis(Base) {
                 result.text += `\n\n## Navigation Links\n\n${links}`;
             }
         }
+        async researchOverlay(current, previous, pageStateHash) {
+            const focusArea = detectFocusArea(current.ariaSnapshot);
+            if (!focusArea.detected || !focusArea.name)
+                return null;
+            if (focusArea.type !== 'dialog' && focusArea.type !== 'modal')
+                return null;
+            const cached = getCachedResearch(pageStateHash);
+            if (!cached)
+                return null;
+            const escaped = focusArea.name.replace(/"/g, '\\"');
+            if (mdq(cached).query(`section3(~"${escaped}")`).count() > 0) {
+                debugLog(`Overlay "${focusArea.name}" already in cached research, skipping`);
+                return null;
+            }
+            const diff = await current.diff(previous);
+            await diff.calculate();
+            if (!diff.ariaChanged && diff.htmlParts.length === 0) {
+                debugLog(`No diff between current and previous state for overlay "${focusArea.name}"`);
+                return null;
+            }
+            const alreadyExpanded = this._summarizeExpanded(parseResearchSections(cached)
+                .filter((s) => s.elements.length > 0)
+                .map((s) => s.rawMarkdown));
+            tag('substep').log(`Researching overlay: ${focusArea.name}`);
+            const sectionMarkdown = await this._analyzeExpandedAction('', focusArea.name, diff, alreadyExpanded);
+            if (!sectionMarkdown) {
+                debugLog(`Overlay "${focusArea.name}" produced no meaningful expansion`);
+                return null;
+            }
+            const extQuery = mdq(cached).query('section1(~"Extended Research")');
+            let updated;
+            if (extQuery.count() > 0) {
+                const existing = extQuery.text().trimEnd();
+                updated = extQuery.replace(`${existing}\n\n${sectionMarkdown}\n`);
+            }
+            else {
+                updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
+            }
+            saveResearch(pageStateHash, updated);
+            tag('substep').log(`Overlay research appended: ${focusArea.name}`);
+            return sectionMarkdown;
+        }
         async _discoverExpandables(researchText) {
             const allElements = new Map();
             for (const section of parseResearchSections(researchText)) {
@@ -272,8 +316,26 @@ export function WithDeepAnalysis(Base) {
         }
         async _analyzeExpandedAction(code, description, diff, alreadyExpanded) {
             const alreadyHint = alreadyExpanded.length > 0 ? `\nAlready expanded sections:\n${alreadyExpanded.join('\n')}` : '';
+            let intro;
+            if (code) {
+                intro = `An action on "${description}" (\`${code}\`) revealed new UI content.`;
+            }
+            else {
+                intro = `An overlay "${description}" appeared on the page.`;
+            }
+            let actionBlock = '';
+            if (code) {
+                actionBlock = dedent `
+          Action:
+
+          \`\`\`js
+          ${code}
+          \`\`\`
+
+        `;
+            }
             const prompt = dedent `
-        An action on "${description}" (\`${code}\`) revealed new UI content.
+        ${intro}
         Analyze the changes and produce a UI map section.
 
         ARIA changes:
@@ -287,13 +349,7 @@ export function WithDeepAnalysis(Base) {
 
         ### <Short descriptive name>
 
-        Action:
-
-        \`\`\`js
-        ${code}
-        \`\`\`
-
-        <One sentence: what appeared — dropdown menu, modal, tab content, expanded panel, etc.>
+        ${actionBlock}<One sentence: what appeared — dropdown menu, modal, tab content, expanded panel, etc.>
 
         | Element | ARIA | CSS |
         |---------|------|-----|

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

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