explorbot 0.1.32-beta.1 → 0.2.0

package/boat/doc-collector/src/state-diagram.ts

@@ -0,0 +1,281 @@
+import path from 'node:path';
+import { normalizeUrl } from '../../../src/state-manager.ts';
+import { normalizeInlineText } from '../../../src/utils/strings.ts';
+import type { StateTransition } from './ai/documentarian.ts';
+
+function buildStateGraph(outputDir: string, pages: DocumentedPage[]): StateGraph {
+  const pageIds = new Map<string, string>();
+  const pageNodes: StateNode[] = [];
+  const adjacency = new Map<string, Set<string>>();
+  const classAssignment = new Map<StateClass, string[]>([
+    ['page', []],
+    ['dialog', []],
+    ['section', []],
+  ]);
+
+  for (const [index, page] of pages.entries()) {
+    const id = `page${index}`;
+    pageIds.set(normalizeUrl(page.url), id);
+    adjacency.set(id, new Set());
+    classAssignment.get('page')?.push(id);
+    pageNodes.push({ id, kind: 'page', label: page.title || page.url, subLabel: page.url, filePath: page.filePath });
+  }
+
+  const stateKeys = new Map<string, string>();
+  const transientByPage = new Map<string, StateNode[]>();
+  const clicks: StateClick[] = [];
+  const edges: StateEdge[] = [];
+  const drawnBack = new Set<string>();
+  let stateIndex = 0;
+
+  for (const [pageIndex, page] of pages.entries()) {
+    const sourceId = `page${pageIndex}`;
+    for (const transition of page.interactions || []) {
+      const targetState = transition.targetState;
+      if (!targetState) {
+        continue;
+      }
+
+      const normalizedTarget = normalizeUrl(targetState.url);
+      const isPageTarget = targetState.kind === 'page';
+      let pageTargetId: string | undefined;
+      if (isPageTarget) {
+        pageTargetId = pageIds.get(normalizedTarget);
+      }
+      let targetId: string | undefined;
+      if (pageTargetId && pageTargetId !== sourceId) {
+        targetId = pageTargetId;
+      }
+
+      if (!targetId) {
+        const stateKey = `${sourceId}:${targetState.kind}:${normalizeInlineText(targetState.label)}:${normalizedTarget}`;
+        targetId = stateKeys.get(stateKey);
+        if (!targetId) {
+          targetId = `state${stateIndex++}`;
+          stateKeys.set(stateKey, targetId);
+          adjacency.set(targetId, new Set());
+          classAssignment.get(classForKind(targetState.kind))?.push(targetId);
+          const list = transientByPage.get(sourceId) ?? [];
+          list.push({ id: targetId, kind: targetState.kind, label: targetState.label, subLabel: targetState.kind, parentPageId: sourceId });
+          transientByPage.set(sourceId, list);
+          if (transition.screenshot) {
+            const screenshotPath = path.resolve(path.dirname(page.filePath), transition.screenshot.relativePath);
+            clicks.push({ node: targetId, target: path.relative(outputDir, screenshotPath).replaceAll('\\', '/'), tooltip: 'Open state screenshot' });
+          }
+        }
+      }
+
+      if (!targetId) {
+        continue;
+      }
+
+      const pairKey = `${sourceId}>${targetId}`;
+      if (adjacency.get(targetId)?.has(sourceId)) {
+        if (drawnBack.has(pairKey)) {
+          continue;
+        }
+        drawnBack.add(pairKey);
+        edges.push({ source: sourceId, target: targetId, action: transition.action, isBack: true });
+        continue;
+      }
+
+      if (adjacency.get(sourceId)?.has(targetId) || createsCycle(sourceId, targetId, adjacency)) {
+        continue;
+      }
+      adjacency.get(sourceId)?.add(targetId);
+      edges.push({ source: sourceId, target: targetId, action: transition.action, isBack: false });
+    }
+  }
+
+  const pageClicks: StateClick[] = [];
+  for (const pageNode of pageNodes) {
+    const filePath = pageNode.filePath;
+    if (!filePath) {
+      continue;
+    }
+    const relativeFile = path.relative(outputDir, filePath).replaceAll('\\', '/');
+    pageClicks.push({ node: pageNode.id, target: relativeFile, tooltip: `Open ${pageNode.label}` });
+  }
+
+  return { pages: pageNodes, transientByPage, edges, clicks: [...pageClicks, ...clicks], classAssignment };
+}
+
+function renderMermaidBody(outputDir: string, pages: DocumentedPage[]): string {
+  return renderMermaidFromGraph(buildStateGraph(outputDir, pages));
+}
+
+function renderMermaidFromGraph(graph: StateGraph): string {
+  const lines: string[] = ['flowchart TD'];
+  if (graph.pages.length === 0) {
+    lines.push('  empty["No documented states"]');
+    return lines.join('\n');
+  }
+
+  for (const page of graph.pages) {
+    lines.push(`  ${renderNodeLine(page)}`);
+    const children = graph.transientByPage.get(page.id);
+    if (!children || children.length === 0) {
+      continue;
+    }
+    lines.push(`  subgraph sg_${page.id} ["${escapeMermaidLabel(page.label)} — transient states"]`);
+    for (const child of children) {
+      lines.push(`    ${renderNodeLine(child)}`);
+    }
+    lines.push('  end');
+  }
+
+  for (const edge of graph.edges) {
+    let arrow = '-->';
+    if (edge.isBack) {
+      arrow = '-.->';
+    }
+    lines.push(`  ${edge.source} ${arrow}|"${escapeMermaidLabel(edge.action)}"| ${edge.target}`);
+  }
+
+  lines.push('  classDef page fill:#dbeafe,stroke:#2563eb,color:#0f172a;');
+  lines.push('  classDef dialog fill:#ffedd5,stroke:#ea580c,color:#0f172a;');
+  lines.push('  classDef section fill:#f3e8ff,stroke:#9333ea,color:#0f172a;');
+  for (const [className, ids] of graph.classAssignment) {
+    if (ids.length === 0) {
+      continue;
+    }
+    lines.push(`  class ${ids.join(',')} ${className};`);
+  }
+
+  for (const click of graph.clicks) {
+    lines.push(`  click ${click.node} "${click.target}" "${escapeMermaidLabel(click.tooltip)}"`);
+  }
+
+  return lines.join('\n');
+}
+
+function renderStateMapFromGraph(graph: StateGraph): string {
+  if (graph.pages.length === 0) {
+    return '';
+  }
+  const clickByNode = new Map(graph.clicks.map((click) => [click.node, click]));
+  const rows = ['| State | Type | Open |', '| --- | --- | --- |'];
+  for (const pageNode of graph.pages) {
+    const pageClick = clickByNode.get(pageNode.id);
+    let openCell = '—';
+    if (pageClick) {
+      openCell = `[open page](${pageClick.target})`;
+    }
+    rows.push(`| ${escapeTable(pageNode.label)} | page | ${openCell} |`);
+    for (const child of graph.transientByPage.get(pageNode.id) ?? []) {
+      const childClick = clickByNode.get(child.id);
+      let childCell = '—';
+      if (childClick) {
+        childCell = `[view screenshot](${childClick.target})`;
+      }
+      rows.push(`| ${escapeTable(child.label)} | ${child.kind} | ${childCell} |`);
+    }
+  }
+  return rows.join('\n');
+}
+
+function renderNodeLine(node: StateNode): string {
+  const label = `${escapeMermaidLabel(node.label)}<br/>${escapeMermaidLabel(node.subLabel)}`;
+  if (node.kind === 'dialog' || node.kind === 'modal') {
+    return `${node.id}{{"${label}"}}`;
+  }
+  if (node.kind === 'section') {
+    return `${node.id}("${label}")`;
+  }
+  return `${node.id}["${label}"]`;
+}
+
+function createsCycle(sourceId: string, targetId: string, adjacency: Map<string, Set<string>>): boolean {
+  if (sourceId === targetId) {
+    return true;
+  }
+
+  const pending = [targetId];
+  const visited = new Set<string>();
+  while (pending.length > 0) {
+    const nodeId = pending.pop();
+    if (!nodeId || visited.has(nodeId)) {
+      continue;
+    }
+    if (nodeId === sourceId) {
+      return true;
+    }
+    visited.add(nodeId);
+    pending.push(...(adjacency.get(nodeId) || []));
+  }
+  return false;
+}
+
+function escapeMermaidLabel(value: string): string {
+  return normalizeInlineText(value).replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('|', '&#124;');
+}
+
+function escapeTable(value: string): string {
+  return normalizeInlineText(value).replaceAll('|', '\\|');
+}
+
+function classForKind(kind: StateKind): StateClass {
+  if (kind === 'section') {
+    return 'section';
+  }
+  if (kind === 'page') {
+    return 'page';
+  }
+  return 'dialog';
+}
+
+interface DocumentedPage {
+  url: string;
+  title: string;
+  summary: string;
+  canCount: number;
+  mightCount: number;
+  interactionCount: number;
+  canActions: string[];
+  mightActions: string[];
+  interactionActions: string[];
+  qualityNotes: string[];
+  interactions?: StateTransition[];
+  filePath: string;
+}
+
+interface SkippedPage {
+  url: string;
+  reason: string;
+}
+
+type StateKind = 'page' | 'dialog' | 'modal' | 'section';
+type StateClass = 'page' | 'dialog' | 'section';
+
+interface StateNode {
+  id: string;
+  kind: StateKind;
+  label: string;
+  subLabel: string;
+  filePath?: string;
+  parentPageId?: string;
+}
+
+interface StateEdge {
+  source: string;
+  target: string;
+  action: string;
+  isBack: boolean;
+}
+
+interface StateClick {
+  node: string;
+  target: string;
+  tooltip: string;
+}
+
+interface StateGraph {
+  pages: StateNode[];
+  transientByPage: Map<string, StateNode[]>;
+  edges: StateEdge[];
+  clicks: StateClick[];
+  classAssignment: Map<StateClass, string[]>;
+}
+
+export { buildStateGraph, renderMermaidBody, renderMermaidFromGraph, renderStateMapFromGraph };
+export type { DocumentedPage, SkippedPage, StateGraph, StateNode, StateEdge, StateClick };

package/dist/bin/explorbot-cli.js

@@ -454,16 +454,16 @@ program
         await ConfigParser.getInstance().loadConfig({
             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}`);
             return;
         }
         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/dist/boat/doc-collector/src/ai/documentarian.js

@@ -11,14 +11,14 @@ class Documentarian {
         this.config = config;
         this.explorer = explorer;
     }
-    async document(state, research) {
+    async document(state, research, captureState) {
         const interactiveEnabled = this.config.docs?.interactive === true && this.explorer;
         if (!interactiveEnabled) {
             tag('info').log('Documentarian: Using static mode (interactive disabled or no explorer)');
             return this.documentStatic(state, research);
         }
         tag('info').log('Documentarian: Using interactive mode with tools');
-        return this.documentWithInteraction(state, research);
+        return this.documentWithInteraction(state, research, captureState);
     }
     async documentStatic(state, research) {
         try {
@@ -31,11 +31,12 @@ class Documentarian {
             return this.generateDocumentation(state, this.sanitizeResearch(research), true);
         }
     }
-    async documentWithInteraction(state, research) {
+    async documentWithInteraction(state, research, captureState) {
+        let meaningfulInteractions = [];
         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);
@@ -50,7 +51,16 @@ class Documentarian {
         }
         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);
         }
     }

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

@@ -1,23 +1,24 @@
 import { parseResearchSections } from "../../../../src/ai/researcher/parser.js";
+import { detectFocusArea } from "../../../../src/utils/aria.js";
 const DEFAULT_MAX_PRIMARY_CANDIDATES = 3;
 const DEFAULT_MAX_INTERACTIONS = 5;
 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 = {}) {
+export async function collectDocInteractions(explorer, 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)));
+        transitions.push(...(await exploreTabGroup(explorer, 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);
+        const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS, captureState);
         if (!transition) {
             continue;
         }
@@ -32,7 +33,7 @@ export function pickDocActionCandidates(research, config = {}) {
         section: candidate.sectionName,
     }));
 }
-async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions) {
+async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions, captureState) {
     const transitions = [];
     for (const element of tabGroup.elements) {
         if (transitions.length >= maxInteractions) {
@@ -43,7 +44,7 @@ async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions)
             container: tabGroup.container,
             role: 'tab',
             sectionName: tabGroup.sectionName,
-        }, restoreUrl, TAB_WAIT_MS);
+        }, restoreUrl, TAB_WAIT_MS, captureState);
         if (!transition) {
             continue;
         }
@@ -52,7 +53,7 @@ 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) {
+async function executeInteraction(explorer, candidate, restoreUrl, waitMs, captureState) {
     const beforeState = explorer.getStateManager().getCurrentState();
     if (!beforeState) {
         return null;
@@ -73,7 +74,13 @@ async function executeInteraction(explorer, candidate, restoreUrl, waitMs) {
         newElements: ariaChanges.newCount,
         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);
     }
     return transition;
@@ -81,7 +88,7 @@ async function executeInteraction(explorer, candidate, restoreUrl, waitMs) {
 async function attemptInteraction(explorer, candidate) {
     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;
         }
@@ -91,14 +98,14 @@ async function attemptInteraction(explorer, candidate) {
 async function restoreInteractionState(explorer, restoreUrl, primaryCommand) {
     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;
         }
     }
     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, beforeState, afterState, changes) {
     const transition = {
@@ -109,12 +116,42 @@ function buildTransition(candidate, beforeState, afterState, changes) {
         newCapabilities: collectDiscoveryNotes(afterState, changes),
         element: buildInteractionElement(candidate),
         changes,
+        targetState: describeTargetState(beforeState, afterState, candidate),
     };
     if (changes.urlChanged) {
         transition.targetUrl = afterState.url;
     }
     return transition;
 }
+function describeTargetState(beforeState, afterState, candidate) {
+    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 = 'page';
+    if (beforePath === afterPath) {
+        kind = 'section';
+    }
+    return {
+        kind,
+        label: headings[0] || afterState.title || candidate.element.name.trim(),
+        url: afterState.url,
+    };
+}
+function isMeaningfulStateTransition(transition) {
+    if (transition.targetUrl || transition.changes?.urlChanged) {
+        return true;
+    }
+    return (transition.changes?.newElements || 0) > 0;
+}
 function buildInteractionElement(candidate) {
     const element = {
         role: candidate.role,

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

@@ -7,9 +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 } from "./screenshots.js";
+import { captureDocumentationScreenshots, captureInteractionScreenshot } from "./screenshots.js";
 class DocBot {
     explorBot;
     configParser;
@@ -96,7 +97,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({
@@ -118,6 +129,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);
@@ -142,11 +154,12 @@ 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(),
         };
     }
@@ -338,6 +351,9 @@ class DocBot {
         if (documentation.can.length >= minCanActions) {
             return null;
         }
+        if ((documentation.interactions || []).length > 0) {
+            return null;
+        }
         const interactiveCount = this.countInteractiveElements(research);
         if (interactiveCount >= minInteractiveElements) {
             return null;
@@ -365,9 +381,12 @@ class DocBot {
         });
     }
     saveIndex(startPath, pages, skipped, maxPages) {
-        const indexPath = path.join(this.configParser.getOutputDir(), 'spec.md');
-        writeFileSync(indexPath, renderSpecIndex(this.configParser.getOutputDir(), startPath, pages, skipped, maxPages), 'utf8');
-        return indexPath;
+        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 };
     }
     getPagesDir() {
         return path.join(this.configParser.getOutputDir(), 'pages');

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

@@ -1,4 +1,6 @@
 import path from 'node:path';
+import { buildStateGraph, renderMermaidFromGraph, renderStateMapFromGraph } from "./state-diagram.js";
+import { normalizeInlineText } from "../../../src/utils/strings.js";
 function renderPageDocumentation(state, documentation, screenshots = []) {
     const lines = [];
     lines.push(`# ${state.url}`);
@@ -40,6 +42,10 @@ function renderPageDocumentation(state, documentation, screenshots = []) {
                 }
                 lines.push('');
             }
+            if (transition.screenshot) {
+                lines.push(`![${normalizeInlineText(transition.screenshot.title)}](${transition.screenshot.relativePath})`);
+                lines.push('');
+            }
         }
     }
     lines.push('## User Can');
@@ -90,6 +96,18 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
     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('');
     if (pages.length === 0) {
@@ -192,7 +210,4 @@ function ensureSentence(text) {
     }
     return `${trimmed}.`;
 }
-function normalizeInlineText(text) {
-    return text.normalize('NFKC').replace(/\s+/g, ' ').trim();
-}
 export { renderPageDocumentation, renderSpecIndex, ensureSentence, normalizeAction };

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

@@ -1,6 +1,7 @@
 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";
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
 export async function captureDocumentationScreenshots(explorer, state, research, options) {
@@ -46,6 +47,34 @@ export function getScreenshotSections(research) {
     }
     return sections;
 }
+export async function captureInteractionScreenshot(explorer, state, transition, options) {
+    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, pageName, options) {
     const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
     try {