explorbot 0.1.32-beta.1 → 0.2.0

package/README.md

@@ -14,7 +14,7 @@ npx explorbot start https://your-app.com
 
 It runs with no babysitting and reports back what it finds. This is vibe-testing.
 
-New here? Read the [Getting Started guide](docs/getting-started.md).
+New here? Read the [Getting Started guide](docs/basics/getting-started.md).
 
 ## Use Cases
 
@@ -54,11 +54,11 @@ Cheap, fast workers do the clicking and reading; smart managers make the calls
 
 | | | |
 |---|---|---|
-| [Researcher](docs/reference/agents.md) | [Planner](docs/reference/agents.md) | [Tester](docs/reference/agents.md) |
-| [Pilot](docs/reference/agents.md) | [Captain](docs/reference/agents.md) | [Navigator](docs/reference/agents.md) |
-| [Analyst](docs/reference/agents.md) | [Historian](docs/reference/agents.md) | [Fisherman](docs/reference/agents.md) |
+| [Researcher](docs/web-testing/agents.md) | [Planner](docs/web-testing/agents.md) | [Tester](docs/web-testing/agents.md) |
+| [Pilot](docs/web-testing/agents.md) | [Captain](docs/web-testing/agents.md) | [Navigator](docs/web-testing/agents.md) |
+| [Analyst](docs/web-testing/agents.md) | [Historian](docs/web-testing/agents.md) | [Fisherman](docs/web-testing/agents.md) |
 
-See [Agents](docs/reference/agents.md) for what each one does.
+See [Agents](docs/web-testing/agents.md) for what each one does.
 
 ## Core Philosophy
 
@@ -74,7 +74,7 @@ See [Agents](docs/reference/agents.md) for what each one does.
 
 When tuned, Explorbot **runs autonomously for hours**, trying new scenarios on its own. The more it runs, the more it learns.
 
-## What you get
+## Tests, reports, videos
 
 Every run leaves behind:
 
@@ -83,7 +83,7 @@ Every run leaves behind:
 - **Videos** — step-by-step screencasts of every run.
 - **Experience** — what Explorbot learned, reused to test smarter next time.
 
-See [Automated Tests](docs/guides/automated-tests.md) for the test output and [Reporting](docs/guides/reporting.md) for reports.
+See [Automated Tests](docs/web-testing/automated-tests.md) for the test output and [Reporting](docs/workflow/reporting.md) for reports.
 
 ## It works with your suite
 
@@ -94,7 +94,7 @@ Explorbot won't replace your regression tests — it covers what they can't. You
 - Node.js 24+ or **Bun**
 - An **AI provider key** — OpenRouter recommended; Groq, Cerebras, OpenAI, Anthropic, and others via the [Vercel AI SDK](https://sdk.vercel.ai/providers)
 - A **modern terminal** — iTerm2, WARP, Kitty, Ghostty, or Windows Terminal with WSL
-- A **compatible web app** — CRUD-heavy apps fit best. See [Prerequisites](docs/reference/prerequisites.md)
+- A **compatible web app** — CRUD-heavy apps fit best. See [Prerequisites](docs/basics/prerequisites.md)
 
 If your CI runs Playwright, it runs Explorbot. No GPUs, no special runners.
 
@@ -123,25 +123,25 @@ npx explorbot start /admin/users
 
 Type `/explore`, and Explorbot runs its loop on its own — research, plan, test, repeat — learning from every run.
 
-That's the gist. The [**Getting Started guide**](docs/getting-started.md) walks through the full setup — choosing models, teaching Explorbot to log in, and picking the right feature to start on.
+That's the gist. The [**Getting Started guide**](docs/basics/getting-started.md) walks through the full setup — choosing models, teaching Explorbot to log in, and picking the right feature to start on.
 
 ## Teaching Explorbot
 
 Explorbot gets better when you tell it about your app:
 
-- **Knowledge** — credentials, form rules, navigation quirks. See [Knowledge](docs/guides/knowledge.md).
+- **Knowledge** — credentials, form rules, navigation quirks. See [Knowledge](docs/workflow/knowledge.md).
 - **Rules** — per-agent, per-page instructions. See [Configuration](docs/reference/configuration.md#rules).
 - **Experience** — learned automatically from what works.
 
-Handling logins, cookie banners, modals, and test data takes a few lines — see [Customization](docs/guides/customization.md).
+Handling logins, cookie banners, modals, and test data takes a few lines — see [Customization](docs/web-testing/customization.md).
 
 ## It also tests REST APIs
 
-Point Explorbot at an OpenAPI spec and it plans and runs API tests too. See [API Testing](docs/guides/api-testing.md).
+Point Explorbot at an OpenAPI spec and it plans and runs API tests too. See [API Testing](docs/api-testing/basics.md).
 
 ## Keep going
 
-When you're ready to go deeper, the [full documentation](docs/README.md) covers everything, starting with the [Getting Started guide](docs/getting-started.md).
+When you're ready to go deeper, the [full documentation](docs/) covers everything, starting with the [Getting Started guide](docs/basics/getting-started.md).
 
 ## FAQ
 
@@ -163,7 +163,7 @@ No. With fast open models (e.g. `openai/gpt-oss-20b` on OpenRouter or Groq), exp
 Not yet.
 
 **Can I build my own agents with it?**
-Yes, use the programmatic API. See [Scripting](docs/contributing/scripting.md).
+Yes, use the programmatic API. See [Scripting](docs/reference/scripting.md).
 
 **Can I do the same in Cursor with Playwright MCP?**
 Good luck running it on CI!

package/bin/explorbot-cli.ts

@@ -509,9 +509,10 @@ program
         path: options.path || process.cwd(),
       });
 
+      const { KnowledgeTracker } = await import('../src/knowledge-tracker.js');
+      const tracker = new KnowledgeTracker();
+
       if (url && description) {
-        const { KnowledgeTracker } = await import('../src/knowledge-tracker.js');
-        const tracker = new KnowledgeTracker();
         const result = tracker.addKnowledge(url, description);
         const action = result.isNewFile ? 'Created' : 'Updated';
         console.log(`Knowledge ${action} in: ${result.filename}`);
@@ -519,7 +520,7 @@ program
       }
 
       const AddKnowledge = (await import('../src/components/AddKnowledge.js')).default;
-      render(React.createElement(AddKnowledge, { initialUrl: url || '' }), {
+      render(React.createElement(AddKnowledge, { initialUrl: url || '', knowledgeTracker: tracker }), {
         exitOnCtrlC: false,
         patchConsole: false,
       });

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

@@ -5,7 +5,7 @@ import type Explorer from '../../../../src/explorer.ts';
 import type { WebPageState } from '../../../../src/state-manager.ts';
 import { tag } from '../../../../src/utils/logger.ts';
 import type { DocbotConfig } from '../config.ts';
-import { collectDocInteractions } from './tools.ts';
+import { type CaptureInteractionState, type DocStateTransition, collectDocInteractions } from './tools.ts';
 
 class Documentarian {
   private provider: AIProvider;
@@ -18,7 +18,7 @@ class Documentarian {
     this.explorer = explorer;
   }
 
-  async document(state: WebPageState, research: string): Promise<PageDocumentation> {
+  async document(state: WebPageState, research: string, captureState?: CaptureInteractionState): Promise<PageDocumentation> {
     const interactiveEnabled = this.config.docs?.interactive === true && this.explorer;
     if (!interactiveEnabled) {
       tag('info').log('Documentarian: Using static mode (interactive disabled or no explorer)');
@@ -26,7 +26,7 @@ class Documentarian {
     }
 
     tag('info').log('Documentarian: Using interactive mode with tools');
-    return this.documentWithInteraction(state, research);
+    return this.documentWithInteraction(state, research, captureState);
   }
 
   private async documentStatic(state: WebPageState, research: string): Promise<PageDocumentation> {
@@ -41,12 +41,13 @@ class Documentarian {
     }
   }
 
-  private async documentWithInteraction(state: WebPageState, research: string): Promise<PageDocumentation> {
+  private async documentWithInteraction(state: WebPageState, research: string, captureState?: CaptureInteractionState): Promise<PageDocumentation> {
+    let meaningfulInteractions: StateTransition[] = [];
     try {
       tag('info').log('Starting interactive exploration...');
 
-      const deterministicInteractions = await collectDocInteractions(this.explorer!, state, research, this.config);
-      const meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
+      const deterministicInteractions = await collectDocInteractions(this.explorer!, state, research, this.config, captureState);
+      meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
       if (meaningfulInteractions.length > 0) {
         tag('success').log(`Collected ${meaningfulInteractions.length} deterministic interactions`);
         return await this.generateDocumentationWithInteractions(state, research, meaningfulInteractions);
@@ -61,7 +62,20 @@ class Documentarian {
       return this.documentStatic(state, research);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      tag('warning').log(`Interactive documentation failed: ${message}. Falling back to static.`);
+      tag('warning').log(`Interactive documentation failed: ${message}.`);
+      if (meaningfulInteractions.length > 0) {
+        tag('info').log(`Preserving ${meaningfulInteractions.length} observed interaction(s) without AI summary.`);
+        return this.normalizeDocumentation(
+          {
+            summary: `Observed ${meaningfulInteractions.length} interaction(s); AI-generated summary was unavailable.`,
+            can: [],
+            might: [],
+            interactions: meaningfulInteractions,
+          },
+          state,
+          research
+        );
+      }
       return this.documentStatic(state, research);
     }
   }
@@ -354,26 +368,7 @@ const pageDocumentationSchema = z.object({
   interactions: z.array(stateTransitionSchema).nullable(),
 });
 
-type StateTransition = {
-  action: string;
-  before: string;
-  after: string;
-  targetUrl?: string | null;
-  discoveredUrls?: string[] | null;
-  newCapabilities?: string[] | null;
-  element?: {
-    role: string;
-    name: string;
-    section: string;
-    container?: string | null;
-    locator?: string | null;
-  } | null;
-  changes?: {
-    urlChanged: boolean;
-    newElements: number;
-    removedElements: number;
-  } | null;
-};
+type StateTransition = DocStateTransition;
 type PageDocumentation = Omit<z.infer<typeof pageDocumentationSchema>, 'interactions'> & {
   interactions?: StateTransition[];
   qualityNotes?: string[];

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

@@ -1,6 +1,7 @@
 import { type ResearchElement, 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 type { DocbotConfig } from '../config.ts';
 
 export interface DocStateTransition {
@@ -12,6 +13,8 @@ export interface DocStateTransition {
   newCapabilities?: string[];
   element?: InteractionElement;
   changes?: InteractionChanges;
+  targetState?: InteractionState;
+  screenshot?: InteractionScreenshot;
 }
 
 interface InteractionCandidate {
@@ -35,6 +38,19 @@ interface InteractionChanges {
   removedElements: number;
 }
 
+export interface InteractionState {
+  kind: 'page' | 'dialog' | 'modal' | 'section';
+  label: string;
+  url: string;
+}
+
+export interface InteractionScreenshot {
+  title: string;
+  relativePath: string;
+}
+
+export type CaptureInteractionState = (state: WebPageState, transition: DocStateTransition) => Promise<InteractionScreenshot | null>;
+
 const DEFAULT_MAX_PRIMARY_CANDIDATES = 3;
 const DEFAULT_MAX_INTERACTIONS = 5;
 const MAX_LINKS = 15;
@@ -42,14 +58,14 @@ 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: Explorer, state: WebPageState, research: string, config: DocbotConfig = {}): Promise<DocStateTransition[]> {
+export async function collectDocInteractions(explorer: Explorer, state: WebPageState, research: string, config: DocbotConfig = {}, captureState?: CaptureInteractionState): Promise<DocStateTransition[]> {
   const sections = parseResearchSections(research);
   const transitions: DocStateTransition[] = [];
   const maxInteractions = getPositiveConfigNumber(config.docs?.maxInteractions, DEFAULT_MAX_INTERACTIONS);
   const tabGroup = findTabGroup(sections);
 
   if (tabGroup) {
-    transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url, maxInteractions)));
+    transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url, maxInteractions, captureState)));
   }
 
   for (const candidate of findActionCandidates(sections, config)) {
@@ -57,7 +73,7 @@ export async function collectDocInteractions(explorer: Explorer, state: WebPageS
       break;
     }
 
-    const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS);
+    const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS, captureState);
     if (!transition) {
       continue;
     }
@@ -76,7 +92,7 @@ export function pickDocActionCandidates(research: string, config: DocbotConfig =
   }));
 }
 
-async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: ResearchElement[]; container?: string; sectionName: string }, restoreUrl: string, maxInteractions: number): Promise<DocStateTransition[]> {
+async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: ResearchElement[]; container?: string; sectionName: string }, restoreUrl: string, maxInteractions: number, captureState?: CaptureInteractionState): Promise<DocStateTransition[]> {
   const transitions: DocStateTransition[] = [];
 
   for (const element of tabGroup.elements) {
@@ -93,7 +109,8 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
         sectionName: tabGroup.sectionName,
       },
       restoreUrl,
-      TAB_WAIT_MS
+      TAB_WAIT_MS,
+      captureState
     );
     if (!transition) {
       continue;
@@ -106,7 +123,7 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
   return transitions;
 }
 
-async function executeInteraction(explorer: Explorer, candidate: InteractionCandidate, restoreUrl: string, waitMs: number): Promise<DocStateTransition | null> {
+async function executeInteraction(explorer: Explorer, candidate: InteractionCandidate, restoreUrl: string, waitMs: number, captureState?: CaptureInteractionState): Promise<DocStateTransition | null> {
   const beforeState = explorer.getStateManager().getCurrentState();
   if (!beforeState) {
     return null;
@@ -132,7 +149,14 @@ async function executeInteraction(explorer: Explorer, candidate: InteractionCand
     removedElements: ariaChanges.removedCount,
   });
 
-  if (urlChanged) {
+  if (captureState && isMeaningfulStateTransition(transition)) {
+    const screenshot = await captureState(afterState, transition);
+    if (screenshot) {
+      transition.screenshot = screenshot;
+    }
+  }
+
+  if (urlChanged || ariaChanges.newCount > 0) {
     await restoreInteractionState(explorer, restoreUrl);
   }
 
@@ -143,7 +167,7 @@ async function attemptInteraction(explorer: Explorer, candidate: InteractionCand
   const action = explorer.createAction();
 
   for (const command of buildClickCommands(candidate.element, candidate.container)) {
-    const success = await action.attempt(command, buildPurpose(candidate), false);
+    const success = await action.attempt(command, buildPurpose(candidate));
     if (success) {
       return true;
     }
@@ -155,7 +179,7 @@ async function attemptInteraction(explorer: Explorer, candidate: InteractionCand
 async function restoreInteractionState(explorer: Explorer, restoreUrl: string, primaryCommand?: string | null): Promise<void> {
   if (primaryCommand) {
     const action = explorer.createAction();
-    const restored = await action.attempt(primaryCommand, `Restore initial state on ${restoreUrl}`, false);
+    const restored = await action.attempt(primaryCommand, `Restore initial state on ${restoreUrl}`);
     if (restored) {
       await wait(TAB_WAIT_MS);
       return;
@@ -163,7 +187,7 @@ async function restoreInteractionState(explorer: Explorer, restoreUrl: string, p
   }
 
   const action = explorer.createAction();
-  await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`, false);
+  await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`);
 }
 
 function buildTransition(candidate: InteractionCandidate, beforeState: WebPageState, afterState: WebPageState, changes: InteractionChanges): DocStateTransition {
@@ -175,6 +199,7 @@ function buildTransition(candidate: InteractionCandidate, beforeState: WebPageSt
     newCapabilities: collectDiscoveryNotes(afterState, changes),
     element: buildInteractionElement(candidate),
     changes,
+    targetState: describeTargetState(beforeState, afterState, candidate),
   };
 
   if (changes.urlChanged) {
@@ -184,6 +209,38 @@ function buildTransition(candidate: InteractionCandidate, beforeState: WebPageSt
   return transition;
 }
 
+function describeTargetState(beforeState: WebPageState, afterState: WebPageState, candidate: InteractionCandidate): InteractionState {
+  const beforeFocus = detectFocusArea(beforeState.ariaSnapshot || null);
+  const afterFocus = detectFocusArea(afterState.ariaSnapshot || null);
+  if (afterFocus.detected && (!beforeFocus.detected || beforeFocus.name !== afterFocus.name)) {
+    return {
+      kind: afterFocus.type || 'dialog',
+      label: afterFocus.name || candidate.element.name.trim(),
+      url: afterState.url,
+    };
+  }
+
+  const beforePath = beforeState.url.split('?')[0].split('#')[0];
+  const afterPath = afterState.url.split('?')[0].split('#')[0];
+  const headings = collectHeadings(afterState);
+  let kind: InteractionState['kind'] = 'page';
+  if (beforePath === afterPath) {
+    kind = 'section';
+  }
+  return {
+    kind,
+    label: headings[0] || afterState.title || candidate.element.name.trim(),
+    url: afterState.url,
+  };
+}
+
+function isMeaningfulStateTransition(transition: DocStateTransition): boolean {
+  if (transition.targetUrl || transition.changes?.urlChanged) {
+    return true;
+  }
+  return (transition.changes?.newElements || 0) > 0;
+}
+
 function buildInteractionElement(candidate: InteractionCandidate): InteractionElement {
   const element: InteractionElement = {
     role: candidate.role,

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

@@ -8,9 +8,10 @@ import { sanitizeFilename } from '../../../src/utils/strings.ts';
 import { Documentarian, type PageDocumentation } from './ai/documentarian.ts';
 import { type DocbotConfig, DocbotConfigParser } from './config.ts';
 import { type DocumentedPage, type SkippedPage, renderPageDocumentation, renderSpecIndex } from './docs-renderer.ts';
+import { renderMermaidBody } from './state-diagram.ts';
 import { getDocPageKey, shouldCrawlDocPath } from './path-filter.ts';
 import { extractResearchNavigationTargets } from './research-navigation.ts';
-import { type DocumentationScreenshot, captureDocumentationScreenshots } from './screenshots.ts';
+import { type DocumentationScreenshot, captureDocumentationScreenshots, captureInteractionScreenshot } from './screenshots.ts';
 
 class DocBot {
   private explorBot: ExplorBot;
@@ -111,7 +112,17 @@ class DocBot {
           screenshot: this.shouldUseScreenshots(),
           force: true,
         });
-        const documentation = await this.documentarian.document(state, research);
+        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 lowSignalReason = this.getLowSignalReason(documentation, research);
         if (lowSignalReason) {
           skipped.push({
@@ -134,6 +145,7 @@ class DocBot {
           mightActions: documentation.might.map((item) => item.action),
           interactionActions: (documentation.interactions || []).map((item) => item.action),
           qualityNotes: documentation.qualityNotes || [],
+          interactions: documentation.interactions || [],
           filePath,
         });
         documented.add(pageKey);
@@ -159,12 +171,13 @@ class DocBot {
       }
     }
 
-    const indexPath = this.saveIndex(effectiveStartPath, pages, skipped, effectiveMaxPages);
+    const { indexPath, diagramPath } = this.saveIndex(effectiveStartPath, pages, skipped, effectiveMaxPages);
 
     return {
       pages,
       skipped,
       indexPath,
+      diagramPath,
       outputDir: this.configParser.getOutputDir(),
     };
   }
@@ -385,6 +398,10 @@ class DocBot {
       return null;
     }
 
+    if ((documentation.interactions || []).length > 0) {
+      return null;
+    }
+
     const interactiveCount = this.countInteractiveElements(research);
     if (interactiveCount >= minInteractiveElements) {
       return null;
@@ -417,10 +434,13 @@ class DocBot {
     });
   }
 
-  private saveIndex(startPath: string, pages: DocumentedPage[], skipped: SkippedPage[], maxPages: number): string {
-    const indexPath = path.join(this.configParser.getOutputDir(), 'spec.md');
-    writeFileSync(indexPath, renderSpecIndex(this.configParser.getOutputDir(), startPath, pages, skipped, maxPages), 'utf8');
-    return indexPath;
+  private saveIndex(startPath: string, pages: DocumentedPage[], skipped: SkippedPage[], maxPages: number): { indexPath: string; diagramPath: string } {
+    const outputDir = this.configParser.getOutputDir();
+    const indexPath = path.join(outputDir, 'index.md');
+    writeFileSync(indexPath, renderSpecIndex(outputDir, startPath, pages, skipped, maxPages), 'utf8');
+    const diagramPath = path.join(outputDir, 'state-diagram.mmd');
+    writeFileSync(diagramPath, renderMermaidBody(outputDir, pages), 'utf8');
+    return { indexPath, diagramPath };
   }
 
   private getPagesDir(): string {
@@ -461,6 +481,7 @@ interface CollectionResult {
   pages: DocumentedPage[];
   skipped: SkippedPage[];
   indexPath: string;
+  diagramPath: string;
   outputDir: string;
 }
 

package/boat/doc-collector/src/docs-renderer.ts

@@ -1,7 +1,9 @@
 import path from 'node:path';
-import type { WebPageState } from '../../../src/state-manager.ts';
+import { type WebPageState } from '../../../src/state-manager.ts';
 import type { PageDocumentation, StateTransition } from './ai/documentarian.ts';
 import type { DocumentationScreenshot } from './screenshots.ts';
+import { buildStateGraph, renderMermaidFromGraph, renderStateMapFromGraph, type DocumentedPage, type SkippedPage } from './state-diagram.ts';
+import { normalizeInlineText } from '../../../src/utils/strings.ts';
 
 function renderPageDocumentation(state: WebPageState, documentation: PageDocumentation, screenshots: DocumentationScreenshot[] = []): string {
   const lines: string[] = [];
@@ -48,6 +50,10 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
         }
         lines.push('');
       }
+      if (transition.screenshot) {
+        lines.push(`![${normalizeInlineText(transition.screenshot.title)}](${transition.screenshot.relativePath})`);
+        lines.push('');
+      }
     }
   }
 
@@ -109,6 +115,18 @@ function renderSpecIndex(outputDir: string, startPath: string, pages: Documented
   lines.push(`Pages skipped: ${skipped.length}`);
   lines.push(`Max pages: ${maxPages}`);
   lines.push('');
+  const graph = buildStateGraph(outputDir, pages);
+  lines.push('## State Transitions');
+  lines.push('');
+  lines.push(`\`\`\`mermaid\n${renderMermaidFromGraph(graph)}\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('');
 
@@ -227,28 +245,5 @@ function ensureSentence(text: string): string {
   return `${trimmed}.`;
 }
 
-function normalizeInlineText(text: string): string {
-  return text.normalize('NFKC').replace(/\s+/g, ' ').trim();
-}
-
-interface DocumentedPage {
-  url: string;
-  title: string;
-  summary: string;
-  canCount: number;
-  mightCount: number;
-  interactionCount: number;
-  canActions: string[];
-  mightActions: string[];
-  interactionActions: string[];
-  qualityNotes: string[];
-  filePath: string;
-}
-
-interface SkippedPage {
-  url: string;
-  reason: string;
-}
-
 export { renderPageDocumentation, renderSpecIndex, ensureSentence, normalizeAction };
 export type { DocumentedPage, SkippedPage, StateTransition };

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

@@ -3,7 +3,9 @@ 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';
 
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
@@ -59,6 +61,36 @@ 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;
+  if (!page) {
+    return null;
+  }
+
+  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;
+  }
+
+  return {
+    title: transition.targetState?.label || transition.action,
+    path: filePath,
+    relativePath: toMarkdownPath(options.pageFilePath, filePath),
+    kind: 'state',
+  };
+}
+
 async function captureFullPageScreenshot(page: any, pageName: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
   const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
   try {
@@ -110,7 +142,7 @@ export interface DocumentationScreenshot {
   title: string;
   path: string;
   relativePath: string;
-  kind: 'page' | 'section';
+  kind: 'page' | 'section' | 'state';
   selector?: string;
 }