explorbot 0.1.32-beta.1 → 0.2.0

package/src/explorer.ts

@@ -14,17 +14,17 @@ import { visuallyAnnotateContainers } from './ai/researcher/coordinates.ts';
 import { RequestStore } from './api/request-store.ts';
 import { XhrCapture } from './api/xhr-capture.ts';
 import type { ExplorbotConfig } from './config.js';
-import { ConfigParser, outputPath } from './config.js';
-import type { UserResolveFunction } from './explorbot.js';
+import { ConfigParser } from './config.js';
+import type { ExperienceTracker } from './experience-tracker.js';
 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, TestResult } from './test-plan.ts';
-import { BrowserRecoveryError, isFatalBrowserError, isNavigationTransitionError } from './utils/browser-errors.ts';
+import { BrowserRecoveryError, browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from './utils/browser-errors.ts';
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './utils/html.ts';
 import { createDebug, log, tag } from './utils/logger.js';
-import { waitForPageReadiness } from './utils/page-readiness.ts';
+import { sleep, waitForPageReadiness } from './utils/page-readiness.ts';
 import { WebElement } from './utils/web-element.ts';
 
 declare global {
@@ -64,7 +64,6 @@ class Explorer {
   private stateManager!: StateManager;
   private knowledgeTracker!: KnowledgeTracker;
   config: ExplorbotConfig;
-  private userResolveFn: UserResolveFunction | null = null;
   private options?: { show?: boolean; headless?: boolean; incognito?: boolean; session?: string };
   private reporter!: Reporter;
   private otherTabs: TabInfo[] = [];
@@ -77,13 +76,13 @@ class Explorer {
   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 }) {
+  constructor(config: ExplorbotConfig, aiProvider: AIProvider, options: { show?: boolean; headless?: boolean; incognito?: boolean; session?: string } | undefined, experienceTracker: ExperienceTracker, knowledgeTracker: KnowledgeTracker) {
     this.config = config;
     this.aiProvider = aiProvider;
     this.options = options;
     this.initializeContainer();
-    this.stateManager = new StateManager({ incognito: this.options?.incognito });
-    this.knowledgeTracker = new KnowledgeTracker();
+    this.knowledgeTracker = knowledgeTracker;
+    this.stateManager = new StateManager(experienceTracker, knowledgeTracker);
     this.reporter = new Reporter(config.reporter, this.stateManager);
   }
 
@@ -91,8 +90,7 @@ class Explorer {
     try {
       // Use project root for output directory, not current working directory
       const configParser = ConfigParser.getInstance();
-      const configPath = configParser.getConfigPath();
-      const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
+      const projectRoot = configParser.getProjectRoot();
       (global as any).output_dir = path.join(projectRoot, 'output', 'states');
       (global as any).codecept_dir = projectRoot;
 
@@ -155,8 +153,7 @@ class Explorer {
     };
 
     if (this.config.stepsFile) {
-      const configPath = ConfigParser.getInstance().getConfigPath();
-      const projectRoot = configPath ? path.dirname(configPath) : process.cwd();
+      const projectRoot = ConfigParser.getInstance().getProjectRoot();
       codeceptConfig.include = { I: path.resolve(projectRoot, this.config.stepsFile) };
     }
 
@@ -164,17 +161,9 @@ class Explorer {
   }
 
   public getConfig(): ExplorbotConfig {
-    if (!this.config) {
-      throw new Error('Configuration not loaded. Call run() first.');
-    }
     return this.config;
   }
 
-  public getConfigPath(): string | null {
-    const configParser = ConfigParser.getInstance();
-    return configParser.getConfigPath();
-  }
-
   public getAIProvider(): AIProvider {
     return this.aiProvider;
   }
@@ -183,10 +172,6 @@ class Explorer {
     return this.stateManager;
   }
 
-  public getCurrentUrl(): string {
-    return this.stateManager.getCurrentState()!.url || '?';
-  }
-
   public getKnowledgeTracker(): KnowledgeTracker {
     return this.knowledgeTracker;
   }
@@ -227,10 +212,6 @@ class Explorer {
       return;
     }
 
-    if (!this.config) {
-      await this.initializeContainer();
-    }
-
     await codeceptjs.recorder.start();
     await codeceptjs.container.started(null);
     storeListener();
@@ -359,8 +340,8 @@ class Explorer {
     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));
+  async attemptAction(code: string, originalMessage?: string): Promise<boolean> {
+    return this.runWithBrowserRecovery('attemptAction', () => this.createAction().attempt(code, originalMessage));
   }
 
   getPlaywrightRecorder(): PlaywrightRecorder {
@@ -388,7 +369,7 @@ class Explorer {
       try {
         await action.execute(`I.amOnPage(${serializedUrl})`);
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = browserErrorMessage(err);
         if (!RECOVERABLE_NAVIGATION_ERRORS.test(msg)) throw err;
         tag('warning').log(`Navigation warning (continuing after load): ${msg.split('\n')[0]}`);
         await this.waitForPageReadiness();
@@ -437,7 +418,7 @@ class Explorer {
       return result;
     } catch (error) {
       if (this.isFatalBrowserError(error)) {
-        tag('warning').log(`getEidxInContainer: ${error instanceof Error ? error.message : error}`);
+        tag('warning').log(`getEidxInContainer: ${browserErrorMessage(error)}`);
         await this.recoverFromBrowserError();
       }
       return [];
@@ -452,18 +433,13 @@ class Explorer {
       return await el.first().getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx);
     } catch (error) {
       if (this.isFatalBrowserError(error)) {
-        tag('warning').log(`getEidxByLocator: ${error instanceof Error ? error.message : error}`);
+        tag('warning').log(`getEidxByLocator: ${browserErrorMessage(error)}`);
         await this.recoverFromBrowserError();
       }
       return null;
     }
   }
 
-  async reload() {
-    await this.closeOtherTabs();
-    await this.playwrightHelper.page.reload();
-  }
-
   private resolveBrowserUrl(url?: string): string | null {
     if (!url) return null;
     try {
@@ -508,7 +484,7 @@ class Explorer {
       await this.playwrightHelper.page.reload({ waitUntil: 'domcontentloaded', timeout: 10000 });
       return this.waitForPageReadiness();
     } catch (err) {
-      tag('error').log(`Browser recovery failed: ${err instanceof Error ? err.message : err}`);
+      tag('error').log(`Browser recovery failed: ${browserErrorMessage(err)}`);
       return false;
     }
   }
@@ -552,7 +528,7 @@ class Explorer {
       tag('success').log('Browser restarted');
       return true;
     } catch (err) {
-      tag('error').log(`Browser restart failed: ${err instanceof Error ? err.message : err}`);
+      tag('error').log(`Browser restart failed: ${browserErrorMessage(err)}`);
       return false;
     }
   }
@@ -584,7 +560,7 @@ class Explorer {
       return await page.evaluate(() => window.top !== window.self);
     } catch (error) {
       if (this.isFatalBrowserError(error)) {
-        tag('warning').log(`isInsideIframe: ${error instanceof Error ? error.message : error}`);
+        tag('warning').log(`isInsideIframe: ${browserErrorMessage(error)}`);
         await this.recoverFromBrowserError();
       }
       return false;
@@ -608,10 +584,6 @@ class Explorer {
     this.otherTabs = [];
   }
 
-  setUserResolve(userResolveFn: UserResolveFunction): void {
-    this.userResolveFn = userResolveFn;
-  }
-
   private listenToStateChanged(): void {
     if (!this.playwrightHelper) {
       debugLog('Playwright helper not available for state monitoring');
@@ -760,12 +732,8 @@ class Explorer {
     return true;
   }
 
-  async ensureActiveTestPageAvailable(): Promise<boolean> {
-    return this.ensurePageAvailable();
-  }
-
   async handleExecutionError(error: unknown): Promise<BrowserExecutionErrorResult> {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = browserErrorMessage(error);
     tag('error').log(`Browser execution error: ${message}`);
 
     if (error instanceof Error && error.name === 'AbortError') {
@@ -873,33 +841,13 @@ class Explorer {
     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);
-      const count = await pwLocator.count();
-      if (opts.multiple ? count === 0 : count !== 1) return false;
-      if (opts.contents) {
-        const html = await pwLocator.first().innerHTML();
-        if (!html?.trim()) return false;
-      }
-      if (opts.success) await opts.success(pwLocator);
-      return true;
-    } catch (error) {
-      if (this.isFatalBrowserError(error)) {
-        tag('warning').log(`hasPlaywrightLocator: ${error instanceof Error ? error.message : error}`);
-        await this.recoverFromBrowserError();
-      }
-      return false;
-    }
-  }
-
   async playwrightLocatorCount(locatorFn: (page: any) => any): Promise<number> {
     try {
       const pwLocator = locatorFn(this.playwrightHelper.page);
       return await pwLocator.count();
     } catch (error) {
       if (this.isFatalBrowserError(error)) {
-        tag('warning').log(`playwrightLocatorCount: ${error instanceof Error ? error.message : error}`);
+        tag('warning').log(`playwrightLocatorCount: ${browserErrorMessage(error)}`);
         await this.recoverFromBrowserError();
       }
       throw error;
@@ -921,7 +869,7 @@ class Explorer {
 
       this.stateManager.updateStateFromBasic(newUrl, newTitle, 'navigation');
 
-      await new Promise((resolve) => setTimeout(resolve, 500));
+      await sleep(500);
     });
   }
 

package/src/knowledge-tracker.ts

@@ -1,15 +1,19 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import dedent from 'dedent';
 import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
 import { ConfigParser } from './config.js';
 import { getCliName } from './utils/cli-name.ts';
-import { createDebug } from './utils/logger.js';
+import { createDebug, pluralize, tag } from './utils/logger.js';
+import { loadMarkdownFiles } from './utils/markdown-files.js';
+import { mdq } from './utils/markdown-query.js';
 import { isSecretName, registerSecret } from './utils/secrets.js';
+import { slugify } from './utils/strings.js';
 
 const debugLog = createDebug('explorbot:knowledge-tracker');
 
-interface Knowledge {
+export interface Knowledge {
   filePath: string;
   url: string;
   content: string;
@@ -24,14 +28,7 @@ export class KnowledgeTracker {
   constructor() {
     const configParser = ConfigParser.getInstance();
     const config = configParser.getConfig();
-    const configPath = configParser.getConfigPath();
-
-    if (configPath) {
-      const projectRoot = dirname(configPath);
-      this.knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
-    } else {
-      this.knowledgeDir = config.dirs?.knowledge || 'knowledge';
-    }
+    this.knowledgeDir = configParser.resolveProjectDir(config.dirs?.knowledge || 'knowledge');
 
     if (!existsSync(this.knowledgeDir)) {
       mkdirSync(this.knowledgeDir, { recursive: true });
@@ -43,29 +40,13 @@ export class KnowledgeTracker {
 
     this.knowledgeFiles = [];
 
-    if (!existsSync(this.knowledgeDir)) {
-      return;
-    }
-
-    const files = readdirSync(this.knowledgeDir)
-      .filter((file) => file.endsWith('.md'))
-      .map((file) => join(this.knowledgeDir, file));
-
-    for (const filePath of files) {
-      try {
-        const fileContent = readFileSync(filePath, 'utf8');
-        const parsed = matter(fileContent);
-        const urlPattern = parsed.data.url || parsed.data.path || '*';
-
-        this.knowledgeFiles.push({
-          filePath,
-          url: urlPattern,
-          content: this.interpolateVars(parsed.content),
-          ...parsed.data,
-        });
-      } catch (error) {
-        // Skip invalid files
-      }
+    for (const entry of loadMarkdownFiles(this.knowledgeDir, { recursive: true })) {
+      this.knowledgeFiles.push({
+        filePath: entry.filePath,
+        url: entry.data.url || entry.data.path || '*',
+        content: this.interpolateVars(entry.content),
+        ...entry.data,
+      });
     }
 
     this.isLoaded = true;
@@ -79,25 +60,40 @@ export class KnowledgeTracker {
     });
   }
 
+  renderRelevantKnowledge(state: ActionResult): string {
+    const knowledgeFiles = this.getRelevantKnowledge(state);
+    if (knowledgeFiles.length === 0) return '';
+
+    const knowledgeContent = knowledgeFiles
+      .map((k) => k.content)
+      .filter((k) => !!k)
+      .join('\n\n');
+
+    tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
+    return dedent`
+      <knowledge>
+      Here is relevant knowledge for this page:
+
+      ${knowledgeContent}
+      </knowledge>
+    `;
+  }
+
   addKnowledge(urlPattern: string, description: string): { filename: string; filePath: string; isNewFile: boolean } {
     const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
     const configPath = configParser.getConfigPath();
 
     if (!configPath) {
       throw new Error(`No explorbot configuration found. Please run "${getCliName()} init" first.`);
     }
 
-    const projectRoot = dirname(configPath);
-    const knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
-
-    if (!existsSync(knowledgeDir)) {
-      mkdirSync(knowledgeDir, { recursive: true });
+    if (!existsSync(this.knowledgeDir)) {
+      mkdirSync(this.knowledgeDir, { recursive: true });
     }
 
     const normalizedUrl = this.normalizeUrl(urlPattern);
     const filename = this.generateFilename(normalizedUrl);
-    const filePath = join(knowledgeDir, filename);
+    const filePath = join(this.knowledgeDir, filename);
 
     const isNewFile = !existsSync(filePath);
 
@@ -128,6 +124,8 @@ export class KnowledgeTracker {
       writeFileSync(filePath, fileContent, 'utf8');
     }
 
+    this.isLoaded = false;
+
     return { filename, filePath, isNewFile };
   }
 
@@ -158,12 +156,7 @@ export class KnowledgeTracker {
   }
 
   private generateFilename(url: string): string {
-    let filename = url
-      .replace(/https?:\/\//g, '')
-      .replace(/[^a-zA-Z0-9_]/g, '_')
-      .replace(/_+/g, '_')
-      .replace(/^_|_$/g, '')
-      .toLowerCase();
+    let filename = slugify(url.replace(/https?:\/\//g, ''));
 
     if (!filename || filename === '*') {
       filename = 'general';
@@ -194,7 +187,7 @@ export class KnowledgeTracker {
 
     return this.knowledgeFiles.map((knowledge) => {
       const content = knowledge.content.trim();
-      const firstLine = content.split('\n')[0]?.trim() || '';
+      const firstLine = mdq(content).meta()[0]?.text.split('\n')[0]?.trim() || '';
       return {
         url: knowledge.url,
         firstLine,

package/src/state-manager.ts

@@ -1,11 +1,9 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import matter from 'gray-matter';
 import { ActionResult } from './action-result.js';
-import { ConfigParser, outputPath } from './config.js';
-import { ExperienceTracker } from './experience-tracker.js';
+import type { ExperienceTracker } from './experience-tracker.js';
+import type { KnowledgeTracker, Knowledge } from './knowledge-tracker.js';
 import { detectFocusArea } from './utils/aria.js';
-import { createDebug, tag } from './utils/logger.js';
+import { createDebug } from './utils/logger.js';
+import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 
 const debugLog = createDebug('explorbot:state');
@@ -69,43 +67,30 @@ export interface StateTransition {
 
 export type StateChangeListener = (event: StateTransition) => void;
 
-export interface Knowledge extends WebPageState {
-  /** File path */
-  filePath: string;
-  /** Markdown content */
-  content: string;
-}
+export type { Knowledge };
 
 export class StateManager {
   private currentState: WebPageState | null = null;
   private stateHistory: StateTransition[] = [];
   private allVisitedUrls: Set<string> = new Set();
-  private knowledgeCache: Knowledge[] = [];
-  private lastKnowledgeScan: Date | null = null;
   private stateChangeListeners: StateChangeListener[] = [];
   private experienceTracker!: ExperienceTracker;
-  private knowledgeDir: string;
+  private knowledgeTracker: KnowledgeTracker;
   private nextStateId = 1;
 
-  constructor() {
-    this.experienceTracker = new ExperienceTracker();
-    const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
-    const configPath = configParser.getConfigPath();
-
-    // Resolve knowledge directory relative to the config file location (project root)
-    if (configPath) {
-      const projectRoot = dirname(configPath);
-      this.knowledgeDir = join(projectRoot, config.dirs?.knowledge || 'knowledge');
-    } else {
-      this.knowledgeDir = config.dirs?.knowledge || 'knowledge';
-    }
+  constructor(experienceTracker: ExperienceTracker, knowledgeTracker: KnowledgeTracker) {
+    this.experienceTracker = experienceTracker;
+    this.knowledgeTracker = knowledgeTracker;
   }
 
   getExperienceTracker(): ExperienceTracker {
     return this.experienceTracker;
   }
 
+  getKnowledgeTracker(): KnowledgeTracker {
+    return this.knowledgeTracker;
+  }
+
   /**
    * Subscribe to state change events
    */
@@ -134,11 +119,6 @@ export class StateManager {
     });
   }
 
-  /**
-   * Extract state path from full URL
-   * Removes domain, port, protocol
-   * Keeps path, query, and hash: /path/to/page?tab=users#section
-   */
   /**
    * Update current state from ActionResult and record transition if state changed
    */
@@ -230,13 +210,7 @@ export class StateManager {
       parts.push(`title_${title}`);
     }
 
-    return parts
-      .join('_')
-      .replace(/[^a-zA-Z0-9_]/g, '_')
-      .replace(/_+/g, '_')
-      .replace(/^_|_$/g, '')
-      .toLowerCase()
-      .substring(0, 200);
+    return slugify(parts.join('_')).substring(0, 200);
   }
 
   /**
@@ -327,65 +301,14 @@ export class StateManager {
     return this.stateHistory.slice(-count);
   }
 
-  /**
-   * Scan knowledge directory for .md files and cache them
-   */
-  private scanKnowledgeFiles(): void {
-    const now = new Date();
-
-    // Only rescan every 30 seconds to avoid excessive file I/O
-    if (this.lastKnowledgeScan && now.getTime() - this.lastKnowledgeScan.getTime() < 30000) {
-      return;
-    }
-
-    this.knowledgeCache = [];
-
-    if (!existsSync(this.knowledgeDir)) {
-      debugLog(`Knowledge directory not found: ${this.knowledgeDir}`);
-      return;
-    }
-
-    try {
-      const files = readdirSync(this.knowledgeDir, { recursive: true })
-        .filter((file) => typeof file === 'string' && file.endsWith('.md'))
-        .map((file) => join(this.knowledgeDir, file as string));
-
-      for (const filePath of files) {
-        try {
-          const fileContent = readFileSync(filePath, 'utf8');
-          const parsed = matter(fileContent);
-
-          const urlPattern = parsed.data.url || parsed.data.path || '*';
-
-          this.knowledgeCache.push({
-            filePath,
-            url: urlPattern,
-            ...parsed.data,
-            content: parsed.content,
-          });
-
-          debugLog(`Loaded knowledge file: ${filePath} (pattern: ${urlPattern})`);
-        } catch (error) {
-          debugLog(`Failed to load knowledge file ${filePath}:`, error);
-        }
-      }
-
-      this.lastKnowledgeScan = now;
-      debugLog(`Scanned ${this.knowledgeCache.length} knowledge files`);
-    } catch (error) {
-      debugLog('Failed to scan knowledge directory:', error);
-    }
-  }
   /**
    * Get relevant knowledge files for current state
    */
   getRelevantKnowledge(): Knowledge[] {
     if (!this.currentState) return [];
 
-    this.scanKnowledgeFiles();
-
     const actionResult = ActionResult.fromState(this.currentState);
-    return this.knowledgeCache.filter((knowledge) => actionResult.isMatchedBy(knowledge));
+    return this.knowledgeTracker.getRelevantKnowledge(actionResult);
   }
 
   /**
@@ -402,24 +325,6 @@ export class StateManager {
   /**
    * Get all context for current state (knowledge + experience)
    */
-  getCurrentContext(): {
-    state: WebPageState;
-    knowledge: Knowledge[];
-    experience: string[];
-    recentTransitions: StateTransition[];
-  } {
-    if (!this.currentState) {
-      throw new Error('No current state available');
-    }
-
-    return {
-      state: this.currentState,
-      knowledge: this.getRelevantKnowledge(),
-      experience: this.getRelevantExperience(),
-      recentTransitions: this.getRecentTransitions(),
-    };
-  }
-
   /**
    * Check if we've been in this state before
    */
@@ -455,45 +360,6 @@ export class StateManager {
    * If the last transition changed URL, returns the fromState (for URL change detection).
    * Otherwise returns the most recent toState with content (for diffing).
    */
-  getPreviousState(): WebPageState | null {
-    if (this.stateHistory.length === 0) return null;
-
-    const lastTransition = this.stateHistory[this.stateHistory.length - 1];
-
-    if (lastTransition.fromState?.url !== lastTransition.toState?.url) {
-      return lastTransition.fromState;
-    }
-
-    for (let i = this.stateHistory.length - 1; i >= 0; i--) {
-      const toState = this.stateHistory[i].toState;
-
-      if (!toState) continue;
-      if (toState.id === this.currentState?.id) continue;
-
-      if (toState.html || toState.ariaSnapshot) {
-        return toState;
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Load HTML content from file
-   */
-  loadHtmlFromFile(htmlFile: string): string | null {
-    try {
-      const filePath = outputPath('states', htmlFile);
-      if (existsSync(filePath)) {
-        return readFileSync(filePath, 'utf8');
-      }
-      return null;
-    } catch (error) {
-      debugLog('Failed to load HTML from file:', error);
-      return null;
-    }
-  }
-
   /**
    * Clear state history (useful for testing or reset)
    * Note: This preserves the current state, only clears navigation history
@@ -527,15 +393,8 @@ export class StateManager {
     this.stateHistory = [];
     this.allVisitedUrls.clear();
     this.stateChangeListeners = [];
-    this.knowledgeCache = [];
-    this.lastKnowledgeScan = null;
     this.nextStateId = 1;
 
-    // Clean up experience tracker if it has cleanup method
-    if (this.experienceTracker && typeof this.experienceTracker.cleanup === 'function') {
-      this.experienceTracker.cleanup();
-    }
-
     debugLog('StateManager cleanup completed');
   }
 }

package/src/utils/aria.ts

@@ -483,7 +483,7 @@ export const compactAriaSnapshot = (snapshot: string | null, keepNamed = false):
   return renderTree(tree);
 };
 
-export const diffAriaSnapshots = (previous: string | null, current: string | null): string | null => {
+export const diffAriaSnapshots = (previous: string | null, current: string | null): AriaDiff => {
   const flat = (snap: string | null): FlatEntry[] => {
     let tree = parseSnapshot(snap);
     tree = unwrapIgnored(tree);
@@ -500,7 +500,9 @@ export const diffAriaSnapshots = (previous: string | null, current: string | nul
   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], toggled);
+  const added = [...byCount.added, ...renames.added];
+  const removed = [...byCount.removed, ...renames.removed];
+  return { text: formatDiff(added, removed, toggled), count: added.length + removed.length + toggled.length };
 };
 
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
@@ -570,10 +572,17 @@ export function parseAriaLocator(ariaStr: string): { role: string; text: string
   return { role: match[1], text: match[2] };
 }
 
+export const LARGE_ARIA_CHANGE_THRESHOLD = 50;
+
 // ─────────────────────────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────────────────────────
 
+export interface AriaDiff {
+  text: string | null;
+  count: number;
+}
+
 type AriaNode = {
   role: string;
   name?: string;