explorbot 0.2.0 → 0.2.2

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,15 +3,15 @@ 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;
 
 export async function captureDocumentationScreenshots(explorer: Explorer, state: WebPageState, research: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot[]> {
-  const page = explorer.playwrightHelper?.page;
+  const page = explorer.page;
   if (!page) {
     return [];
   }
@@ -61,8 +61,8 @@ export function getScreenshotSections(research: string): ScreenshotSection[] {
   return sections;
 }
 
-export async function captureInteractionScreenshot(explorer: Explorer, state: WebPageState, transition: DocStateTransition, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
-  const page = explorer.playwrightHelper?.page;
+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/bin/explorbot-cli.js

@@ -9,7 +9,7 @@ import { render } from 'ink';
 import React from 'react';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { ConfigParser } from '../src/config.js';
+import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot } from '../src/explorbot.js';
 import { Stats } from '../src/stats.js';
 import { Plan } from '../src/test-plan.js';
@@ -27,7 +27,6 @@ if (!process.env.EXPLORBOT_NO_BANNER) {
     console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 function buildExplorBotOptions(from, options) {
-    const sessionFile = options.session === true ? path.join(path.resolve(options.path || process.cwd()), 'output', 'session.json') : options.session;
     return {
         from,
         verbose: options.verbose || options.debug,
@@ -36,7 +35,7 @@ function buildExplorBotOptions(from, options) {
         show: options.show,
         headless: options.headless,
         incognito: options.incognito,
-        session: sessionFile,
+        session: options.session,
     };
 }
 function addCommonOptions(cmd) {
@@ -623,7 +622,7 @@ program
             path: options.path,
             config: options.config,
             headless: true,
-            session: options.session === true ? 'output/session.json' : options.session,
+            session: options.session,
         };
         const explorBot = new ExplorBot(mainOptions);
         await explorBot.start();
@@ -652,10 +651,10 @@ addCommonOptions(program.command('shell <url> <command>').description('Execute a
         const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
         await explorBot.start();
         await explorBot.agentNavigator().visit(url);
-        const action = explorBot.getExplorer().createAction();
+        const action = explorBot.getExplorer().action();
         await action.execute(command);
         log('Command executed successfully');
-        const state = explorBot.getExplorer().getStateManager().getCurrentState();
+        const state = explorBot.stateManager().getCurrentState();
         if (state)
             log(`URL: ${state.url}`);
         await explorBot.stop();
@@ -793,4 +792,25 @@ import { createApiCommands } from "../boat/api-tester/src/cli.js";
 import { createDocsCommands } from "../boat/doc-collector/src/cli.js";
 program.addCommand(createApiCommands('api'));
 program.addCommand(createDocsCommands('docs'));
+const envHelp = () => {
+    const width = Math.max(...EXPLORBOT_ENV_VARS.map((v) => v.name.length));
+    const rows = EXPLORBOT_ENV_VARS.map((v) => `  ${v.name.padEnd(width)}  ${v.description}`).join('\n');
+    return `
+Environment variables (config-free one-liner mode):
+  Set EXPLORBOT_AI_PROVIDER to run without an explorbot.config.js. A config file always wins.
+
+${rows}
+
+  Providers: ${Object.keys(PROVIDERS).join(', ')}
+  Example:
+    EXPLORBOT_URL=https://app.example.com EXPLORBOT_AI_PROVIDER=openrouter \\
+      ${cli} explore /login --max-tests 3
+`;
+};
+const addEnvHelp = (cmd) => {
+    cmd.addHelpText('after', envHelp);
+    for (const sub of cmd.commands)
+        addEnvHelp(sub);
+};
+addEnvHelp(program);
 program.parse();

package/dist/boat/api-tester/src/config.js

@@ -9,7 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
 import { parseEnv } from 'node:util';
-import { EXPLORBOT_CONFIG_PATHS } from "../../../src/config.js";
+import { EXPLORBOT_CONFIG_PATHS, createModel, materializeKnowledge, resolveModel, resolveOutputRoot } from "../../../src/config.js";
 export class ApibotConfigParser {
     static instance;
     config = null;
@@ -37,9 +37,13 @@ export class ApibotConfigParser {
         ApibotConfigParser.loadEnv('.env');
         const resolvedPath = options?.config || this.findConfigFile();
         if (!resolvedPath) {
-            if (options?.path)
-                process.chdir(originalCwd);
-            throw new Error('No configuration file found. Create apibot.config.js or apibot.config.ts');
+            try {
+                return await this.loadEnvConfig();
+            }
+            finally {
+                if (options?.path && originalCwd !== process.cwd())
+                    process.chdir(originalCwd);
+            }
         }
         try {
             const configModule = await this.loadConfigModule(resolvedPath);
@@ -98,6 +102,41 @@ export class ApibotConfigParser {
             mkdirSync(dirPath, { recursive: true });
         }
     }
+    async loadEnvConfig() {
+        const provider = process.env.EXPLORBOT_AI_PROVIDER;
+        const modelSpec = process.env.EXPLORBOT_AI_MODEL;
+        if (!provider && !modelSpec) {
+            throw new Error('No configuration file found. Create apibot.config.js or set EXPLORBOT_URL and EXPLORBOT_AI_PROVIDER environment variables');
+        }
+        if (modelSpec && !provider && !modelSpec.includes('/')) {
+            throw new Error('EXPLORBOT_AI_MODEL needs a provider — set EXPLORBOT_AI_PROVIDER, or write it as "provider/model-id"');
+        }
+        const baseEndpoint = process.env.EXPLORBOT_URL;
+        if (!baseEndpoint) {
+            throw new Error('No API endpoint to test. Set EXPLORBOT_URL to the API base endpoint');
+        }
+        const outputRoot = resolveOutputRoot();
+        materializeKnowledge(outputRoot);
+        const api = { baseEndpoint };
+        if (process.env.EXPLORBOT_API_SPEC) {
+            api.spec = [process.env.EXPLORBOT_API_SPEC];
+        }
+        let model;
+        if (provider && modelSpec)
+            model = await createModel(provider, modelSpec);
+        if (provider && !modelSpec)
+            model = await resolveModel(provider, 'model');
+        if (!provider)
+            model = await resolveModel(modelSpec, 'model');
+        this.config = {
+            ai: { model },
+            api,
+            dirs: { output: '.', knowledge: 'knowledge' },
+        };
+        this.configPath = path.join(outputRoot, 'apibot.config.js');
+        this.validateConfig(this.config);
+        return this.config;
+    }
     findConfigFile() {
         const apibotPaths = ['apibot.config.js', 'apibot.config.mjs', 'apibot.config.ts'];
         for (const p of apibotPaths) {

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

@@ -6,10 +6,12 @@ class Documentarian {
     provider;
     config;
     explorer;
-    constructor(provider, config = {}, explorer) {
+    stateManager;
+    constructor(provider, config = {}, explorer, stateManager) {
         this.provider = provider;
         this.config = config;
         this.explorer = explorer;
+        this.stateManager = stateManager;
     }
     async document(state, research, captureState) {
         const interactiveEnabled = this.config.docs?.interactive === true && this.explorer;
@@ -35,7 +37,7 @@ class Documentarian {
         let meaningfulInteractions = [];
         try {
             tag('info').log('Starting interactive exploration...');
-            const deterministicInteractions = await collectDocInteractions(this.explorer, state, research, this.config, captureState);
+            const deterministicInteractions = await collectDocInteractions(this.explorer, this.stateManager, state, research, this.config, captureState);
             meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
             if (meaningfulInteractions.length > 0) {
                 tag('success').log(`Collected ${meaningfulInteractions.length} deterministic interactions`);
@@ -75,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

@@ -6,19 +6,19 @@ const MAX_LINKS = 15;
 const DEFAULT_WAIT_MS = 700;
 const TAB_WAIT_MS = 500;
 const DEFAULT_DENIED_ACTION_LABELS = ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'];
-export async function collectDocInteractions(explorer, state, research, config = {}, captureState) {
+export async function collectDocInteractions(explorer, stateManager, state, research, config = {}, captureState) {
     const sections = parseResearchSections(research);
     const transitions = [];
     const maxInteractions = getPositiveConfigNumber(config.docs?.maxInteractions, DEFAULT_MAX_INTERACTIONS);
     const tabGroup = findTabGroup(sections);
     if (tabGroup) {
-        transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url, maxInteractions, captureState)));
+        transitions.push(...(await exploreTabGroup(explorer, stateManager, tabGroup, state.url, maxInteractions, captureState)));
     }
     for (const candidate of findActionCandidates(sections, config)) {
         if (transitions.length >= maxInteractions) {
             break;
         }
-        const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS, captureState);
+        const transition = await executeInteraction(explorer, stateManager, candidate, state.url, DEFAULT_WAIT_MS, captureState);
         if (!transition) {
             continue;
         }
@@ -33,13 +33,13 @@ export function pickDocActionCandidates(research, config = {}) {
         section: candidate.sectionName,
     }));
 }
-async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions, captureState) {
+async function exploreTabGroup(explorer, stateManager, tabGroup, restoreUrl, maxInteractions, captureState) {
     const transitions = [];
     for (const element of tabGroup.elements) {
         if (transitions.length >= maxInteractions) {
             break;
         }
-        const transition = await executeInteraction(explorer, {
+        const transition = await executeInteraction(explorer, stateManager, {
             element,
             container: tabGroup.container,
             role: 'tab',
@@ -53,17 +53,18 @@ async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions,
     await restoreInteractionState(explorer, restoreUrl, buildPrimaryCommand(tabGroup.elements[0], tabGroup.container));
     return transitions;
 }
-async function executeInteraction(explorer, candidate, restoreUrl, waitMs, captureState) {
-    const beforeState = explorer.getStateManager().getCurrentState();
+async function executeInteraction(explorer, stateManager, candidate, restoreUrl, waitMs, captureState) {
+    const beforeState = stateManager.getCurrentState();
     if (!beforeState) {
         return null;
     }
+    const beforeScreenshot = await captureState?.before();
     const executed = await attemptInteraction(explorer, candidate);
     if (!executed) {
         return null;
     }
     await wait(waitMs);
-    const afterState = explorer.getStateManager().getCurrentState();
+    const afterState = stateManager.getCurrentState();
     if (!afterState) {
         return null;
     }
@@ -75,18 +76,18 @@ async function executeInteraction(explorer, candidate, restoreUrl, waitMs, captu
         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;
 }
 async function attemptInteraction(explorer, candidate) {
-    const action = explorer.createAction();
+    const action = explorer.action();
     for (const command of buildClickCommands(candidate.element, candidate.container)) {
         const success = await action.attempt(command, buildPurpose(candidate));
         if (success) {
@@ -97,22 +98,27 @@ async function attemptInteraction(explorer, candidate) {
 }
 async function restoreInteractionState(explorer, restoreUrl, primaryCommand) {
     if (primaryCommand) {
-        const action = explorer.createAction();
+        const action = explorer.action();
         const restored = await action.attempt(primaryCommand, `Restore initial state on ${restoreUrl}`);
         if (restored) {
             await wait(TAB_WAIT_MS);
             return;
         }
     }
-    const action = explorer.createAction();
+    const action = explorer.action();
     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

@@ -4,10 +4,6 @@ import { Command } from 'commander';
 import { setPreserveConsoleLogs } from "../../../src/utils/logger.js";
 import { DocBot } from "./docbot.js";
 function buildOptions(options) {
-    let session = options.session;
-    if (options.session === true) {
-        session = 'output/session.json';
-    }
     return {
         verbose: options.verbose || options.debug,
         config: options.config,
@@ -15,7 +11,7 @@ function buildOptions(options) {
         show: options.show,
         headless: options.headless,
         incognito: options.incognito,
-        session,
+        session: options.session,
         docsConfig: options.docsConfig,
     };
 }
@@ -84,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

@@ -7,10 +7,10 @@ import { sanitizeFilename } from "../../../src/utils/strings.js";
 import { Documentarian } from "./ai/documentarian.js";
 import { DocbotConfigParser } from "./config.js";
 import { renderPageDocumentation, renderSpecIndex } from "./docs-renderer.js";
-import { renderMermaidBody } from "./state-diagram.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;
     configParser;
@@ -39,7 +39,7 @@ class DocBot {
             config: this.options.docsConfig,
             path: this.options.path,
         });
-        this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config, this.explorBot.getExplorer());
+        this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config, this.explorBot.getExplorer(), this.explorBot.stateManager());
         this.ensureDirectory(this.configParser.getOutputDir());
         this.ensureDirectory(this.getPagesDir());
     }
@@ -66,7 +66,7 @@ class DocBot {
             if (documented.has(targetKey)) {
                 continue;
             }
-            const stateManager = this.explorBot.getExplorer().getStateManager();
+            const stateManager = this.explorBot.stateManager();
             if (stateManager.hasVisitedState(target)) {
                 continue;
             }
@@ -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);