explorbot 0.1.27 → 0.1.29

package/src/components/LogPane.tsx

@@ -121,6 +121,7 @@ const LogPane: React.FC<LogPaneProps> = React.memo(({ verboseMode }) => {
       case 'step':
         return { color: 'cyan' as const, dimColor: true };
       case 'multiline':
+      case 'details':
         return { color: 'gray' as const, dimColor: true };
       case 'html':
         return { color: 'gray' as const };
@@ -143,16 +144,16 @@ const LogPane: React.FC<LogPaneProps> = React.memo(({ verboseMode }) => {
     }
     const styles = getLogStyles(log.type);
 
-    if (log.type === 'multiline') {
+    if (log.type === 'multiline' || log.type === 'details') {
       const cleaned = stripAnsi(dedent(log.content));
       const parsed = parseMarkdownToTerminal(cleaned);
       const lines = parsed.split('\n');
       const maxLines = log.maxLines || 16;
-      const truncated = lines.length > maxLines ? `${lines.slice(0, maxLines).join('\n')}\n... (${lines.length - maxLines} more lines)` : parsed;
+      const content = log.type === 'details' ? parsed : lines.length > maxLines ? `${lines.slice(0, maxLines).join('\n')}\n... (${lines.length - maxLines} more lines)` : parsed;
       return (
         <Box key={index} borderStyle="classic" borderLeft={false} borderRight={false} marginY={1} padding={1} borderColor="dim" overflow="hidden">
           <Text color="gray" dimColor>
-            {truncated}
+            {content}
           </Text>
         </Box>
       );

package/src/config.ts

@@ -59,6 +59,7 @@ interface AgentConfig extends HooksConfig {
   systemPrompt?: string;
   rules?: RuleEntry[];
   providerOptions?: Record<string, any>;
+  reasoning?: 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 }
 
 interface ResearcherAgentConfig extends AgentConfig {

package/src/explorbot.ts

@@ -25,12 +25,13 @@ import { ExperienceTracker } from './experience-tracker.ts';
 import Explorer from './explorer.ts';
 import { KnowledgeTracker } from './knowledge-tracker.ts';
 import { WebPageState } from './state-manager.ts';
+import { Stats } from './stats.ts';
 import type { Suite } from './suite.ts';
 import { Plan, type Test } from './test-plan.ts';
-import { parsePlansFromMarkdown } from './utils/test-plan-markdown.ts';
 import { setVerboseMode, tag } from './utils/logger.ts';
 import { relativeToCwd } from './utils/next-steps.ts';
 import { sanitizeFilename } from './utils/strings.ts';
+import { parsePlansFromMarkdown } from './utils/test-plan-markdown.ts';
 
 export interface ExplorBotOptions {
   from?: string;
@@ -494,7 +495,10 @@ export class ExplorBot {
 
       const reporter = this.explorer?.getReporter();
       if (reporter?.isEnabled()) {
-        await reporter.setRunDescription(markdown);
+        let description = markdown;
+        const modelsTable = Stats.modelsTable(this.provider.getConfiguredModels());
+        if (modelsTable) description = `${markdown}\n\n${modelsTable}`;
+        await reporter.setRunDescription(description);
       }
 
       this.lastReportedTestCount = tests.length;

package/src/explorer.ts

@@ -2,13 +2,14 @@ import { existsSync, mkdirSync } from 'node:fs';
 import path, { join } from 'node:path';
 // @ts-ignore
 import * as codeceptjs from 'codeceptjs';
+import dedent from 'dedent';
 import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
+import type { BrowserContextOptions } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import { AIProvider } from './ai/provider.js';
-import type { BrowserContextOptions } from 'playwright';
 import { visuallyAnnotateContainers } from './ai/researcher/coordinates.ts';
 import { RequestStore } from './api/request-store.ts';
 import { XhrCapture } from './api/xhr-capture.ts';
@@ -19,10 +20,11 @@ import { KnowledgeTracker } from './knowledge-tracker.js';
 import { PlaywrightRecorder } from './playwright-recorder.ts';
 import { Reporter } from './reporter.ts';
 import { StateManager } from './state-manager.js';
-import { Test } from './test-plan.ts';
+import { Test, TestResult } from './test-plan.ts';
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './utils/html.ts';
 import { createDebug, log, tag } from './utils/logger.js';
 import { WebElement } from './utils/web-element.ts';
+import { BrowserRecoveryError, isFatalBrowserError } from './utils/browser-errors.ts';
 
 declare global {
   namespace NodeJS {
@@ -39,7 +41,6 @@ declare namespace CodeceptJS {
 }
 
 const debugLog = createDebug('explorbot:explorer');
-const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
 
 interface TabInfo {
@@ -47,6 +48,12 @@ interface TabInfo {
   title: string;
 }
 
+interface BrowserExecutionErrorResult {
+  action: 'continue' | 'stop';
+  message: string;
+  recovered?: boolean;
+}
+
 class Explorer {
   private aiProvider: AIProvider;
   playwrightHelper: any;
@@ -64,6 +71,10 @@ class Explorer {
   private xhrCapture: XhrCapture | null = null;
   private requestStore: RequestStore | null = null;
   private playwrightRecorder: PlaywrightRecorder = new PlaywrightRecorder();
+  private observedTestPages = new Set<any>();
+  private testPageErrorHandler: ((error: Error) => void) | null = null;
+  private testConsoleHandler: ((message: any) => void) | null = null;
+  private testDialogHandler: ((dialog: any) => void) | null = null;
 
   constructor(config: ExplorbotConfig, aiProvider: AIProvider, options?: { show?: boolean; headless?: boolean; incognito?: boolean; session?: string }) {
     this.config = config;
@@ -199,12 +210,14 @@ class Explorer {
     }
   }
 
-  private setupXhrCapture(): void {
+  private setupXhrCapture(reuseRequestStore = false): void {
     const configParser = ConfigParser.getInstance();
     const outputDir = configParser.getOutputDir();
-    this.requestStore = new RequestStore(outputDir);
+    if (!reuseRequestStore || !this.requestStore) {
+      this.requestStore = new RequestStore(outputDir);
+    }
     const baseUrl = this.config.playwright.url;
-    this.xhrCapture = new XhrCapture(this.requestStore, baseUrl);
+    this.xhrCapture = new XhrCapture(this.requestStore!, baseUrl);
     this.xhrCapture.attach(this.playwrightHelper.page);
   }
 
@@ -239,18 +252,7 @@ class Explorer {
     }
     await this.connectOrLaunchBrowser();
     const hasSession = this.options?.session && existsSync(this.options.session);
-    const helperOptions = this.playwrightHelper.options || {};
-    // CodeceptJS skips _createContextPage when sessions/storageState are involved, so we
-    // build contextOptions ourselves. Most keys share a name with Playwright's
-    // BrowserContextOptions and are copied as-is; `emulate` must be flattened, `basicAuth`
-    // renamed to `httpCredentials`, and `storageState` comes from the --session flag.
-    const contextOptions: BrowserContextOptions = {
-      ...helperOptions,
-    };
-    if (helperOptions.emulate) Object.assign(contextOptions, helperOptions.emulate);
-    if (helperOptions.basicAuth) contextOptions.httpCredentials = helperOptions.basicAuth;
-    if (hasSession) contextOptions.storageState = this.options!.session;
-    await this.playwrightHelper._createContextPage(contextOptions);
+    await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
     await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
     this.setupXhrCapture();
     if (hasSession) {
@@ -287,15 +289,75 @@ class Explorer {
     await this.playwrightHelper._startBrowser();
   }
 
+  private createBrowserContextOptions(): BrowserContextOptions {
+    const helperOptions = this.playwrightHelper.options || {};
+    const contextOptions: BrowserContextOptions = {
+      ...helperOptions,
+    };
+
+    if (helperOptions.emulate) Object.assign(contextOptions, helperOptions.emulate);
+    if (helperOptions.basicAuth) contextOptions.httpCredentials = helperOptions.basicAuth;
+    if (this.options?.session && existsSync(this.options.session)) contextOptions.storageState = this.options.session;
+
+    return contextOptions;
+  }
+
   createAction() {
     return new Action(this.actor, this.stateManager, this.playwrightRecorder);
   }
 
+  async runWithBrowserRecovery<T>(label: string, operation: () => Promise<T>): Promise<T> {
+    if (!(await this.ensurePageAvailable())) {
+      throw new Error(`Browser page is unavailable before ${label}`);
+    }
+
+    try {
+      return await operation();
+    } catch (error) {
+      if (!this.isFatalBrowserError(error)) throw error;
+
+      tag('warning').log(`${label}: browser page is unavailable, recovering...`);
+      let recovered = await this.recoverFromBrowserError();
+      if (!recovered) recovered = await this.restartBrowser();
+      if (!recovered) throw new BrowserRecoveryError(label, error, false);
+      if (!(await this.waitForUsablePageDom())) throw new BrowserRecoveryError(label, error, true);
+
+      try {
+        return await operation();
+      } catch (retryError) {
+        if (this.isFatalBrowserError(retryError)) {
+          throw new BrowserRecoveryError(label, retryError, true);
+        }
+        throw retryError;
+      }
+    }
+  }
+
+  async capturePageState(opts: { includeScreenshot?: boolean } = {}): Promise<ActionResult> {
+    return this.runWithBrowserRecovery('capturePageState', () => this.createAction().capturePageState(opts));
+  }
+
+  async capturePageWithScreenshot(): Promise<ActionResult> {
+    return this.capturePageState({ includeScreenshot: true });
+  }
+
+  async executeAction(code: string): Promise<Action> {
+    return this.runWithBrowserRecovery('executeAction', () => this.createAction().execute(code));
+  }
+
+  async attemptAction(code: string, originalMessage?: string, experience = true): Promise<boolean> {
+    return this.runWithBrowserRecovery('attemptAction', () => this.createAction().attempt(code, originalMessage, experience));
+  }
+
   getPlaywrightRecorder(): PlaywrightRecorder {
     return this.playwrightRecorder;
   }
 
   async visit(url: string) {
+    return this.runWithBrowserRecovery('visit', () => this.visitOnce(url));
+  }
+
+  private async visitOnce(url: string) {
     await this.closeOtherTabs();
 
     const serializedUrl = JSON.stringify(url);
@@ -338,12 +400,14 @@ class Explorer {
   }
 
   async annotateElements(): Promise<WebElement[]> {
-    const { elements } = await annotatePageElements(this.playwrightHelper.page);
-    return elements;
+    return this.runWithBrowserRecovery('annotateElements', async () => {
+      const { elements } = await annotatePageElements(this.playwrightHelper.page);
+      return elements;
+    });
   }
 
   async visuallyAnnotateElements(opts?: { containers?: Array<{ css: string; label: string }> }): Promise<number> {
-    return visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []);
+    return this.runWithBrowserRecovery('visuallyAnnotateElements', () => visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []));
   }
 
   async getEidxInContainer(containerCss: string | null): Promise<string[]> {
@@ -386,28 +450,99 @@ class Explorer {
     await this.playwrightHelper.page.reload();
   }
 
+  private resolveBrowserUrl(url?: string): string | null {
+    if (!url) return null;
+    try {
+      return new URL(url).toString();
+    } catch {}
+
+    const baseUrl = this.config.playwright?.url || this.config.web?.url;
+    if (!baseUrl) return null;
+
+    try {
+      return new URL(url, baseUrl).toString();
+    } catch {
+      return null;
+    }
+  }
+
   isFatalBrowserError(error: unknown): boolean {
-    const msg = error instanceof Error ? error.message : String(error);
-    return FATAL_BROWSER_ERRORS.test(msg);
+    return isFatalBrowserError(error);
   }
 
   async recoverFromBrowserError(): Promise<boolean> {
     try {
-      const url = this.stateManager.getCurrentState()?.url;
+      if (!this.playwrightHelper?.page || this.playwrightHelper.page.isClosed?.()) {
+        const context = this.playwrightHelper?.browserContext;
+        if (!context) return await this.restartBrowser();
+        const page = await context.newPage();
+        await page.bringToFront();
+        await this.playwrightHelper._setPage(page);
+        this.bindFrameNavigated(page);
+        if (this.xhrCapture) {
+          this.xhrCapture.attach(this.playwrightHelper.page);
+        }
+      }
+
+      const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
       if (url) {
         tag('warning').log(`Browser error detected, recovering by navigating to ${url}`);
         await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
-        return true;
+        return this.waitForUsablePageDom();
       }
       tag('warning').log('Browser error detected, reloading page');
       await this.playwrightHelper.page.reload({ waitUntil: 'domcontentloaded', timeout: 10000 });
-      return true;
+      return this.waitForUsablePageDom();
     } catch (err) {
       tag('error').log(`Browser recovery failed: ${err instanceof Error ? err.message : err}`);
       return false;
     }
   }
 
+  async restartBrowser(): Promise<boolean> {
+    if (!this.playwrightHelper) return false;
+
+    const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
+
+    try {
+      if (this.xhrCapture && this.playwrightHelper.page) {
+        this.xhrCapture.detach(this.playwrightHelper.page);
+      }
+
+      await this.playwrightRecorder.stop();
+
+      if (this.playwrightHelper.browserContext) {
+        await this.playwrightHelper.browserContext.close().catch((err: unknown) => {
+          debugLog('Failed to close browser context before restart:', err);
+        });
+        this.playwrightHelper.browserContext = null;
+      }
+
+      if (!this.isSharedBrowser) {
+        await this.playwrightHelper._stopBrowser().catch((err: unknown) => {
+          debugLog('Failed to stop browser before restart:', err);
+        });
+      }
+
+      await this.connectOrLaunchBrowser();
+      await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+      await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
+      this.setupXhrCapture(true);
+      this.listenToStateChanged();
+
+      if (url) {
+        await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
+        if (!(await this.waitForUsablePageDom())) return false;
+      }
+
+      tag('success').log('Browser restarted');
+      return true;
+    } catch (err) {
+      tag('error').log(`Browser restart failed: ${err instanceof Error ? err.message : err}`);
+      return false;
+    }
+  }
+
   async switchToMainFrame() {
     if (this.playwrightHelper.frame) {
       debugLog('Switching to main frame');
@@ -415,6 +550,30 @@ class Explorer {
     }
   }
 
+  private async waitForUsablePageDom(): Promise<boolean> {
+    const page = this.playwrightHelper?.page;
+    if (!page) return false;
+
+    await page.waitForLoadState?.('domcontentloaded', { timeout: 5000 }).catch(() => {});
+    if (page.waitForFunction) {
+      const hasUsableDom = await page
+        .waitForFunction(
+          () => {
+            const body = document.body;
+            if (!body) return false;
+            return body.children.length > 0 || body.textContent?.trim().length > 0;
+          },
+          undefined,
+          { timeout: 5000 }
+        )
+        .then(() => true)
+        .catch(() => false);
+      if (!hasUsableDom) return false;
+    }
+    await page.waitForLoadState?.('networkidle', { timeout: 3000 }).catch(() => {});
+    return true;
+  }
+
   async isInsideIframe(): Promise<boolean> {
     if (this.playwrightHelper.frame) return true;
 
@@ -542,11 +701,13 @@ class Explorer {
     return this._activeTest;
   }
 
-  async startTest(test: Test) {
+  async startTest(test: Test): Promise<boolean> {
     this._activeTest = test;
+    test.start();
     await this.reporter.reportTestStart(test);
     await this.closeOtherTabs();
     this.otherTabs = [];
+    if (!(await this.ensurePageAvailable())) return false;
 
     const codeceptjsTest = toCodeceptjsTest(test);
 
@@ -563,13 +724,7 @@ class Explorer {
       test.setActiveNoteScreenshot(lastScreenshot);
     };
 
-    const dialogHandler = (dialog: any) => {
-      const dialogType = dialog.type();
-      const dialogMessage = dialog.message();
-      test.addNote(`Native dialog ${dialogType} appeared: ${dialogMessage}. Accepted automatically`);
-    };
-
-    this.playwrightHelper?.page?.on('dialog', dialogHandler);
+    this.watchActiveTestPage();
 
     codeceptjs.event.dispatcher.emit('test.before', codeceptjsTest);
     codeceptjs.event.dispatcher.emit('test.start', codeceptjsTest);
@@ -580,11 +735,105 @@ class Explorer {
     codeceptjs.event.dispatcher.on('test.after', () => {
       codeceptjs.event.dispatcher.off('step.passed', stepHandler);
       codeceptjs.event.dispatcher.off('step.failed', stepHandler);
-      this.playwrightHelper?.page?.off('dialog', dialogHandler);
+      this.unwatchActiveTestPages();
     });
+
+    return true;
+  }
+
+  async ensurePageAvailable(): Promise<boolean> {
+    const page = this.playwrightHelper?.page;
+    if (page && !page.isClosed?.()) {
+      this.watchActiveTestPage(page);
+      return true;
+    }
+
+    const recovered = await this.recoverFromBrowserError();
+    if (!recovered) return false;
+    this.watchActiveTestPage();
+    return true;
+  }
+
+  async ensureActiveTestPageAvailable(): Promise<boolean> {
+    return this.ensurePageAvailable();
+  }
+
+  async handleExecutionError(error: unknown): Promise<BrowserExecutionErrorResult> {
+    const message = error instanceof Error ? error.message : String(error);
+    tag('error').log(`Browser execution error: ${message}`);
+
+    if (error instanceof Error && error.name === 'AbortError') {
+      return {
+        action: 'stop',
+        message,
+      };
+    }
+
+    if (error instanceof BrowserRecoveryError) {
+      return {
+        action: 'stop',
+        recovered: error.recovered,
+        message: error.message,
+      };
+    }
+
+    if (!this.isFatalBrowserError(error)) {
+      return {
+        action: 'continue',
+        message: `Previous execution error: ${message}. Investigate the current state and choose a different approach.`,
+      };
+    }
+
+    let recovered = await this.recoverFromBrowserError();
+    if (!recovered) recovered = await this.restartBrowser();
+
+    if (!recovered) {
+      return {
+        action: 'stop',
+        recovered: false,
+        message: `Browser could not be recovered after fatal error: ${message}`,
+      };
+    }
+
+    this.watchActiveTestPage();
+    return {
+      action: 'continue',
+      recovered: true,
+      message: dedent`
+        Browser was recovered after a fatal page error.
+        Continue from the restored page.
+        The interrupted browser action is not product evidence.
+        Inspect the restored page and retry the current step when it is still required.
+      `,
+    };
+  }
+
+  watchActiveTestPage(page = this.playwrightHelper?.page): void {
+    if (!this._activeTest) return;
+    if (!page) return;
+    if (this.observedTestPages.has(page)) return;
+
+    this.testPageErrorHandler ||= (err: Error) => {
+      this._activeTest?.addNote(`Console error: ${err.message}`, TestResult.FAILED);
+    };
+    this.testConsoleHandler ||= (msg: any) => {
+      if (msg.type() !== 'error') return;
+      this._activeTest?.addNote(`Console error: ${msg.text()}`, TestResult.FAILED);
+    };
+    this.testDialogHandler ||= (dialog: any) => {
+      const dialogType = dialog.type();
+      const dialogMessage = dialog.message();
+      this._activeTest?.addNote(`Native dialog ${dialogType} appeared: ${dialogMessage}. Accepted automatically`);
+    };
+
+    page.on('pageerror', this.testPageErrorHandler);
+    page.on('console', this.testConsoleHandler);
+    page.on('dialog', this.testDialogHandler);
+    this.observedTestPages.add(page);
   }
 
   async stopTest(test: Test, meta?: Record<string, string>) {
+    this.unwatchActiveTestPages();
     this._activeTest = null;
     const lastScreenshot = this.stateManager.getCurrentState()?.screenshotFile;
     if (lastScreenshot) {
@@ -609,6 +858,15 @@ class Explorer {
     codeceptjs.event.dispatcher.emit('test.after', codeceptjsTest);
   }
 
+  private unwatchActiveTestPages(): void {
+    for (const page of this.observedTestPages) {
+      if (this.testPageErrorHandler) page.off('pageerror', this.testPageErrorHandler);
+      if (this.testConsoleHandler) page.off('console', this.testConsoleHandler);
+      if (this.testDialogHandler) page.off('dialog', this.testDialogHandler);
+    }
+    this.observedTestPages.clear();
+  }
+
   async hasPlaywrightLocator(locatorFn: (page: any) => any, opts: { multiple?: boolean; contents?: boolean; success?: (locator: any) => Promise<void> | void } = {}): Promise<boolean> {
     try {
       const pwLocator = locatorFn(this.playwrightHelper.page);
@@ -671,7 +929,7 @@ class Explorer {
     await oldPage.close();
     await newPage.bringToFront();
 
-    this.playwrightHelper.page = newPage;
+    await this.playwrightHelper._setPage(newPage);
     this.otherTabs = [];
 
     this.bindFrameNavigated(newPage);
@@ -705,8 +963,7 @@ class Explorer {
     }
 
     await firstPage.bringToFront();
-
-    this.playwrightHelper.page = firstPage;
+    await this.playwrightHelper._setPage(firstPage);
 
     debugLog(`Cleaned up tabs, now focused on: ${await firstPage.url()}`);
   }

package/src/state-manager.ts

@@ -24,6 +24,8 @@ export interface WebPageState {
   url: string;
   /** Page title */
   title?: string;
+  /** HTTP status of the main document navigation */
+  httpStatus?: number;
   /** Full URL for reference */
   fullUrl?: string;
   /** Timestamp when state was captured */

package/src/stats.ts

@@ -54,6 +54,24 @@ export class Stats {
     return String(num);
   }
 
+  static modelsTable(roleModels: Record<string, string>): string {
+    const usedModels = Object.entries(Stats.models).filter(([, tokens]) => tokens.total > 0);
+    if (usedModels.length === 0) return '';
+
+    const rolesByModel: Record<string, string[]> = {};
+    for (const [role, model] of Object.entries(roleModels)) {
+      if (!rolesByModel[model]) rolesByModel[model] = [];
+      rolesByModel[model].push(role);
+    }
+
+    const rows = usedModels.map(([model, tokens]) => {
+      const roles = rolesByModel[model]?.join(', ') || '-';
+      return `| ${roles} | ${model} | ${Stats.humanizeTokens(tokens.total)} |`;
+    });
+
+    return ['## Models', '', '| Role | Model | Tokens |', '| --- | --- | --- |', ...rows].join('\n');
+  }
+
   static hasActivity(): boolean {
     if (Stats.tests > 0 || Stats.plans > 0 || Stats.researches > 0) return true;
     const totalTokens = Object.values(Stats.models).reduce((sum, m) => sum + m.total, 0);

package/src/utils/aria.ts

@@ -334,6 +334,54 @@ const detectRenames = (prev: FlatEntry[], curr: FlatEntry[], prevTotals: Map<str
   return { added, removed };
 };
 
+// Interactive controls keep a stable role+name across a state flip; only an ARIA state
+// attribute changes. Report those flips on their own line so the model always sees
+// "now checked / now collapsed", in both directions, regardless of other page churn.
+const STATE_WORDS: Record<string, { on: string; off: string }> = {
+  checked: { on: 'checked', off: 'unchecked' },
+  selected: { on: 'selected', off: 'unselected' },
+  pressed: { on: 'pressed', off: 'unpressed' },
+  expanded: { on: 'expanded', off: 'collapsed' },
+};
+const STATE_ATTRS = Object.keys(STATE_WORDS);
+
+const stateWord = (attr: string, value: unknown): string => {
+  if (attr === 'checked' && value === 'mixed') return 'partially checked';
+  const words = STATE_WORDS[attr];
+  if (value === true || value === 'true') return words.on;
+  return words.off;
+};
+
+// Pair entries by path; when role and name match but a state attr differs, it's a toggle.
+const detectToggles = (prev: FlatEntry[], curr: FlatEntry[]): { toggled: string[]; togglePaths: Set<string> } => {
+  const toggled: string[] = [];
+  const togglePaths = new Set<string>();
+  const currByPath = new Map(curr.map((e) => [e.path, e]));
+
+  for (const before of prev) {
+    const after = currByPath.get(before.path);
+    if (!after) continue;
+    if (before.entry.role !== after.entry.role) continue;
+    if (before.entry.name !== after.entry.name) continue;
+
+    const transitions: string[] = [];
+    for (const attr of STATE_ATTRS) {
+      const was = stateWord(attr, before.entry[attr]);
+      const now = stateWord(attr, after.entry[attr]);
+      if (was === now) continue;
+      transitions.push(`${was} -> ${now}`);
+    }
+    if (transitions.length === 0) continue;
+
+    togglePaths.add(before.path);
+    let label = String(after.entry.role);
+    const name = after.entry.name;
+    if (typeof name === 'string' && name.trim()) label += ` "${name.trim()}"`;
+    toggled.push(`${label}: ${transitions.join(', ')}`);
+  }
+  return { toggled, togglePaths };
+};
+
 const TOP_DIFF_ITEMS = 10;
 
 const formatDiffSection = (label: string, items: string[]): string[] => {
@@ -358,9 +406,15 @@ const formatDiffSection = (label: string, items: string[]): string[] => {
   return lines;
 };
 
-const formatDiff = (added: string[], removed: string[]): string | null => {
-  if (added.length === 0 && removed.length === 0) return null;
-  return ['ariaDiff:', ...formatDiffSection('added', added), ...formatDiffSection('removed', removed)].join('\n');
+const formatDiff = (added: string[], removed: string[], toggled: string[]): string | null => {
+  if (added.length === 0 && removed.length === 0 && toggled.length === 0) return null;
+  const sections = ['ariaDiff:'];
+  if (toggled.length > 0) {
+    sections.push('  toggled:');
+    for (const line of toggled) sections.push(`    - ${line}`);
+  }
+  sections.push(...formatDiffSection('added', added), ...formatDiffSection('removed', removed));
+  return sections.join('\n');
 };
 
 // ─────────────────────────────────────────────────────────────────
@@ -437,13 +491,16 @@ export const diffAriaSnapshots = (previous: string | null, current: string | nul
     tree = dropEmpty(tree);
     return flatten(tree);
   };
-  const prev = flat(previous);
-  const curr = flat(current);
+  const prevAll = flat(previous);
+  const currAll = flat(current);
+  const { toggled, togglePaths } = detectToggles(prevAll, currAll);
+  const prev = prevAll.filter((e) => !togglePaths.has(e.path));
+  const curr = currAll.filter((e) => !togglePaths.has(e.path));
   const prevTotals = countBy(prev.map((e) => e.summary));
   const currTotals = countBy(curr.map((e) => e.summary));
   const byCount = diffByCount(prevTotals, currTotals);
   const renames = detectRenames(prev, curr, prevTotals, currTotals);
-  return formatDiff([...byCount.added, ...renames.added], [...byCount.removed, ...renames.removed]);
+  return formatDiff([...byCount.added, ...renames.added], [...byCount.removed, ...renames.removed], toggled);
 };
 
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {