explorbot 0.2.1 → 0.2.2

package/boat/doc-collector/src/ai/documentarian.ts

@@ -94,6 +94,9 @@ class Documentarian {
       if ((interaction.changes?.newElements || 0) > 0) {
         return true;
       }
+      if ((interaction.changes?.removedElements || 0) > 0) {
+        return true;
+      }
       return (interaction.discoveredUrls || []).length > 0;
     });
   }

package/boat/doc-collector/src/ai/tools.ts

@@ -49,7 +49,10 @@ export interface InteractionScreenshot {
   relativePath: string;
 }
 
-export type CaptureInteractionState = (state: WebPageState, transition: DocStateTransition) => Promise<InteractionScreenshot | null>;
+export interface CaptureInteractionState {
+  before(): Promise<Buffer | null>;
+  after(beforeScreenshot: Buffer | null, state: WebPageState, transition: DocStateTransition): Promise<InteractionScreenshot | null>;
+}
 
 const DEFAULT_MAX_PRIMARY_CANDIDATES = 3;
 const DEFAULT_MAX_INTERACTIONS = 5;
@@ -130,6 +133,8 @@ async function executeInteraction(explorer: Explorer, stateManager: StateManager
     return null;
   }
 
+  const beforeScreenshot = await captureState?.before();
+
   const executed = await attemptInteraction(explorer, candidate);
   if (!executed) {
     return null;
@@ -151,13 +156,13 @@ async function executeInteraction(explorer: Explorer, stateManager: StateManager
   });
 
   if (captureState && isMeaningfulStateTransition(transition)) {
-    const screenshot = await captureState(afterState, transition);
+    const screenshot = await captureState.after(beforeScreenshot ?? null, afterState, transition);
     if (screenshot) {
       transition.screenshot = screenshot;
     }
   }
 
-  if (urlChanged || ariaChanges.newCount > 0) {
+  if (urlChanged || ariaChanges.newCount > 0 || ariaChanges.removedCount > 0) {
     await restoreInteractionState(explorer, restoreUrl);
   }
 
@@ -192,11 +197,18 @@ async function restoreInteractionState(explorer: Explorer, restoreUrl: string, p
 }
 
 function buildTransition(candidate: InteractionCandidate, beforeState: WebPageState, afterState: WebPageState, changes: InteractionChanges): DocStateTransition {
+  const existingUrls = new Set(collectLinks(beforeState).map((link) => link.url));
   const transition: DocStateTransition = {
     action: describeAction(candidate),
     before: summarizeInteractiveState(beforeState),
     after: summarizeInteractiveState(afterState),
-    discoveredUrls: collectLinks(afterState).map((link) => link.url),
+    discoveredUrls: [
+      ...new Set(
+        collectLinks(afterState)
+          .map((link) => link.url)
+          .filter((url) => !existingUrls.has(url))
+      ),
+    ],
     newCapabilities: collectDiscoveryNotes(afterState, changes),
     element: buildInteractionElement(candidate),
     changes,
@@ -239,7 +251,7 @@ function isMeaningfulStateTransition(transition: DocStateTransition): boolean {
   if (transition.targetUrl || transition.changes?.urlChanged) {
     return true;
   }
-  return (transition.changes?.newElements || 0) > 0;
+  return (transition.changes?.newElements || 0) > 0 || (transition.changes?.removedElements || 0) > 0;
 }
 
 function buildInteractionElement(candidate: InteractionCandidate): InteractionElement {

package/boat/doc-collector/src/cli.ts

@@ -91,6 +91,7 @@ export function createDocsCommands(name = 'docs'): Command {
             output: 'docs',
             screenshot: true,
             interactive: false,
+            ignoreErrors: true,
             collapseDynamicPages: true,
             scope: 'site',
             includePaths: [],

package/boat/doc-collector/src/config.ts

@@ -115,6 +115,7 @@ class DocbotConfigParser {
           output: 'docs',
           screenshot: true,
           interactive: false,
+          ignoreErrors: true,
           collapseDynamicPages: true,
           scope: 'site',
           includePaths: [],
@@ -151,6 +152,7 @@ interface DocbotConfig {
     maxPages?: number;
     output?: string;
     screenshot?: boolean;
+    ignoreErrors?: boolean | string[];
     prompt?: string;
     collapseDynamicPages?: boolean;
     scope?: 'site' | 'section' | 'subtree';

package/boat/doc-collector/src/docbot.ts

@@ -6,11 +6,12 @@ import { normalizeUrl } from '../../../src/state-manager.ts';
 import { tag } from '../../../src/utils/logger.ts';
 import { sanitizeFilename } from '../../../src/utils/strings.ts';
 import { Documentarian, type PageDocumentation } from './ai/documentarian.ts';
+import type { DocStateTransition } from './ai/tools.ts';
 import { type DocbotConfig, DocbotConfigParser } from './config.ts';
 import { type DocumentedPage, type SkippedPage, renderPageDocumentation, renderSpecIndex } from './docs-renderer.ts';
 import { getDocPageKey, shouldCrawlDocPath } from './path-filter.ts';
 import { extractResearchNavigationTargets } from './research-navigation.ts';
-import { type DocumentationScreenshot, captureDocumentationScreenshots, captureInteractionScreenshot } from './screenshots.ts';
+import { type DocumentationScreenshot, captureBeforeInteraction, captureDocumentationScreenshots, captureInteractionScreenshot } from './screenshots.ts';
 import { renderMermaidBody } from './state-diagram.ts';
 
 class DocBot {
@@ -113,16 +114,18 @@ class DocBot {
           force: true,
         });
         const pagePath = this.getPageFilePath(state.url);
-        const documentation = await this.documentarian.document(state, research, async (interactionState, transition) => {
-          if (!this.shouldUseScreenshots()) {
-            return null;
-          }
-          return captureInteractionScreenshot(this.explorBot.getExplorer(), interactionState, transition, {
-            pageFilePath: pagePath,
-            screenshotsDir: this.getScreenshotsDir(),
-            config: this.config,
-          });
-        });
+        const captureState = this.shouldUseScreenshots()
+          ? {
+              before: () => captureBeforeInteraction(this.explorBot.getExplorer()),
+              after: (beforeScreenshot: Buffer | null, interactionState: WebPageState, transition: DocStateTransition) =>
+                captureInteractionScreenshot(this.explorBot.getExplorer(), beforeScreenshot, interactionState, transition, {
+                  pageFilePath: pagePath,
+                  screenshotsDir: this.getScreenshotsDir(),
+                  config: this.config,
+                }),
+            }
+          : undefined;
+        const documentation = await this.documentarian.document(state, research, captureState);
         const lowSignalReason = this.getLowSignalReason(documentation, research);
         if (lowSignalReason) {
           skipped.push({
@@ -163,6 +166,9 @@ class DocBot {
         }
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
+        if (!this.shouldIgnoreError(error)) {
+          throw error;
+        }
         tag('warning').log(`Skipping ${target}: ${reason}`);
         skipped.push({
           url: target,
@@ -410,6 +416,28 @@ class DocBot {
     return `low-signal page: only ${documentation.can.length} proven actions and ${interactiveCount} interactive elements`;
   }
 
+  private shouldIgnoreError(error: unknown): boolean {
+    const ignoreErrors = this.config.docs?.ignoreErrors;
+    if (ignoreErrors === undefined || ignoreErrors === true) return true;
+    if (ignoreErrors === false) return false;
+
+    const details = [error instanceof Error ? error.name : '', error instanceof Error ? error.message : String(error)];
+    if (typeof error === 'object' && error && 'code' in error) {
+      details.push(String(error.code));
+    }
+    const normalized = details
+      .join(' ')
+      .toLowerCase()
+      .replaceAll(/[\W_]+/g, ' ');
+    return ignoreErrors.some((pattern) => {
+      const normalizedPattern = pattern
+        .trim()
+        .toLowerCase()
+        .replaceAll(/[\W_]+/g, ' ');
+      return normalizedPattern.length > 0 && normalized.includes(normalizedPattern);
+    });
+  }
+
   private countInteractiveElements(research: string): number {
     const matches = [...research.matchAll(/\((\d+) elements?\)/g)];
     return matches.reduce((sum, match) => sum + Number.parseInt(match[1], 10), 0);

package/boat/doc-collector/src/interaction-screenshots.ts

@@ -0,0 +1,160 @@
+import { writeFileSync } from 'node:fs';
+import pixelmatch from 'pixelmatch';
+import type { Page } from 'playwright';
+import { PNG } from 'pngjs';
+
+const REGION_PADDING = 30;
+const SCREENSHOT_OPTIONS = { animations: 'disabled', caret: 'hide' } as const;
+
+export async function captureInteractionBefore(page: Page): Promise<Buffer | null> {
+  await removeVisualAnnotations(page);
+  try {
+    return await page.screenshot(SCREENSHOT_OPTIONS);
+  } catch {
+    return null;
+  }
+}
+
+export async function captureInteractionAfter(page: Page, beforeScreenshot: Buffer | null, filePath: string, detectUnmarkedOverlay = false): Promise<InteractionCaptureResult> {
+  if (!beforeScreenshot) return 'failed';
+
+  await removeVisualAnnotations(page);
+  try {
+    const afterScreenshot = await page.screenshot(SCREENSHOT_OPTIONS);
+    const before = PNG.sync.read(beforeScreenshot);
+    const after = PNG.sync.read(afterScreenshot);
+    if (before.width !== after.width || before.height !== after.height) return 'failed';
+    const changedPixels = findChangedPixelBounds(before, after);
+    if (!changedPixels) return 'unchanged';
+    const fullViewportChanged = changedPixels.x === 0 && changedPixels.y === 0 && changedPixels.width === after.width && changedPixels.height === after.height;
+    const changedRegion = addPadding(changedPixels, after.width, after.height);
+    const overlayRegion = fullViewportChanged ? await findOverlayRegion(page, after, detectUnmarkedOverlay) : null;
+    saveRegion(after, overlayRegion || changedRegion, filePath);
+    return 'captured';
+  } catch {
+    return 'failed';
+  }
+}
+
+export function findChangedRegion(beforeScreenshot: Buffer, afterScreenshot: Buffer, padding = REGION_PADDING): ScreenshotRegion | null {
+  const before = PNG.sync.read(beforeScreenshot);
+  const after = PNG.sync.read(afterScreenshot);
+  if (before.width !== after.width || before.height !== after.height) return null;
+  const changedPixels = findChangedPixelBounds(before, after);
+  return changedPixels ? addPadding(changedPixels, before.width, before.height, padding) : null;
+}
+
+function saveRegion(after: PNG, region: ScreenshotRegion, filePath: string): void {
+  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));
+}
+
+function findChangedPixelBounds(before: PNG, after: PNG): ScreenshotRegion | null {
+  const diff = Buffer.alloc(before.width * before.height * 4);
+  const changedPixels = pixelmatch(before.data, after.data, diff, before.width, before.height, { diffMask: true });
+  if (changedPixels === 0) return null;
+
+  let left = before.width;
+  let top = before.height;
+  let right = 0;
+  let bottom = 0;
+
+  for (let y = 0; y < before.height; y++) {
+    for (let x = 0; x < before.width; x++) {
+      if (diff[(y * before.width + x) * 4 + 3] === 0) continue;
+      left = Math.min(left, x);
+      top = Math.min(top, y);
+      right = Math.max(right, x);
+      bottom = Math.max(bottom, y);
+    }
+  }
+
+  return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+}
+
+function addPadding(region: ScreenshotRegion, imageWidth: number, imageHeight: number, padding = REGION_PADDING): ScreenshotRegion {
+  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: Page): Promise<void> {
+  try {
+    await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+      for (const element of elements) element.remove();
+    });
+  } catch {}
+}
+
+async function findOverlayRegion(page: Page, image: PNG, detectUnmarkedOverlay: boolean): Promise<ScreenshotRegion | null> {
+  let box: { x: number; y: number; width: number; height: number } | null = null;
+  try {
+    const dialogs = page.locator('[role="dialog"]:visible, [role="alertdialog"]:visible, [aria-modal="true"]:visible');
+    if ((await dialogs.count()) > 0) box = await dialogs.last().boundingBox();
+  } catch {}
+
+  if (!box && detectUnmarkedOverlay) {
+    try {
+      box = await findUnmarkedOverlay(page);
+    } catch {}
+  }
+
+  try {
+    const viewport = page.viewportSize();
+    if (!box || !viewport) return null;
+
+    const scaleX = image.width / viewport.width;
+    const scaleY = image.height / viewport.height;
+    const x = Math.max(0, Math.floor(box.x * scaleX) - REGION_PADDING);
+    const y = Math.max(0, Math.floor(box.y * scaleY) - REGION_PADDING);
+    const maxX = Math.min(image.width, Math.ceil((box.x + box.width) * scaleX) + REGION_PADDING);
+    const maxY = Math.min(image.height, Math.ceil((box.y + box.height) * scaleY) + REGION_PADDING);
+    if (maxX <= x || maxY <= y) return null;
+    return { x, y, width: maxX - x, height: maxY - y };
+  } catch {
+    return null;
+  }
+}
+
+async function findUnmarkedOverlay(page: Page): Promise<{ x: number; y: number; width: number; height: number } | null> {
+  return page.evaluate(() => {
+    const elements = [...document.body.querySelectorAll('*')].map((element) => {
+      const style = getComputedStyle(element);
+      const box = element.getBoundingClientRect();
+      const zIndex = Number.parseInt(style.zIndex, 10);
+      return { element, style, box, zIndex, area: box.width * box.height };
+    });
+    const isVisibleLayer = ({ style, box, zIndex }: (typeof elements)[number]) => {
+      if (style.visibility === 'hidden' || style.display === 'none' || Number(style.opacity) === 0) return false;
+      if (box.width <= 0 || box.height <= 0) return false;
+      if (style.position !== 'fixed' && style.position !== 'absolute') return false;
+      return Number.isFinite(zIndex);
+    };
+    const backdropZIndex = elements.filter((item) => isVisibleLayer(item) && item.box.width >= window.innerWidth && item.box.height >= window.innerHeight).reduce((highest, item) => Math.max(highest, item.zIndex), Number.NEGATIVE_INFINITY);
+    if (!Number.isFinite(backdropZIndex)) return null;
+
+    const candidates = elements
+      .filter((item) => {
+        if (!isVisibleLayer(item)) return false;
+        if (item.box.width >= window.innerWidth && item.box.height >= window.innerHeight) return false;
+        if (item.zIndex < backdropZIndex) return false;
+        return item.element.matches('button, input, select, textarea, a[href]') || !!item.element.querySelector('button, input, select, textarea, a[href]');
+      })
+      .sort((left, right) => right.zIndex - left.zIndex || left.area - right.area);
+    const box = candidates[0]?.box;
+    if (!box) return null;
+    return { x: box.x, y: box.y, width: box.width, height: box.height };
+  });
+}
+
+export interface ScreenshotRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type InteractionCaptureResult = 'captured' | 'unchanged' | 'failed';

package/boat/doc-collector/src/screenshots.ts

@@ -3,10 +3,10 @@ import path from 'node:path';
 import { parseResearchSections } from '../../../src/ai/researcher/parser.ts';
 import type Explorer from '../../../src/explorer.ts';
 import type { WebPageState } from '../../../src/state-manager.ts';
-import { detectFocusArea } from '../../../src/utils/aria.ts';
 import { safeFilename, sanitizeFilename } from '../../../src/utils/strings.ts';
 import type { DocStateTransition } from './ai/tools.ts';
 import type { DocbotConfig } from './config.ts';
+import { captureInteractionAfter, captureInteractionBefore } from './interaction-screenshots.ts';
 
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
 
@@ -61,7 +61,7 @@ export function getScreenshotSections(research: string): ScreenshotSection[] {
   return sections;
 }
 
-export async function captureInteractionScreenshot(explorer: Explorer, state: WebPageState, transition: DocStateTransition, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
+export async function captureInteractionScreenshot(explorer: Explorer, beforeScreenshot: Buffer | null, state: WebPageState, transition: DocStateTransition, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
   const page = explorer.page;
   if (!page) {
     return null;
@@ -70,18 +70,11 @@ export async function captureInteractionScreenshot(explorer: Explorer, state: We
   mkdirSync(options.screenshotsDir, { recursive: true });
   const pageName = sanitizeFilename(state.url || 'page') || 'page';
   const stateName = sanitizeFilename(transition.targetState?.label || transition.action) || 'state';
-  const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}`, '.png'));
-  const focus = detectFocusArea(state.ariaSnapshot || null);
-
-  try {
-    if (focus.detected) {
-      await page.locator('[role="dialog"], [role="alertdialog"], [aria-modal="true"]').last().screenshot({ path: filePath });
-    } else {
-      await page.screenshot({ path: filePath });
-    }
-  } catch {
-    return null;
-  }
+  const stateId = state.id ? `_${state.id}` : '';
+  const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}${stateId}`, '.png'));
+  const result = await captureInteractionAfter(page, beforeScreenshot, filePath, transition.changes?.urlChanged !== true);
+  if (result === 'unchanged') return null;
+  if (result === 'failed' && !(await captureViewport(page, filePath))) return null;
 
   return {
     title: transition.targetState?.label || transition.action,
@@ -91,6 +84,21 @@ export async function captureInteractionScreenshot(explorer: Explorer, state: We
   };
 }
 
+export async function captureBeforeInteraction(explorer: Explorer): Promise<Buffer | null> {
+  const page = explorer.page;
+  if (!page) return null;
+  return captureInteractionBefore(page);
+}
+
+async function captureViewport(page: any, filePath: string): Promise<boolean> {
+  try {
+    await page.screenshot({ path: filePath });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function captureFullPageScreenshot(page: any, pageName: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
   const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
   try {

package/dist/boat/doc-collector/src/ai/documentarian.js

@@ -77,6 +77,9 @@ class Documentarian {
             if ((interaction.changes?.newElements || 0) > 0) {
                 return true;
             }
+            if ((interaction.changes?.removedElements || 0) > 0) {
+                return true;
+            }
             return (interaction.discoveredUrls || []).length > 0;
         });
     }

package/dist/boat/doc-collector/src/ai/tools.js

@@ -58,6 +58,7 @@ async function executeInteraction(explorer, stateManager, candidate, restoreUrl,
     if (!beforeState) {
         return null;
     }
+    const beforeScreenshot = await captureState?.before();
     const executed = await attemptInteraction(explorer, candidate);
     if (!executed) {
         return null;
@@ -75,12 +76,12 @@ async function executeInteraction(explorer, stateManager, candidate, restoreUrl,
         removedElements: ariaChanges.removedCount,
     });
     if (captureState && isMeaningfulStateTransition(transition)) {
-        const screenshot = await captureState(afterState, transition);
+        const screenshot = await captureState.after(beforeScreenshot ?? null, afterState, transition);
         if (screenshot) {
             transition.screenshot = screenshot;
         }
     }
-    if (urlChanged || ariaChanges.newCount > 0) {
+    if (urlChanged || ariaChanges.newCount > 0 || ariaChanges.removedCount > 0) {
         await restoreInteractionState(explorer, restoreUrl);
     }
     return transition;
@@ -108,11 +109,16 @@ async function restoreInteractionState(explorer, restoreUrl, primaryCommand) {
     await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`);
 }
 function buildTransition(candidate, beforeState, afterState, changes) {
+    const existingUrls = new Set(collectLinks(beforeState).map((link) => link.url));
     const transition = {
         action: describeAction(candidate),
         before: summarizeInteractiveState(beforeState),
         after: summarizeInteractiveState(afterState),
-        discoveredUrls: collectLinks(afterState).map((link) => link.url),
+        discoveredUrls: [
+            ...new Set(collectLinks(afterState)
+                .map((link) => link.url)
+                .filter((url) => !existingUrls.has(url))),
+        ],
         newCapabilities: collectDiscoveryNotes(afterState, changes),
         element: buildInteractionElement(candidate),
         changes,
@@ -150,7 +156,7 @@ function isMeaningfulStateTransition(transition) {
     if (transition.targetUrl || transition.changes?.urlChanged) {
         return true;
     }
-    return (transition.changes?.newElements || 0) > 0;
+    return (transition.changes?.newElements || 0) > 0 || (transition.changes?.removedElements || 0) > 0;
 }
 function buildInteractionElement(candidate) {
     const element = {

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

@@ -80,6 +80,7 @@ export function createDocsCommands(name = 'docs') {
             output: 'docs',
             screenshot: true,
             interactive: false,
+            ignoreErrors: true,
             collapseDynamicPages: true,
             scope: 'site',
             includePaths: [],

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

@@ -105,6 +105,7 @@ class DocbotConfigParser {
                 output: 'docs',
                 screenshot: true,
                 interactive: false,
+                ignoreErrors: true,
                 collapseDynamicPages: true,
                 scope: 'site',
                 includePaths: [],

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

@@ -9,7 +9,7 @@ import { DocbotConfigParser } from "./config.js";
 import { renderPageDocumentation, renderSpecIndex } from "./docs-renderer.js";
 import { getDocPageKey, shouldCrawlDocPath } from "./path-filter.js";
 import { extractResearchNavigationTargets } from "./research-navigation.js";
-import { captureDocumentationScreenshots, captureInteractionScreenshot } from "./screenshots.js";
+import { captureBeforeInteraction, captureDocumentationScreenshots, captureInteractionScreenshot } from "./screenshots.js";
 import { renderMermaidBody } from "./state-diagram.js";
 class DocBot {
     explorBot;
@@ -98,16 +98,17 @@ class DocBot {
                     force: true,
                 });
                 const pagePath = this.getPageFilePath(state.url);
-                const documentation = await this.documentarian.document(state, research, async (interactionState, transition) => {
-                    if (!this.shouldUseScreenshots()) {
-                        return null;
+                const captureState = this.shouldUseScreenshots()
+                    ? {
+                        before: () => captureBeforeInteraction(this.explorBot.getExplorer()),
+                        after: (beforeScreenshot, interactionState, transition) => captureInteractionScreenshot(this.explorBot.getExplorer(), beforeScreenshot, interactionState, transition, {
+                            pageFilePath: pagePath,
+                            screenshotsDir: this.getScreenshotsDir(),
+                            config: this.config,
+                        }),
                     }
-                    return captureInteractionScreenshot(this.explorBot.getExplorer(), interactionState, transition, {
-                        pageFilePath: pagePath,
-                        screenshotsDir: this.getScreenshotsDir(),
-                        config: this.config,
-                    });
-                });
+                    : undefined;
+                const documentation = await this.documentarian.document(state, research, captureState);
                 const lowSignalReason = this.getLowSignalReason(documentation, research);
                 if (lowSignalReason) {
                     skipped.push({
@@ -147,6 +148,9 @@ class DocBot {
             }
             catch (error) {
                 const reason = error instanceof Error ? error.message : String(error);
+                if (!this.shouldIgnoreError(error)) {
+                    throw error;
+                }
                 tag('warning').log(`Skipping ${target}: ${reason}`);
                 skipped.push({
                     url: target,
@@ -360,6 +364,28 @@ class DocBot {
         }
         return `low-signal page: only ${documentation.can.length} proven actions and ${interactiveCount} interactive elements`;
     }
+    shouldIgnoreError(error) {
+        const ignoreErrors = this.config.docs?.ignoreErrors;
+        if (ignoreErrors === undefined || ignoreErrors === true)
+            return true;
+        if (ignoreErrors === false)
+            return false;
+        const details = [error instanceof Error ? error.name : '', error instanceof Error ? error.message : String(error)];
+        if (typeof error === 'object' && error && 'code' in error) {
+            details.push(String(error.code));
+        }
+        const normalized = details
+            .join(' ')
+            .toLowerCase()
+            .replaceAll(/[\W_]+/g, ' ');
+        return ignoreErrors.some((pattern) => {
+            const normalizedPattern = pattern
+                .trim()
+                .toLowerCase()
+                .replaceAll(/[\W_]+/g, ' ');
+            return normalizedPattern.length > 0 && normalized.includes(normalizedPattern);
+        });
+    }
     countInteractiveElements(research) {
         const matches = [...research.matchAll(/\((\d+) elements?\)/g)];
         return matches.reduce((sum, match) => sum + Number.parseInt(match[1], 10), 0);

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

@@ -0,0 +1,156 @@
+import { writeFileSync } from 'node:fs';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+const REGION_PADDING = 30;
+const SCREENSHOT_OPTIONS = { animations: 'disabled', caret: 'hide' };
+export async function captureInteractionBefore(page) {
+    await removeVisualAnnotations(page);
+    try {
+        return await page.screenshot(SCREENSHOT_OPTIONS);
+    }
+    catch {
+        return null;
+    }
+}
+export async function captureInteractionAfter(page, beforeScreenshot, filePath, detectUnmarkedOverlay = false) {
+    if (!beforeScreenshot)
+        return 'failed';
+    await removeVisualAnnotations(page);
+    try {
+        const afterScreenshot = await page.screenshot(SCREENSHOT_OPTIONS);
+        const before = PNG.sync.read(beforeScreenshot);
+        const after = PNG.sync.read(afterScreenshot);
+        if (before.width !== after.width || before.height !== after.height)
+            return 'failed';
+        const changedPixels = findChangedPixelBounds(before, after);
+        if (!changedPixels)
+            return 'unchanged';
+        const fullViewportChanged = changedPixels.x === 0 && changedPixels.y === 0 && changedPixels.width === after.width && changedPixels.height === after.height;
+        const changedRegion = addPadding(changedPixels, after.width, after.height);
+        const overlayRegion = fullViewportChanged ? await findOverlayRegion(page, after, detectUnmarkedOverlay) : null;
+        saveRegion(after, overlayRegion || changedRegion, filePath);
+        return 'captured';
+    }
+    catch {
+        return 'failed';
+    }
+}
+export function findChangedRegion(beforeScreenshot, afterScreenshot, padding = REGION_PADDING) {
+    const before = PNG.sync.read(beforeScreenshot);
+    const after = PNG.sync.read(afterScreenshot);
+    if (before.width !== after.width || before.height !== after.height)
+        return null;
+    const changedPixels = findChangedPixelBounds(before, after);
+    return changedPixels ? addPadding(changedPixels, before.width, before.height, padding) : null;
+}
+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));
+}
+function findChangedPixelBounds(before, after) {
+    const diff = Buffer.alloc(before.width * before.height * 4);
+    const changedPixels = pixelmatch(before.data, after.data, diff, before.width, before.height, { diffMask: true });
+    if (changedPixels === 0)
+        return null;
+    let left = before.width;
+    let top = before.height;
+    let right = 0;
+    let bottom = 0;
+    for (let y = 0; y < before.height; y++) {
+        for (let x = 0; x < before.width; x++) {
+            if (diff[(y * before.width + x) * 4 + 3] === 0)
+                continue;
+            left = Math.min(left, x);
+            top = Math.min(top, y);
+            right = Math.max(right, x);
+            bottom = Math.max(bottom, y);
+        }
+    }
+    return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+}
+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 {
+        const dialogs = page.locator('[role="dialog"]:visible, [role="alertdialog"]:visible, [aria-modal="true"]:visible');
+        if ((await dialogs.count()) > 0)
+            box = await dialogs.last().boundingBox();
+    }
+    catch { }
+    if (!box && detectUnmarkedOverlay) {
+        try {
+            box = await findUnmarkedOverlay(page);
+        }
+        catch { }
+    }
+    try {
+        const viewport = page.viewportSize();
+        if (!box || !viewport)
+            return null;
+        const scaleX = image.width / viewport.width;
+        const scaleY = image.height / viewport.height;
+        const x = Math.max(0, Math.floor(box.x * scaleX) - REGION_PADDING);
+        const y = Math.max(0, Math.floor(box.y * scaleY) - REGION_PADDING);
+        const maxX = Math.min(image.width, Math.ceil((box.x + box.width) * scaleX) + REGION_PADDING);
+        const maxY = Math.min(image.height, Math.ceil((box.y + box.height) * scaleY) + REGION_PADDING);
+        if (maxX <= x || maxY <= y)
+            return null;
+        return { x, y, width: maxX - x, height: maxY - y };
+    }
+    catch {
+        return null;
+    }
+}
+async function findUnmarkedOverlay(page) {
+    return page.evaluate(() => {
+        const elements = [...document.body.querySelectorAll('*')].map((element) => {
+            const style = getComputedStyle(element);
+            const box = element.getBoundingClientRect();
+            const zIndex = Number.parseInt(style.zIndex, 10);
+            return { element, style, box, zIndex, area: box.width * box.height };
+        });
+        const isVisibleLayer = ({ style, box, zIndex }) => {
+            if (style.visibility === 'hidden' || style.display === 'none' || Number(style.opacity) === 0)
+                return false;
+            if (box.width <= 0 || box.height <= 0)
+                return false;
+            if (style.position !== 'fixed' && style.position !== 'absolute')
+                return false;
+            return Number.isFinite(zIndex);
+        };
+        const backdropZIndex = elements.filter((item) => isVisibleLayer(item) && item.box.width >= window.innerWidth && item.box.height >= window.innerHeight).reduce((highest, item) => Math.max(highest, item.zIndex), Number.NEGATIVE_INFINITY);
+        if (!Number.isFinite(backdropZIndex))
+            return null;
+        const candidates = elements
+            .filter((item) => {
+            if (!isVisibleLayer(item))
+                return false;
+            if (item.box.width >= window.innerWidth && item.box.height >= window.innerHeight)
+                return false;
+            if (item.zIndex < backdropZIndex)
+                return false;
+            return item.element.matches('button, input, select, textarea, a[href]') || !!item.element.querySelector('button, input, select, textarea, a[href]');
+        })
+            .sort((left, right) => right.zIndex - left.zIndex || left.area - right.area);
+        const box = candidates[0]?.box;
+        if (!box)
+            return null;
+        return { x: box.x, y: box.y, width: box.width, height: box.height };
+    });
+}

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

@@ -1,8 +1,8 @@
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { parseResearchSections } from "../../../src/ai/researcher/parser.js";
-import { detectFocusArea } from "../../../src/utils/aria.js";
 import { safeFilename, sanitizeFilename } from "../../../src/utils/strings.js";
+import { captureInteractionAfter, captureInteractionBefore } from "./interaction-screenshots.js";
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
 export async function captureDocumentationScreenshots(explorer, state, research, options) {
     const page = explorer.page;
@@ -47,7 +47,7 @@ export function getScreenshotSections(research) {
     }
     return sections;
 }
-export async function captureInteractionScreenshot(explorer, state, transition, options) {
+export async function captureInteractionScreenshot(explorer, beforeScreenshot, state, transition, options) {
     const page = explorer.page;
     if (!page) {
         return null;
@@ -55,19 +55,13 @@ export async function captureInteractionScreenshot(explorer, state, transition,
     mkdirSync(options.screenshotsDir, { recursive: true });
     const pageName = sanitizeFilename(state.url || 'page') || 'page';
     const stateName = sanitizeFilename(transition.targetState?.label || transition.action) || 'state';
-    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}`, '.png'));
-    const focus = detectFocusArea(state.ariaSnapshot || null);
-    try {
-        if (focus.detected) {
-            await page.locator('[role="dialog"], [role="alertdialog"], [aria-modal="true"]').last().screenshot({ path: filePath });
-        }
-        else {
-            await page.screenshot({ path: filePath });
-        }
-    }
-    catch {
+    const stateId = state.id ? `_${state.id}` : '';
+    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}${stateId}`, '.png'));
+    const result = await captureInteractionAfter(page, beforeScreenshot, filePath, transition.changes?.urlChanged !== true);
+    if (result === 'unchanged')
+        return null;
+    if (result === 'failed' && !(await captureViewport(page, filePath)))
         return null;
-    }
     return {
         title: transition.targetState?.label || transition.action,
         path: filePath,
@@ -75,6 +69,21 @@ export async function captureInteractionScreenshot(explorer, state, transition,
         kind: 'state',
     };
 }
+export async function captureBeforeInteraction(explorer) {
+    const page = explorer.page;
+    if (!page)
+        return null;
+    return captureInteractionBefore(page);
+}
+async function captureViewport(page, filePath) {
+    try {
+        await page.screenshot({ path: filePath });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function captureFullPageScreenshot(page, pageName, options) {
     const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
     try {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -114,7 +114,9 @@
     "micromatch": "^4.0.8",
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
+    "pixelmatch": "^7.2.0",
     "playwright": "^1.60",
+    "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",
     "strip-ansi": "^7.1.2",
@@ -131,6 +133,7 @@
     "@types/debug": "^4.1.12",
     "@types/jsdom": "^27.0.0",
     "@types/micromatch": "^4.0.9",
+    "@types/pngjs": "^6.0.5",
     "@types/react": "^18.2.0",
     "@types/yargs": "^17.0.24",
     "bunosh": "^0.4.0",

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

@@ -207,7 +207,7 @@ export function WithLocators(Base) {
                 const eidxList = section.elements.map((el) => el.eidx).filter(Boolean);
                 if (eidxList.length < 2)
                     continue;
-                const ancestor = await this.explorer.runWithBrowserRecovery('recoverContainerFromChildren', () => WebElement.commonAncestor(this.explorer.playwrightHelper.page, eidxList));
+                const ancestor = await this.explorer.withPage((page) => WebElement.commonAncestor(page, eidxList));
                 if (!ancestor)
                     continue;
                 const candidates = [];

package/dist/src/explorer.d.ts

@@ -39,6 +39,7 @@ declare class Explorer {
     testPageErrorHandler: ((error: Error) => void) | null;
     testConsoleHandler: ((message: any) => void) | null;
     testDialogHandler: ((dialog: any) => void) | null;
+    eventDispatcher: any;
     constructor(config: ExplorbotConfig, options: ExplorerOptions | undefined, deps: ExplorerDeps);
     get actor(): CodeceptJS.I;
     get page(): Page | null;

package/dist/src/explorer.js

@@ -35,6 +35,7 @@ class Explorer {
     testPageErrorHandler = null;
     testConsoleHandler = null;
     testDialogHandler = null;
+    eventDispatcher = codeceptjs.event.dispatcher;
     constructor(config, options, deps) {
         this.config = config;
         this.options = options;
@@ -169,16 +170,16 @@ class Explorer {
             stepHandler(step, 'failed', error?.message || String(error), error?.stack);
         };
         const onTestAfter = () => {
-            codeceptjs.event.dispatcher.off('step.passed', onStepPassed);
-            codeceptjs.event.dispatcher.off('step.failed', onStepFailed);
-            codeceptjs.event.dispatcher.off('test.after', onTestAfter);
+            this.eventDispatcher.off('step.passed', onStepPassed);
+            this.eventDispatcher.off('step.failed', onStepFailed);
+            this.eventDispatcher.off('test.after', onTestAfter);
             this.unwatchActiveTestPages();
         };
-        codeceptjs.event.dispatcher.emit('test.before', codeceptjsTest);
-        codeceptjs.event.dispatcher.emit('test.start', codeceptjsTest);
-        codeceptjs.event.dispatcher.on('step.passed', onStepPassed);
-        codeceptjs.event.dispatcher.on('step.failed', onStepFailed);
-        codeceptjs.event.dispatcher.on('test.after', onTestAfter);
+        this.eventDispatcher.emit('test.before', codeceptjsTest);
+        this.eventDispatcher.emit('test.start', codeceptjsTest);
+        this.eventDispatcher.on('step.passed', onStepPassed);
+        this.eventDispatcher.on('step.failed', onStepFailed);
+        this.eventDispatcher.on('test.after', onTestAfter);
         return { started: true, stop: (meta) => this.finishTest(test, meta) };
     }
     async openTab() {
@@ -568,18 +569,18 @@ class Explorer {
         const codeceptjsTest = toCodeceptjsTest(test);
         if (test.isSuccessful) {
             codeceptjsTest.state = 'passed';
-            codeceptjs.event.dispatcher.emit('test.passed', codeceptjsTest);
+            this.eventDispatcher.emit('test.passed', codeceptjsTest);
         }
         else if (test.isSkipped) {
             codeceptjsTest.state = 'skipped';
-            codeceptjs.event.dispatcher.emit('test.skipped', codeceptjsTest);
+            this.eventDispatcher.emit('test.skipped', codeceptjsTest);
         }
         else {
             codeceptjsTest.state = 'failed';
-            codeceptjs.event.dispatcher.emit('test.failed', codeceptjsTest);
+            this.eventDispatcher.emit('test.failed', codeceptjsTest);
         }
-        codeceptjs.event.dispatcher.emit('test.finish', codeceptjsTest);
-        codeceptjs.event.dispatcher.emit('test.after', codeceptjsTest);
+        this.eventDispatcher.emit('test.finish', codeceptjsTest);
+        this.eventDispatcher.emit('test.after', codeceptjsTest);
     }
     watchActiveTestPage(page = this.playwrightHelper?.page) {
         if (!this._activeTest)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -114,7 +114,9 @@
     "micromatch": "^4.0.8",
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
+    "pixelmatch": "^7.2.0",
     "playwright": "^1.60",
+    "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",
     "strip-ansi": "^7.1.2",
@@ -131,6 +133,7 @@
     "@types/debug": "^4.1.12",
     "@types/jsdom": "^27.0.0",
     "@types/micromatch": "^4.0.9",
+    "@types/pngjs": "^6.0.5",
     "@types/react": "^18.2.0",
     "@types/yargs": "^17.0.24",
     "bunosh": "^0.4.0",

package/src/ai/researcher/locators.ts

@@ -228,7 +228,7 @@ export function WithLocators<T extends Constructor>(Base: T) {
         const eidxList = section.elements.map((el) => el.eidx).filter(Boolean) as string[];
         if (eidxList.length < 2) continue;
 
-        const ancestor = await this.explorer.runWithBrowserRecovery('recoverContainerFromChildren', () => WebElement.commonAncestor(this.explorer.playwrightHelper.page, eidxList));
+        const ancestor = await this.explorer.withPage((page) => WebElement.commonAncestor(page, eidxList));
         if (!ancestor) continue;
 
         const candidates: string[] = [];

package/src/explorer.ts

@@ -58,6 +58,7 @@ class Explorer {
   private testPageErrorHandler: ((error: Error) => void) | null = null;
   private testConsoleHandler: ((message: any) => void) | null = null;
   private testDialogHandler: ((dialog: any) => void) | null = null;
+  private eventDispatcher = codeceptjs.event.dispatcher;
 
   constructor(config: ExplorbotConfig, options: ExplorerOptions | undefined, deps: ExplorerDeps) {
     this.config = config;
@@ -215,17 +216,17 @@ class Explorer {
       stepHandler(step, 'failed', error?.message || String(error), error?.stack);
     };
     const onTestAfter = () => {
-      codeceptjs.event.dispatcher.off('step.passed', onStepPassed);
-      codeceptjs.event.dispatcher.off('step.failed', onStepFailed);
-      codeceptjs.event.dispatcher.off('test.after', onTestAfter);
+      this.eventDispatcher.off('step.passed', onStepPassed);
+      this.eventDispatcher.off('step.failed', onStepFailed);
+      this.eventDispatcher.off('test.after', onTestAfter);
       this.unwatchActiveTestPages();
     };
 
-    codeceptjs.event.dispatcher.emit('test.before', codeceptjsTest);
-    codeceptjs.event.dispatcher.emit('test.start', codeceptjsTest);
-    codeceptjs.event.dispatcher.on('step.passed', onStepPassed);
-    codeceptjs.event.dispatcher.on('step.failed', onStepFailed);
-    codeceptjs.event.dispatcher.on('test.after', onTestAfter);
+    this.eventDispatcher.emit('test.before', codeceptjsTest);
+    this.eventDispatcher.emit('test.start', codeceptjsTest);
+    this.eventDispatcher.on('step.passed', onStepPassed);
+    this.eventDispatcher.on('step.failed', onStepFailed);
+    this.eventDispatcher.on('test.after', onTestAfter);
 
     return { started: true, stop: (meta) => this.finishTest(test, meta) };
   }
@@ -665,17 +666,17 @@ class Explorer {
 
     if (test.isSuccessful) {
       codeceptjsTest.state = 'passed';
-      codeceptjs.event.dispatcher.emit('test.passed', codeceptjsTest);
+      this.eventDispatcher.emit('test.passed', codeceptjsTest);
     } else if (test.isSkipped) {
       codeceptjsTest.state = 'skipped';
-      codeceptjs.event.dispatcher.emit('test.skipped', codeceptjsTest);
+      this.eventDispatcher.emit('test.skipped', codeceptjsTest);
     } else {
       codeceptjsTest.state = 'failed';
-      codeceptjs.event.dispatcher.emit('test.failed', codeceptjsTest);
+      this.eventDispatcher.emit('test.failed', codeceptjsTest);
     }
 
-    codeceptjs.event.dispatcher.emit('test.finish', codeceptjsTest);
-    codeceptjs.event.dispatcher.emit('test.after', codeceptjsTest);
+    this.eventDispatcher.emit('test.finish', codeceptjsTest);
+    this.eventDispatcher.emit('test.after', codeceptjsTest);
   }
 
   private watchActiveTestPage(page = this.playwrightHelper?.page): void {