explorbot 0.4.1 → 0.4.2

package/dist/boat/doc-collector/src/docs-renderer.js

@@ -3,7 +3,7 @@ import matter from 'gray-matter';
 import { APPLICATION_SPEC_FORMAT, APPLICATION_SPEC_VERSION } from "../../../src/application-spec-contract.js";
 import { normalizeInlineText } from "../../../src/utils/strings.js";
 import { buildStateGraph, renderMermaidFromGraph, renderPageStateDiagram, renderStateMapFromGraph } from "./state-diagram.js";
-function renderPageDocumentation(state, documentation, screenshots = []) {
+function renderPageDocumentation(state, documentation, screenshots = [], evidence = []) {
     const lines = [];
     lines.push(`# ${state.url}`);
     lines.push('');
@@ -15,6 +15,35 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
     lines.push('');
     lines.push(ensureSentence(documentation.summary));
     lines.push('');
+    lines.push('## User Can');
+    lines.push('');
+    if (documentation.can.length === 0) {
+        lines.push('- No proven actions were identified from the collected research.');
+        lines.push('');
+    }
+    for (const [index, item] of documentation.can.entries()) {
+        lines.push(`- ${normalizeAction(item.action)} -> ${item.scope}`);
+        lines.push(`  Proof: ${ensureSentence(item.evidence)}`);
+        const shot = evidence[index];
+        if (shot) {
+            lines.push('');
+            lines.push(`  ![${normalizeInlineText(item.action)}](${shot.relativePath})`);
+        }
+        lines.push('');
+    }
+    lines.push('## User Might');
+    lines.push('');
+    if (documentation.might.length === 0) {
+        lines.push('- No assumption-based actions were identified.');
+        lines.push('');
+    }
+    for (const item of documentation.might) {
+        lines.push(`- ${normalizeAction(item.action, 'might')} -> ${item.scope}`);
+        lines.push(`  Signal: ${ensureSentence(item.evidence)}`);
+    }
+    if (documentation.might.length > 0) {
+        lines.push('');
+    }
     if (screenshots.length > 0) {
         lines.push('## Screenshots');
         lines.push('');
@@ -26,6 +55,24 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
             lines.push('');
         }
     }
+    const navigationLinks = renderNavigationLinks(state);
+    if (navigationLinks.length > 0) {
+        lines.push('## Navigation');
+        lines.push('');
+        for (const link of navigationLinks) {
+            lines.push(`- ${link.title}: ${link.url}`);
+        }
+        lines.push('');
+    }
+    const qualityNotes = documentation.qualityNotes;
+    if (qualityNotes && qualityNotes.length > 0) {
+        lines.push('## Coverage Notes');
+        lines.push('');
+        for (const note of qualityNotes) {
+            lines.push(`- ${ensureSentence(note)}`);
+        }
+        lines.push('');
+    }
     const interactions = documentation.interactions;
     const pageStateDiagram = renderPageStateDiagram(state.title || state.url || 'page', state.url || '', interactions || []);
     if (pageStateDiagram) {
@@ -57,41 +104,6 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
             }
         }
     }
-    lines.push('## User Can');
-    lines.push('');
-    if (documentation.can.length === 0) {
-        lines.push('- No proven actions were identified from the collected research.');
-        lines.push('');
-    }
-    for (const item of documentation.can) {
-        lines.push(`- ${normalizeAction(item.action)} -> ${item.scope}`);
-        lines.push(`  Proof: ${ensureSentence(item.evidence)}`);
-    }
-    if (documentation.can.length > 0) {
-        lines.push('');
-    }
-    lines.push('## User Might');
-    lines.push('');
-    if (documentation.might.length === 0) {
-        lines.push('- No assumption-based actions were identified.');
-        lines.push('');
-    }
-    for (const item of documentation.might) {
-        lines.push(`- ${normalizeAction(item.action, 'might')} -> ${item.scope}`);
-        lines.push(`  Signal: ${ensureSentence(item.evidence)}`);
-    }
-    if (documentation.might.length > 0) {
-        lines.push('');
-    }
-    const qualityNotes = documentation.qualityNotes;
-    if (qualityNotes && qualityNotes.length > 0) {
-        lines.push('## Coverage Notes');
-        lines.push('');
-        for (const note of qualityNotes) {
-            lines.push(`- ${ensureSentence(note)}`);
-        }
-        lines.push('');
-    }
     return matter.stringify(`${lines.join('\n').trimEnd()}\n`, {
         url: state.url,
         format: APPLICATION_SPEC_FORMAT,
@@ -111,17 +123,7 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
     lines.push('');
     const graph = buildStateGraph(outputDir, pages);
     const mermaid = renderMermaidFromGraph(graph, true);
-    lines.push('## State Transitions');
-    lines.push('');
-    lines.push(`\`\`\`mermaid\n${mermaid}\n\`\`\``);
-    lines.push('');
     const stateMap = renderStateMapFromGraph(graph);
-    if (stateMap) {
-        lines.push('### State Index');
-        lines.push('');
-        lines.push(stateMap);
-        lines.push('');
-    }
     lines.push('## Pages');
     lines.push('');
     if (pages.length === 0) {
@@ -179,8 +181,29 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
         }
         lines.push('');
     }
+    lines.push('## State Transitions');
+    lines.push('');
+    lines.push(`\`\`\`mermaid\n${mermaid}\n\`\`\``);
+    lines.push('');
+    if (stateMap) {
+        lines.push('### State Index');
+        lines.push('');
+        lines.push(stateMap);
+        lines.push('');
+    }
     return `${lines.join('\n').trimEnd()}\n`;
 }
+function renderNavigationLinks(state) {
+    const links = [];
+    const seen = new Set();
+    for (const link of state.links || []) {
+        if (!link.url || seen.has(link.url))
+            continue;
+        seen.add(link.url);
+        links.push({ title: normalizeInlineText(link.title) || link.url, url: link.url });
+    }
+    return links;
+}
 function normalizeAction(action, kind = 'can') {
     const trimmed = normalizeInlineText(action);
     if (!trimmed) {

package/dist/boat/doc-collector/src/interaction-screenshots.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from 'node:fs';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
+import { removeVisualAnnotations } from "../../../src/ai/researcher/coordinates.js";
 const REGION_PADDING = 30;
 const SCREENSHOT_OPTIONS = { animations: 'disabled', caret: 'hide' };
 export async function captureInteractionBefore(page) {
@@ -43,7 +44,7 @@ export function findChangedRegion(beforeScreenshot, afterScreenshot, padding = R
     const changedPixels = findChangedPixelBounds(before, after);
     return changedPixels ? addPadding(changedPixels, before.width, before.height, padding) : null;
 }
-function saveRegion(after, region, filePath) {
+export function saveRegion(after, region, filePath) {
     const cropped = new PNG({ width: region.width, height: region.height });
     PNG.bitblt(after, cropped, region.x, region.y, region.width, region.height, 0, 0);
     writeFileSync(filePath, PNG.sync.write(cropped));
@@ -69,22 +70,28 @@ function findChangedPixelBounds(before, after) {
     }
     return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
 }
-function addPadding(region, imageWidth, imageHeight, padding = REGION_PADDING) {
+export function regionAround(png, box, viewport, padding) {
+    let scaleX = 1;
+    let scaleY = 1;
+    if (viewport) {
+        scaleX = png.width / viewport.width;
+        scaleY = png.height / viewport.height;
+    }
+    const scaled = {
+        x: Math.round(box.x * scaleX),
+        y: Math.round(box.y * scaleY),
+        width: Math.round(box.width * scaleX),
+        height: Math.round(box.height * scaleY),
+    };
+    return addPadding(scaled, png.width, png.height, Math.round(padding * scaleX));
+}
+export function addPadding(region, imageWidth, imageHeight, padding = REGION_PADDING) {
     const x = Math.max(0, region.x - padding);
     const y = Math.max(0, region.y - padding);
     const maxX = Math.min(imageWidth, region.x + region.width + padding);
     const maxY = Math.min(imageHeight, region.y + region.height + padding);
     return { x, y, width: maxX - x, height: maxY - y };
 }
-async function removeVisualAnnotations(page) {
-    try {
-        await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
-            for (const element of elements)
-                element.remove();
-        });
-    }
-    catch { }
-}
 async function findOverlayRegion(page, image, detectUnmarkedOverlay) {
     let box = null;
     try {

package/dist/boat/doc-collector/src/screenshots.js

@@ -1,14 +1,21 @@
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { PNG } from 'pngjs';
+import { removeVisualAnnotations } from "../../../src/ai/researcher/coordinates.js";
 import { parseResearchSections } from "../../../src/ai/researcher/parser.js";
+import { parseAriaLocator } from "../../../src/utils/aria.js";
+import { normalizeUrl } from "../../../src/state-manager.js";
 import { safeFilename, sanitizeFilename } from "../../../src/utils/strings.js";
-import { captureInteractionAfter, captureInteractionBefore } from "./interaction-screenshots.js";
+import { captureInteractionAfter, captureInteractionBefore, regionAround, saveRegion } from "./interaction-screenshots.js";
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
+const EVIDENCE_PADDING = 250;
 export async function captureDocumentationScreenshots(explorer, state, research, options) {
     const page = explorer.page;
     if (!page) {
         return [];
     }
+    await dismissTransientOverlay(page);
+    await removeVisualAnnotations(page);
     mkdirSync(options.screenshotsDir, { recursive: true });
     const screenshots = [];
     const pageName = sanitizeFilename(state.url || 'page') || 'page';
@@ -26,6 +33,102 @@ export async function captureDocumentationScreenshots(explorer, state, research,
     }
     return screenshots;
 }
+export async function captureEvidenceScreenshots(explorer, state, documentation, options) {
+    const page = explorer.page;
+    if (!page) {
+        return documentation.can.map(() => null);
+    }
+    await dismissTransientOverlay(page);
+    await removeVisualAnnotations(page);
+    if (!isOnDocumentedPage(page, state)) {
+        return documentation.can.map(() => null);
+    }
+    mkdirSync(options.screenshotsDir, { recursive: true });
+    const pageName = sanitizeFilename(state.url || 'page') || 'page';
+    const shots = [];
+    for (const [index, item] of documentation.can.entries()) {
+        shots.push(await captureEvidenceScreenshot(page, pageName, index, item, options));
+    }
+    return shots;
+}
+async function captureEvidenceScreenshot(page, pageName, index, item, options) {
+    if (!item.element)
+        return null;
+    const element = resolveResearchLocator(item.element, options.research);
+    if (!element)
+        return null;
+    const locatorInfo = parseAriaLocator(element);
+    try {
+        const locator = resolveEvidenceLocator(page, element, locatorInfo);
+        if ((await locator.count()) !== 1)
+            return null;
+        await locator.scrollIntoViewIfNeeded({ timeout: 2000 });
+        const box = await locator.boundingBox();
+        if (!box || box.width <= 0 || box.height <= 0)
+            return null;
+        const image = await page.screenshot();
+        const png = PNG.sync.read(image);
+        const region = regionAround(png, box, await page.viewportSize(), EVIDENCE_PADDING);
+        const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_can_${index + 1}`, '.png'));
+        saveRegion(png, region, filePath);
+        return {
+            title: item.action,
+            path: filePath,
+            relativePath: toMarkdownPath(options.pageFilePath, filePath),
+            kind: 'evidence',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function resolveResearchLocator(requested, research) {
+    if (!research)
+        return requested;
+    const requestedAria = parseAriaLocator(requested);
+    const requestedCss = unwrapLocator(requested);
+    for (const section of parseResearchSections(research)) {
+        for (const element of section.elements) {
+            if (requestedAria && element.aria?.role === requestedAria.role && element.aria.text === requestedAria.text) {
+                return `{ role: '${element.aria.role}', text: '${element.aria.text}' }`;
+            }
+            if (element.css && requestedCss === unwrapLocator(element.css))
+                return element.css;
+        }
+    }
+    return null;
+}
+function unwrapLocator(locator) {
+    const trimmed = locator.trim();
+    const first = trimmed.at(0);
+    const last = trimmed.at(-1);
+    if (first === last && (first === '`' || first === '"' || first === "'")) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function isOnDocumentedPage(page, state) {
+    try {
+        const current = new URL(page.url());
+        const expected = new URL(state.url || '', current.origin);
+        return current.origin === expected.origin && normalizeUrl(current.href) === normalizeUrl(expected.href);
+    }
+    catch {
+        return false;
+    }
+}
+function resolveEvidenceLocator(page, element, locatorInfo) {
+    if (locatorInfo?.text) {
+        return page.getByRole(locatorInfo.role, { name: locatorInfo.text, exact: true });
+    }
+    return page.locator(element);
+}
+async function dismissTransientOverlay(page) {
+    try {
+        await page.keyboard.press('Escape');
+    }
+    catch { }
+}
 export function getScreenshotSections(research) {
     const sections = [];
     const seen = new Set();

package/dist/boat/doc-collector/src/template-dedup.js

@@ -0,0 +1,27 @@
+import { ariaTemplateSignature } from "../../../src/utils/aria.js";
+import { diceSimilarity } from "../../../src/utils/similarity.js";
+const TEMPLATE_MIN_SIGNATURE_SIZE = 8;
+const TEMPLATE_SIMILARITY_THRESHOLD = 90;
+export function buildTemplateRecord(url, snapshot) {
+    const signature = ariaTemplateSignature(snapshot);
+    if (signature.size < TEMPLATE_MIN_SIGNATURE_SIZE)
+        return null;
+    return { url, signature };
+}
+export function findTemplateMatch(snapshot, known, threshold = TEMPLATE_SIMILARITY_THRESHOLD) {
+    const signature = ariaTemplateSignature(snapshot);
+    if (signature.size < TEMPLATE_MIN_SIGNATURE_SIZE)
+        return null;
+    let bestUrl = null;
+    let bestScore = 0;
+    for (const record of known) {
+        const score = diceSimilarity(signature, record.signature);
+        if (score < bestScore)
+            continue;
+        bestScore = score;
+        bestUrl = record.url;
+    }
+    if (bestScore < threshold)
+        return null;
+    return bestUrl;
+}

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

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import dedent from 'dedent';
 import { keepServerRunning } from "../../../src/browser-server.js";
+import { RecommendedModelsCommand } from "../../../src/commands/recommended-models-command.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { isVerboseMode, setQuietMode } from "../../../src/utils/logger.js";
 import { clearActivityLine, trackActivityLine } from "./activity-line.js";
@@ -199,6 +200,7 @@ export function createPrimaCommands(name = 'prima') {
         await prima.stop().catch(() => { });
         process.exit(0);
     });
+    RecommendedModelsCommand.register(cmd);
     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) => {

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

@@ -14,7 +14,7 @@ import { getAliveEndpoint, launchServer, listInstances, stopServer } from "../..
 import { ConfigCommand } from "../../../src/commands/config-command.js";
 import { ConfigMissingError, ConfigParser, EXPLORBOT_ENV_VARS, outputPath } from "../../../src/config.js";
 import { ExplorBot } from "../../../src/explorbot.js";
-import { listSites } from "../../../src/global-config.js";
+import { findSiteWith, listSites } from "../../../src/global-config.js";
 import { Reporter } from "../../../src/reporter.js";
 import { Stats } from "../../../src/stats.js";
 import { Task, Test, TestResult } from "../../../src/test-plan.js";
@@ -1006,8 +1006,7 @@ export class Prima {
     }
     async status(hash) {
         if (!this.artifactsDir) {
-            const sites = listSites();
-            const site = sites.find((candidate) => existsSync(path.join(candidate.dir, 'output', 'prima', hash))) || sites[0];
+            const site = findSiteWith(path.join('output', 'prima', hash)) || listSites()[0];
             if (site && !this.configBaseUrl())
                 this.sessionUrl = site.url;
             await this.loadConfig();
@@ -1049,7 +1048,7 @@ export class Prima {
             aria: result.ariaSnapshot,
             html: await result.combinedHtml(),
             screenshot: result.screenshot,
-            requests: this.bot.requestStore().getRequests(),
+            requests: this.bot.requestStore().getMadeRequests(),
         });
     }
     statusHash() {

package/dist/package.json

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

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

@@ -2,7 +2,7 @@ import { type HtmlConfig } from './config.js';
 import type { Link, WebPageState } from './state-manager.js';
 import { TTLCache } from './utils/cache.js';
 import { type HtmlDiffPart, type HtmlDiffResult } from './utils/html-diff.js';
-import { Overlay } from './utils/overlay.js';
+import { Region } from './utils/region.js';
 interface ActionResultData extends WebPageState {
     html?: string;
     fullUrl?: string | undefined;
@@ -83,7 +83,7 @@ export declare class ActionResult implements ActionResultData {
     notes: string[];
     links: Link[];
     verifications?: Record<string, boolean>;
-    overlay: Overlay;
+    overlay: Region;
     _diffCache: {
         previousId: number | undefined;
         diff: Diff;

package/dist/src/action-result.js

@@ -6,6 +6,7 @@ import { htmlDiff, liveRegionMessages } from "./utils/html-diff.js";
 import { extractHeadings, extractLinks, extractTargetedHtml, htmlCombinedSnapshot, htmlMinimalUISnapshot, htmlTextSnapshot, minifyHtml } from "./utils/html.js";
 import { createDebug } from "./utils/logger.js";
 import { Overlay } from "./utils/overlay.js";
+import { Region } from "./utils/region.js";
 import { slugify } from "./utils/strings.js";
 import { extractStatePath, matchesUrl } from "./utils/url-matcher.js";
 const debugLog = createDebug('explorbot:state');
@@ -38,7 +39,7 @@ export class ActionResult {
     notes = [];
     links = [];
     verifications;
-    overlay = new Overlay();
+    overlay = new Region();
     _diffCache = null;
     constructor(data) {
         this.id = data.id;
@@ -198,7 +199,7 @@ export class ActionResult {
         if (record.region && this.overlay.name !== record.region)
             return false;
         if (record.root) {
-            if (!this.overlay.present)
+            if (!this.overlay.isOpen)
                 return false;
             if (this.overlay.root && this.overlay.root !== record.root)
                 return false;
@@ -446,15 +447,12 @@ export class ActionResult {
             pageDiff.ariaChanges = diff.ariaChanged;
             pageDiff.ariaChangeCount = diff.ariaChangeCount;
         }
-        if (this.overlay.present && (!previousState.overlay.present || previousState.overlay.name !== this.overlay.name)) {
+        if (this.overlay.isOpen && (!previousState.overlay.isOpen || 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 -->`;
-            }
+            const subtree = trimSubtree(await minifyHtml(htmlCombinedSnapshot(this.overlay.html, htmlConfig?.combined)));
             pageDiff.htmlParts = [{ container: this.overlay.root, subtree, rawSize: subtree.length, added: [], removed: [] }];
         }
         else if (diff.isSameUrl() && diff.htmlParts.length > 0) {
@@ -478,7 +476,7 @@ export class ActionResult {
             parts.push(`h1_${this.h1}`);
         if (this.h2)
             parts.push(`h2_${this.h2}`);
-        if (includeRegion && this.overlay.present && this.overlay.name)
+        if (includeRegion && this.overlay.isOpen && this.overlay.name)
             parts.push(`region_${this.overlay.name}`);
         let stateString = slugify(parts.map((part) => part.substring(0, 100)).join('_'));
         if (stateString.length > 200) {
@@ -511,6 +509,7 @@ const CONSOLE_ERROR_LIMIT = 3;
 const HTML_PARTS_TOTAL_BUDGET = 8000;
 const HTML_PARTS_COUNT_LIMIT = 8;
 const HTML_PART_SUBTREE_BUDGET = 2000;
+const SUBTREE_TAIL_BUDGET = 600;
 function collapseHtmlParts(parts) {
     const total = parts.reduce((sum, p) => sum + p.subtree.length, 0);
     const fullPageReRender = total > HTML_PARTS_TOTAL_BUDGET || parts.length > HTML_PARTS_COUNT_LIMIT;
@@ -522,15 +521,14 @@ function collapseHtmlParts(parts) {
             subtree: `<html><head></head><body>...collapsed (${part.subtree.length} chars, ${part.added.length} added, ${part.removed.length} removed)...</body></html>`,
         }));
     }
-    return parts.map((part) => {
-        if (part.subtree.length <= HTML_PART_SUBTREE_BUDGET)
-            return part;
-        const head = part.subtree.slice(0, HTML_PART_SUBTREE_BUDGET);
-        return {
-            ...part,
-            subtree: `${head}...<!-- truncated ${part.subtree.length - HTML_PART_SUBTREE_BUDGET} chars -->`,
-        };
-    });
+    return parts.map((part) => ({ ...part, subtree: trimSubtree(part.subtree) }));
+}
+function trimSubtree(subtree) {
+    if (subtree.length <= HTML_PART_SUBTREE_BUDGET)
+        return subtree;
+    const head = subtree.slice(0, HTML_PART_SUBTREE_BUDGET - SUBTREE_TAIL_BUDGET);
+    const tail = subtree.slice(-SUBTREE_TAIL_BUDGET);
+    return `${head}...<!-- truncated ${subtree.length - HTML_PART_SUBTREE_BUDGET} chars -->${tail}`;
 }
 export class Diff {
     current;

package/dist/src/action.d.ts

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

package/dist/src/action.js

@@ -166,7 +166,7 @@ class Action {
                 iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
             if (!frame)
-                await this.detectRegionOfInterest(result).catch((err) => debugLog('Region detection failed:', err.message));
+                await this.detectRegion(result).catch((err) => debugLog('Region detection failed:', err.message));
             this.stateManager.updateState(result, codeBlock);
             return result;
         }
@@ -179,36 +179,36 @@ class Action {
             return new ActionResult({ url, error: msg });
         }
     }
-    async detectRegionOfInterest(result) {
+    async detectRegion(result) {
         const previousState = this.stateManager.getCurrentState();
         if (!previousState)
             return;
         const previous = ActionResult.fromState(previousState);
-        const previousOverlay = previous.overlay;
+        const previousRegion = 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;
+        if (result.overlay.isModal && previousRegion.isModal && previousRegion.root && previousRegion.type === result.overlay.type && previousRegion.name === result.overlay.name) {
+            result.overlay = previousRegion;
             return;
         }
         if (!previous.html)
             return;
         if (previous.html === result.html) {
-            if (sameUrl && previousOverlay.present && previousOverlay.xpath && !result.overlay.detected)
-                result.overlay = previousOverlay;
+            if (sameUrl && previousRegion.isOpen && previousRegion.xpath && !result.overlay.isModal)
+                result.overlay = previousRegion;
             return;
         }
         let carried = null;
-        if (sameUrl && previousOverlay.present && previousOverlay.xpath) {
-            if (await overlayPage.isStillOpen(previousOverlay)) {
-                carried = previousOverlay;
+        if (sameUrl && previousRegion.isOpen && previousRegion.xpath) {
+            if (await overlayPage.isStillOpen(previousRegion)) {
+                carried = previousRegion;
             }
             else {
-                debugLog(`Region closed: ${previousOverlay.name || previousOverlay.type}`);
-                if (!result.overlay.detected) {
-                    const parent = previousOverlay.parent;
+                debugLog(`Region closed: ${previousRegion.name || previousRegion.type}`);
+                if (!result.overlay.isModal) {
+                    const parent = previousRegion.parent;
                     if (parent?.xpath) {
-                        const restored = new Overlay(parent);
+                        const restored = Overlay.resolve({ overlay: parent });
                         if (await overlayPage.isStillOpen(restored))
                             result.overlay = restored;
                     }
@@ -224,7 +224,7 @@ class Action {
             sameUrl,
             previousHtml: previous.html,
         });
-        if (result.overlay.detected) {
+        if (result.overlay instanceof Overlay) {
             if (detected)
                 result.overlay = result.overlay.withGeometry(detected);
             return;

package/dist/src/ai/fisherman/request-haul.d.ts

@@ -0,0 +1,11 @@
+import type { RequestResult } from '../../api/request-result.js';
+import { type RequestStore } from '../../api/request-store.js';
+export declare class RequestHaul {
+    store: RequestStore;
+    start: number;
+    constructor(store: RequestStore);
+    requests(): RequestResult[];
+    failed(): RequestResult[];
+    successfulWrites(): RequestResult[];
+    byId(): Map<string, RequestResult>;
+}

package/dist/src/ai/fisherman/request-haul.js

@@ -0,0 +1,28 @@
+import { isFailedRequest } from "../../api/request-store.js";
+export class RequestHaul {
+    store;
+    start;
+    constructor(store) {
+        this.store = store;
+        this.start = store.getMadeRequests().length;
+    }
+    requests() {
+        return this.store.getMadeRequests().slice(this.start);
+    }
+    failed() {
+        return this.requests().filter(isFailedRequest);
+    }
+    successfulWrites() {
+        return this.requests().filter((r) => r.isWrite && !r.error && r.status >= 200 && r.status < 400);
+    }
+    byId() {
+        const map = new Map();
+        for (const request of this.successfulWrites()) {
+            const { id } = request.extractIdAndTitle();
+            if (id === undefined)
+                continue;
+            map.set(String(id), request);
+        }
+        return map;
+    }
+}

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

@@ -1,6 +1,7 @@
 import type { ApiClient } from '../api/api-client.js';
 import type { RequestStore } from '../api/request-store.js';
-export declare function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, opts: {
+import type { RequestHaul } from './fisherman/request-haul.js';
+export declare function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, haul: RequestHaul, opts: {
     spec?: any;
     baseEndpoint?: string;
 }): {
@@ -120,6 +121,14 @@ export declare function createFishermanTools(apiClient: ApiClient, requestStore:
     isFinished: () => boolean;
     finishFromText: (text?: string) => void;
 };
+export declare function verifyFinish(haul: RequestHaul, input: {
+    summary: string;
+    created: FishermanResult['created'];
+    failed?: FishermanResult['failed'];
+}): {
+    result: FishermanResult | null;
+    error?: string;
+};
 export interface FishermanResult {
     success: boolean;
     summary: string;