explorbot 0.3.5 → 0.4.1

package/dist/boat/prima/src/cli.js

@@ -29,9 +29,9 @@ const checkHelp = dedent `
               as false.
   Outcomes are settled against a screenshot of the whole page: what a user can see is
   the proof, and the run log only says what was done. CONTRADICTION means the two
-  disagree - reported with both sides rather than settled one way, and ### Artifacts
-  then names the html, aria and screenshot on disk so you can judge it yourself. Not
-  finding something in the picture is not enough on its own; that is "not verified".
+  disagree - reported with both sides rather than settled one way, so read the html,
+  aria and screenshot named under ### Artifacts and judge it yourself. Not finding
+  something in the picture is not enough on its own; that is "not verified".
   ok: follows those outcomes - false when one FAILED or CONTRADICTED, or when the run
   could not complete, which is reported as such rather than as an app failure.
   Page problems seen on the way appear under ### Answer, not as step failures.
@@ -48,6 +48,12 @@ const verifyHelp = dedent `
   and gives no overall verdict - read the lines and decide. "none ran" means the claim
   could not be expressed, which is not the same as false.
 `;
+const statusHelp = dedent `
+  Reads the files a command recorded, so it needs no browser and outlives the session.
+  The hash is looked up across every recorded site. ### Artifacts names every file kept
+  under it: the aria tree, the html, the screenshot and network log when they were
+  captured, and the per-step captures of a do run.
+`;
 const reportHelp = dedent `
   Commands are logged as they run, so the report needs no browser and outlives the session.
   The most recent session is reported unless --pw-session names another.
@@ -100,6 +106,7 @@ function addCommonOptions(cmd) {
         .option('--ephemeral', 'Keep no state between runs; applies to config-free runs, where output goes to a temp directory')
         .option('--framework <name>', 'Not active yet: framework the reported code targets, codeceptjs or playwright')
         .option('--url <url>', 'Page to open when the session has no page yet')
+        .option('--spec <path>', 'Docbot application spec directory or index.md to read as page knowledge')
         .option('--endpoint <ep>', 'Websocket endpoint of a browser server to attach to, skipping discovery')
         .option('--pw-session <title>', 'Title of the playwright-cli session to attach to')
         .addHelpText('after', `\n${sessionHelp}`);
@@ -112,9 +119,11 @@ function primaFor(options) {
         process.env.EXPLORBOT_AI_MODEL = options.model;
     if (options.visionModel)
         process.env.EXPLORBOT_VISION_MODEL = options.visionModel;
+    if (options.spec)
+        process.env.EXPLORBOT_SPEC = options.spec;
     return new Prima(buildOptions(options));
 }
-async function runPrima(options, command, run, record = true) {
+async function runPrima(options, command, run) {
     setQuietMode(!isVerboseMode());
     trackActivityLine();
     const prima = primaFor(options);
@@ -127,8 +136,7 @@ async function runPrima(options, command, run, record = true) {
     catch (error) {
         envelope = await prima.toolFailureEnvelope(command, error);
     }
-    if (record)
-        prima.record(envelope, Date.now() - startedAt);
+    prima.record(envelope, Date.now() - startedAt);
     clearActivityLine();
     console.log(renderEnvelope(envelope));
     await prima.stop().catch(() => { });
@@ -191,8 +199,14 @@ export function createPrimaCommands(name = 'prima') {
         await prima.stop().catch(() => { });
         process.exit(0);
     });
-    addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command')).action(async (hash, options) => {
-        await runPrima(options, `status ${hash}`, (prima) => prima.status(hash), false);
+    addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command'))
+        .addHelpText('after', `\n${statusHelp}`)
+        .action(async (hash, options) => {
+        setQuietMode(!isVerboseMode());
+        const prima = primaFor(options);
+        const envelope = await prima.status(hash).catch((error) => prima.toolFailureEnvelope(`status ${hash}`, error));
+        console.log(renderEnvelope(envelope));
+        process.exit(envelope.ok ? 0 : 1);
     });
     addCommonOptions(cmd.command('report').description('Turn every command of a session into one html and markdown report'))
         .addHelpText('after', `\n${reportHelp}`)

package/dist/boat/prima/src/envelope.js

@@ -1,5 +1,7 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+export const STATUS_FILE = 'status.json';
+const ARTIFACT_FILES = { aria: 'aria.yml', html: 'page.html', screenshot: 'page.png', network: 'network.jsonl' };
 const EXPECTATION_LABELS = {
     passed: 'PASSED       ',
     failed: 'FAILED       ',
@@ -13,21 +15,35 @@ export function renderEnvelope(data) {
 export function writeArtifacts(dir, snapshot) {
     mkdirSync(dir, { recursive: true });
     const paths = {
-        aria: path.resolve(dir, 'aria.yml'),
-        html: path.resolve(dir, 'page.html'),
+        aria: path.resolve(dir, ARTIFACT_FILES.aria),
+        html: path.resolve(dir, ARTIFACT_FILES.html),
     };
     writeFileSync(paths.aria, snapshot.aria ?? '', 'utf-8');
     writeFileSync(paths.html, snapshot.html ?? '', 'utf-8');
     if (snapshot.screenshot) {
-        paths.screenshot = path.resolve(dir, 'page.png');
+        paths.screenshot = path.resolve(dir, ARTIFACT_FILES.screenshot);
         writeFileSync(paths.screenshot, snapshot.screenshot);
     }
     if (!snapshot.requests.length)
         return paths;
-    paths.network = path.resolve(dir, 'network.jsonl');
+    paths.network = path.resolve(dir, ARTIFACT_FILES.network);
     writeFileSync(paths.network, snapshot.requests.map((request) => `${JSON.stringify(request)}\n`).join(''), 'utf-8');
     return paths;
 }
+export function readArtifacts(dir) {
+    const paths = { aria: path.resolve(dir, ARTIFACT_FILES.aria), html: path.resolve(dir, ARTIFACT_FILES.html) };
+    if (existsSync(path.resolve(dir, ARTIFACT_FILES.screenshot)))
+        paths.screenshot = path.resolve(dir, ARTIFACT_FILES.screenshot);
+    if (existsSync(path.resolve(dir, ARTIFACT_FILES.network)))
+        paths.network = path.resolve(dir, ARTIFACT_FILES.network);
+    const recorded = [...Object.values(ARTIFACT_FILES), STATUS_FILE];
+    const files = readdirSync(dir)
+        .filter((entry) => !recorded.includes(entry))
+        .sort();
+    if (files.length)
+        paths.files = files;
+    return paths;
+}
 function renderResult(data) {
     const lines = [`ok: ${data.ok}`, `command: ${data.command}`];
     if (data.used?.length)
@@ -70,7 +86,7 @@ function renderSteps(data) {
             lines.push(`      ${line}`);
     });
     if (data.stepFiles)
-        lines.push('', `page after each step: ${data.stepFiles}`);
+        lines.push('', `page after each step: ${data.stepFiles}/<n>-<step>.{aria.yaml,html,diff.yaml}`);
     return section('Steps', lines.join('\n'));
 }
 function renderExpectations(data) {
@@ -154,6 +170,8 @@ export function renderArtifacts(data) {
         lines.push(`screenshot: ${data.artifacts.screenshot}`);
     if (data.artifacts.network)
         lines.push(`network:    ${data.artifacts.network}`);
+    if (data.artifacts.files?.length)
+        lines.push(`also here:  ${data.artifacts.files.join(', ')}`);
     return section('Artifacts', lines.join('\n'));
 }
 function align(label, marker, width) {

package/dist/boat/prima/src/prima.js

@@ -23,7 +23,7 @@ import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { pluralize } from "../../../src/utils/logger.js";
 import { mdq } from "../../../src/utils/markdown-query.js";
 import { safeFilename } from "../../../src/utils/strings.js";
-import { writeArtifacts } from "./envelope.js";
+import { STATUS_FILE, readArtifacts, writeArtifacts } from "./envelope.js";
 import { isFunctionExpression, takePwValue, toCodeceptWrapper } from "./pw-parser.js";
 import { readDescriptors, selectDescriptor } from "./pw-registry.js";
 import { latestSessionFile, readSession, recordCommand, sessionFile, sessionsDir } from "./session-log.js";
@@ -341,8 +341,6 @@ export class Prima {
         const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
         if (problems.length)
             envelope.failure = { error: problems.join('\n') };
-        if (contradicted.length)
-            envelope.artifacts = this.artifacts;
         if (!test.hasFinished || test.isSkipped) {
             envelope.ok = false;
             envelope.failure = { error: `the run did not complete, so it established nothing about the app: ${notes.at(-1)?.message || 'no steps were recorded'}` };
@@ -924,14 +922,17 @@ export class Prima {
         return response?.text || '';
     }
     async successEnvelope(command, used, result, previousState) {
+        const changes = await this.pageChanges(result, previousState, used[0]);
+        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             used,
             page: this.pageBlock(result, previousState),
-            changes: await this.pageChanges(result, previousState, used[0]),
+            changes,
             instance: await this.instanceInfo(),
-            status: await this.saveStatus(result),
+            status,
+            artifacts: this.artifacts,
         };
     }
     async failureEnvelope(command, error, previousState) {
@@ -939,23 +940,27 @@ export class Prima {
         const failure = { error: browserErrorMessage(error) };
         if (result.ariaSnapshot)
             failure.compactAria = compactAriaSnapshot(result.ariaSnapshot, true);
+        const status = await this.saveStatus(result);
         return {
             ok: false,
             command,
             page: this.pageBlock(result, previousState),
             failure,
             instance: await this.instanceInfo(),
-            status: await this.saveStatus(result),
+            status,
+            artifacts: this.artifacts,
         };
     }
     async reportEnvelope(command, result, previousState, outcome) {
+        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             page: this.pageBlock(result, previousState),
             ...outcome,
             instance: await this.instanceInfo(),
-            status: await this.saveStatus(result),
+            status,
+            artifacts: this.artifacts,
         };
     }
     async capturedResult(previousState, opts = {}) {
@@ -1000,23 +1005,30 @@ export class Prima {
         return lines.join('\n');
     }
     async status(hash) {
+        if (!this.artifactsDir) {
+            const sites = listSites();
+            const site = sites.find((candidate) => existsSync(path.join(candidate.dir, 'output', 'prima', hash))) || sites[0];
+            if (site && !this.configBaseUrl())
+                this.sessionUrl = site.url;
+            await this.loadConfig();
+        }
         const dir = this.statusDir(hash);
-        const statusFile = path.join(dir, 'status.json');
+        const statusFile = path.join(dir, STATUS_FILE);
         if (!existsSync(statusFile))
-            return this.toolFailureEnvelope(`status ${hash}`, `No command was recorded under ${hash}. Every envelope prints its own hash on the Instance line.`);
+            return this.toolFailureEnvelope(`status ${hash}`, `No command was recorded under ${dir}. Every envelope prints its own hash on the Instance line.`);
         const saved = JSON.parse(readFileSync(statusFile, 'utf-8'));
         return {
             ok: true,
             command: `status ${hash}`,
             page: saved.page,
             instance: await this.instanceInfo(),
-            artifacts: { aria: path.join(dir, 'aria.yml'), html: path.join(dir, 'page.html') },
+            artifacts: readArtifacts(dir),
         };
     }
     async saveStatus(result) {
         const hash = this.statusHash();
         await this.writeSnapshot(result);
-        writeFileSync(path.join(this.statusDir(hash), 'status.json'), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
+        writeFileSync(path.join(this.statusDir(hash), STATUS_FILE), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
         return hash;
     }
     async writeStepFiles(index, label, diff) {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -77,7 +77,7 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^4.0",
     "@ai-sdk/google": "^4.0.18",
-    "@ai-sdk/groq": "^4.0",
+    "@ai-sdk/groq": "^4.0.34",
     "@ai-sdk/mistral": "^4.0.13",
     "@ai-sdk/openai": "^4.0",
     "@ai-sdk/otel": "^1.0.2",

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

@@ -1,7 +1,7 @@
 Study the page and figure out its business purpose. What is this page FOR? What would a user come here to do?
 
 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 data page (lists, tables): test create, edit and delete as separate tests, each preparing the item it acts on
 - 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

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

@@ -29,7 +29,6 @@ interface ActionResultData extends WebPageState {
     focusedElement?: FocusedElement | null;
     iframeURL?: string;
     links?: Link[];
-    overlayHtml?: string;
 }
 export interface PageDiff {
     urlChanged: boolean;
@@ -42,6 +41,7 @@ export interface PageDiff {
     consoleErrors?: string[];
     htmlParts?: HtmlDiffPart[];
     iframes?: string;
+    areaOfInterest?: string;
 }
 export interface ToolResultMetadata {
     url: string;
@@ -84,6 +84,10 @@ export declare class ActionResult implements ActionResultData {
     links: Link[];
     verifications?: Record<string, boolean>;
     overlay: Overlay;
+    _diffCache: {
+        previousId: number | undefined;
+        diff: Diff;
+    } | null;
     constructor(data: ActionResultData);
     get hash(): string;
     get html(): string;
@@ -117,8 +121,10 @@ export declare class ActionResult implements ActionResultData {
     get relativeUrl(): string | null;
     get isInsideIframe(): boolean;
     getStateHash(): string;
+    get baseHash(): string;
     diff(previousState: ActionResult | null): Promise<Diff>;
     toToolResult(previousState: ActionResult | null, locator: string): Promise<ToolResultMetadata>;
+    computeStateHash(includeRegion: boolean): string;
     consoleErrors(): string[];
 }
 export declare class Diff {
@@ -140,6 +146,8 @@ export declare class Diff {
     get ariaChangeCount(): number;
     get htmlDiff(): HtmlDiffResult | null;
     get messages(): string[];
+    get similarity(): number;
+    get pageSize(): number;
     calculate(): Promise<void>;
 }
 export interface NetworkCall {

package/dist/src/action-result.js

@@ -39,6 +39,7 @@ export class ActionResult {
     links = [];
     verifications;
     overlay = new Overlay();
+    _diffCache = null;
     constructor(data) {
         this.id = data.id;
         this.timestamp = data.timestamp ?? new Date();
@@ -108,6 +109,7 @@ export class ActionResult {
     set html(value) {
         this._html = value;
         this.snapshotCache.clear();
+        this._diffCache = null;
     }
     get screenshot() {
         if (this._screenshot) {
@@ -193,6 +195,14 @@ export class ActionResult {
     isRelevantExperienceRecord(record, options) {
         if (!record.url || !this.url)
             return false;
+        if (record.region && this.overlay.name !== record.region)
+            return false;
+        if (record.root) {
+            if (!this.overlay.present)
+                return false;
+            if (this.overlay.root && this.overlay.root !== record.root)
+                return false;
+        }
         if (this.isMatchedBy(record))
             return true;
         if (!options?.includeDescendantExperience)
@@ -386,24 +396,17 @@ export class ActionResult {
         return !!this.iframeURL;
     }
     getStateHash() {
-        const parts = [];
-        parts.push(this.relativeUrl || this.url || '/');
-        this.extractHeadings(this.html);
-        if (this.h1)
-            parts.push(`h1_${this.h1}`);
-        if (this.h2)
-            parts.push(`h2_${this.h2}`);
-        let stateString = slugify(parts.map((part) => part.substring(0, 100)).join('_'));
-        if (stateString.length > 200) {
-            stateString = stateString.substring(0, 200);
-            if (stateString.endsWith('_')) {
-                stateString = stateString.slice(0, -1);
-            }
-        }
-        return stateString;
+        return this.computeStateHash(true);
+    }
+    get baseHash() {
+        return this.computeStateHash(false);
     }
     async diff(previousState) {
-        return Diff.create(this, previousState);
+        if (this._diffCache && this._diffCache.previousId === previousState?.id)
+            return this._diffCache.diff;
+        const diff = await Diff.create(this, previousState);
+        this._diffCache = { previousId: previousState?.id, diff };
+        return diff;
     }
     async toToolResult(previousState, locator) {
         const result = {
@@ -443,7 +446,18 @@ export class ActionResult {
             pageDiff.ariaChanges = diff.ariaChanged;
             pageDiff.ariaChangeCount = diff.ariaChangeCount;
         }
-        if (diff.htmlParts.length > 0) {
+        if (this.overlay.present && (!previousState.overlay.present || previousState.overlay.name !== this.overlay.name)) {
+            pageDiff.areaOfInterest = this.overlay.describe();
+        }
+        if (pageDiff.areaOfInterest && this.overlay.html && this.overlay.root) {
+            const htmlConfig = ConfigParser.getInstance().getConfig().html;
+            let subtree = await minifyHtml(htmlCombinedSnapshot(this.overlay.html, htmlConfig?.combined));
+            if (subtree.length > HTML_PART_SUBTREE_BUDGET) {
+                subtree = `${subtree.slice(0, HTML_PART_SUBTREE_BUDGET)}...<!-- truncated -->`;
+            }
+            pageDiff.htmlParts = [{ container: this.overlay.root, subtree, rawSize: subtree.length, added: [], removed: [] }];
+        }
+        else if (diff.isSameUrl() && diff.htmlParts.length > 0) {
             const collapsed = collapseHtmlParts(await diff.cleanedHtmlParts());
             if (collapsed.length > 0) {
                 pageDiff.htmlParts = collapsed;
@@ -456,6 +470,25 @@ export class ActionResult {
         }
         return result;
     }
+    computeStateHash(includeRegion) {
+        const parts = [];
+        parts.push(this.relativeUrl || this.url || '/');
+        this.extractHeadings(this.html);
+        if (this.h1)
+            parts.push(`h1_${this.h1}`);
+        if (this.h2)
+            parts.push(`h2_${this.h2}`);
+        if (includeRegion && this.overlay.present && this.overlay.name)
+            parts.push(`region_${this.overlay.name}`);
+        let stateString = slugify(parts.map((part) => part.substring(0, 100)).join('_'));
+        if (stateString.length > 200) {
+            stateString = stateString.substring(0, 200);
+            if (stateString.endsWith('_')) {
+                stateString = stateString.slice(0, -1);
+            }
+        }
+        return stateString;
+    }
     consoleErrors() {
         const errors = [];
         for (const log of this.browserLogs) {
@@ -560,14 +593,20 @@ export class Diff {
     get messages() {
         return this._messages;
     }
+    get similarity() {
+        return this._htmlDiffResult?.similarity ?? 0;
+    }
+    get pageSize() {
+        return this._htmlDiffResult?.pageSize ?? 0;
+    }
     async calculate() {
         if (!this.previous)
             return;
+        this._htmlDiffResult = await htmlDiff(this.previous.html, this.current.html, ConfigParser.getInstance().getConfig().html);
         if (!this._isSameUrl) {
             this._messages = liveRegionMessages(this.previous.html, this.current.html);
             return;
         }
-        this._htmlDiffResult = await htmlDiff(this.previous.html, this.current.html, ConfigParser.getInstance().getConfig().html);
         this._messages = this._htmlDiffResult.messages;
         const ariaDiff = diffAriaSnapshots(this.previous.ariaSnapshot, this.current.ariaSnapshot);
         this._ariaDiffResult = ariaDiff.text;

package/dist/src/action.d.ts

@@ -33,7 +33,7 @@ declare class Action {
         includeScreenshot?: boolean;
         codeBlock?: string;
     }): Promise<ActionResult>;
-    captureOverlayHtml(): Promise<string>;
+    detectRegionOfInterest(result: ActionResult): Promise<void>;
     captureMainDocumentStatus(): Promise<number | undefined>;
     captureResponses(): () => void;
     recordNetworkCall(request: any, status: number): void;

package/dist/src/action.js

@@ -8,9 +8,9 @@ import { clearActivity, setActivity } from "./activity.js";
 import { ConfigParser, outputPath } from './config.js';
 import { Observability } from "./observability.js";
 import { browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from "./utils/browser-errors.js";
-import { captureHtmlForSnapshot, getVisibleOverlayHtmlExtractorSource, htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
+import { captureHtmlForSnapshot, htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
-import { Overlay } from './utils/overlay.js';
+import { Overlay, OverlayPage } from './utils/overlay.js';
 import { sleep, waitForPageReadiness } from "./utils/page-readiness.js";
 import { safeFilename } from "./utils/strings.js";
 import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from "./utils/web-sandbox.js";
@@ -133,13 +133,10 @@ class Action {
             let ariaSnapshot = null;
             let ariaSnapshotFile = undefined;
             let focusedElement = null;
-            let overlayHtml = '';
             try {
                 const page = this.playwrightHelper.page;
                 ariaSnapshot = await page.locator('body').ariaSnapshot();
                 focusedElement = await page.evaluate(readFocusedElement);
-                if (!frame)
-                    overlayHtml = await this.captureOverlayHtml();
             }
             catch (err) {
                 debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
@@ -166,9 +163,10 @@ class Action {
                 ariaSnapshot,
                 ariaSnapshotFile,
                 focusedElement,
-                overlayHtml: overlayHtml || undefined,
                 iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
+            if (!frame)
+                await this.detectRegionOfInterest(result).catch((err) => debugLog('Region detection failed:', err.message));
             this.stateManager.updateState(result, codeBlock);
             return result;
         }
@@ -181,11 +179,64 @@ class Action {
             return new ActionResult({ url, error: msg });
         }
     }
-    async captureOverlayHtml() {
-        return this.playwrightHelper.page.evaluate(({ extractorSource, config }) => {
-            const extract = new Function(`return ${extractorSource}`)();
-            return extract(config);
-        }, { extractorSource: getVisibleOverlayHtmlExtractorSource(), config: Overlay.captureConfig() });
+    async detectRegionOfInterest(result) {
+        const previousState = this.stateManager.getCurrentState();
+        if (!previousState)
+            return;
+        const previous = ActionResult.fromState(previousState);
+        const previousOverlay = previous.overlay;
+        const sameUrl = !!previous.url && result.isSameUrl({ url: previous.url });
+        const overlayPage = new OverlayPage(this.playwrightHelper.page);
+        if (result.overlay.detected && previousOverlay.detected && previousOverlay.root && previousOverlay.type === result.overlay.type && previousOverlay.name === result.overlay.name) {
+            result.overlay = previousOverlay;
+            return;
+        }
+        if (!previous.html)
+            return;
+        if (previous.html === result.html) {
+            if (sameUrl && previousOverlay.present && previousOverlay.xpath && !result.overlay.detected)
+                result.overlay = previousOverlay;
+            return;
+        }
+        let carried = null;
+        if (sameUrl && previousOverlay.present && previousOverlay.xpath) {
+            if (await overlayPage.isStillOpen(previousOverlay)) {
+                carried = previousOverlay;
+            }
+            else {
+                debugLog(`Region closed: ${previousOverlay.name || previousOverlay.type}`);
+                if (!result.overlay.detected) {
+                    const parent = previousOverlay.parent;
+                    if (parent?.xpath) {
+                        const restored = new Overlay(parent);
+                        if (await overlayPage.isStillOpen(restored))
+                            result.overlay = restored;
+                    }
+                    return;
+                }
+            }
+        }
+        const diff = await result.diff(previous);
+        const detected = await overlayPage.detectRegion({
+            parts: diff.htmlParts,
+            pageSize: diff.pageSize,
+            similarity: diff.similarity,
+            sameUrl,
+            previousHtml: previous.html,
+        });
+        if (result.overlay.detected) {
+            if (detected)
+                result.overlay = result.overlay.withGeometry(detected);
+            return;
+        }
+        if (detected) {
+            result.overlay = detected;
+            if (carried)
+                result.overlay = detected.withParent(carried);
+            return;
+        }
+        if (carried)
+            result.overlay = carried;
     }
     async captureMainDocumentStatus() {
         if (this.mainDocumentStatus)
@@ -349,6 +400,14 @@ class Action {
                 await recorder.reset();
                 await recorder.start();
             }
+            if (executedSteps.length > 0) {
+                codeString = executedSteps.map((step) => step.command).join('\n');
+            }
+            if (!isFatalBrowserError(err)) {
+                const captured = await this.captureOnce({ codeBlock: codeString }).catch(() => null);
+                if (captured && !captured.error)
+                    this.actionResult = captured;
+            }
             this.assertionSteps = [];
             throw err;
         }
@@ -448,14 +507,30 @@ async function captureTitle(page, actor) {
 }
 const ASSERTION_STEP_NAMES = new Set(['see', 'dontSee', 'seeElement', 'dontSeeElement', 'seeInField', 'dontSeeInField', 'seeInCurrentUrl', 'dontSeeInCurrentUrl']);
 export const attachStepLogger = (target, assertionsTarget) => {
+    const recorded = new WeakMap();
+    let batchFailed = false;
     const listener = (step, error) => {
         if (!step?.toCode)
             return;
         if (step.name?.startsWith('grab'))
             return;
+        const existing = recorded.get(step);
+        if (existing) {
+            if (!error && !existing.success) {
+                existing.success = true;
+                existing.error = undefined;
+                batchFailed = target.some((entry) => !entry.success);
+            }
+            return;
+        }
+        if (batchFailed)
+            return;
         const executed = { command: step.toCode(), success: !error };
-        if (error)
+        if (error) {
             executed.error = errorToString(error);
+            batchFailed = true;
+        }
+        recorded.set(step, executed);
         target.push(executed);
         if (assertionsTarget && ASSERTION_STEP_NAMES.has(step.name)) {
             assertionsTarget.push({ name: step.name, args: step.args || [] });

package/dist/src/ai/captain.js

@@ -137,7 +137,7 @@ export class Captain extends CaptainBase {
         const headingLines = formatHeadings(state);
         const headingsBlock = headingLines.join('\n');
         let pageSummary = '';
-        const cachedResearch = Researcher.getCachedResearch(state);
+        const cachedResearch = Researcher.getCachedResearch(actionResult);
         if (cachedResearch) {
             pageSummary = `<page_summary>\n${this.explorBot.agentResearcher().extractBrief(cachedResearch)}\n</page_summary>`;
         }

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

@@ -135,7 +135,6 @@ export declare class Driller extends TaskAgent implements Agent {
     createVerifiedActionTools(baseTools: Record<string, any>, component: ComponentInfo): Record<string, any>;
     hasVerifiedAction(componentId: string): boolean;
     detectNestedOverlayContext(component: ComponentInfo, result: any): Promise<string | null>;
-    getVisibleOverlayHtml(): Promise<string>;
     getComponentScopeHtml(component: ComponentInfo, originalState: ActionResult): Promise<string>;
     saveToKnowledge(knowledgePath: string, state: ActionResult, results: InteractionResult[]): Promise<void>;
     generateKnowledgeContent(state: ActionResult, interactions: InteractionResult[]): string;