@qontinui/ui-bridge 0.1.1 → 0.3.0

package/dist/ai/index.d.ts

@@ -0,0 +1,893 @@
+import { S as SearchCriteria, n as SearchResponse, o as SearchResult, A as AIDiscoveredElement, P as PageContext, t as SemanticSnapshot, m as ParsedAction, N as NLActionRequest, l as NLActionResponse, b as AIErrorContext, d as AssertionRequest, e as AssertionResult, B as BatchAssertionRequest, g as BatchAssertionResult, p as SemanticDiff, R as RecoverySuggestion } from '../types-DfPqwU-i.js';
+export { a as AIElementRegistrationOptions, c as AIFindResponse, f as AssertionType, E as ElementChange, h as ElementModification, F as FormAnalysis, i as FormFieldAnalysis, j as FormFieldState, k as FormState, M as ModalState, q as SemanticSearchCriteria, r as SemanticSearchResponse, s as SemanticSearchResult } from '../types-DfPqwU-i.js';
+import { x as RegisteredElement, q as ElementState } from '../types-jKVgTI6_.js';
+import { D as DiscoveredElement, A as ActionExecutor, d as ControlSnapshot } from '../types-BkNRILUa.js';
+
+/**
+ * Fuzzy Matcher
+ *
+ * Provides fuzzy text matching utilities for finding elements by natural language descriptions.
+ * Implements multiple matching algorithms with configurable thresholds.
+ */
+/**
+ * Configuration for fuzzy matching
+ */
+interface FuzzyMatchConfig {
+    /** Minimum similarity threshold (0-1) */
+    threshold: number;
+    /** Weight for Levenshtein distance */
+    levenshteinWeight: number;
+    /** Weight for Jaro-Winkler similarity */
+    jaroWinklerWeight: number;
+    /** Weight for N-gram matching */
+    ngramWeight: number;
+    /** N-gram size */
+    ngramSize: number;
+    /** Case sensitive matching */
+    caseSensitive: boolean;
+    /** Ignore whitespace differences */
+    ignoreWhitespace: boolean;
+}
+/**
+ * Default fuzzy match configuration
+ */
+declare const DEFAULT_FUZZY_CONFIG: FuzzyMatchConfig;
+/**
+ * Result from a fuzzy match operation
+ */
+interface FuzzyMatchResult {
+    /** Overall similarity score (0-1) */
+    similarity: number;
+    /** Whether the match passes the threshold */
+    isMatch: boolean;
+    /** Individual algorithm scores */
+    scores: {
+        levenshtein: number;
+        jaroWinkler: number;
+        ngram: number;
+    };
+    /** Normalized source string */
+    normalizedSource: string;
+    /** Normalized target string */
+    normalizedTarget: string;
+}
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+declare function levenshteinDistance(s1: string, s2: string): number;
+/**
+ * Calculate Levenshtein similarity (0-1)
+ */
+declare function levenshteinSimilarity(s1: string, s2: string): number;
+/**
+ * Calculate Jaro similarity between two strings
+ */
+declare function jaroSimilarity(s1: string, s2: string): number;
+/**
+ * Calculate Jaro-Winkler similarity
+ * Gives more weight to strings that match from the beginning
+ */
+declare function jaroWinklerSimilarity(s1: string, s2: string, prefixScale?: number): number;
+/**
+ * Generate N-grams from a string
+ */
+declare function generateNgrams(s: string, n: number): Set<string>;
+/**
+ * Calculate N-gram similarity (Jaccard coefficient)
+ */
+declare function ngramSimilarity(s1: string, s2: string, n?: number): number;
+/**
+ * Normalize a string for comparison
+ */
+declare function normalizeString(s: string, config?: Partial<FuzzyMatchConfig>): string;
+/**
+ * Main fuzzy match function
+ * Combines multiple algorithms for robust matching
+ */
+declare function fuzzyMatch(source: string, target: string, config?: Partial<FuzzyMatchConfig>): FuzzyMatchResult;
+/**
+ * Find the best match from a list of candidates
+ */
+declare function findBestMatch(source: string, candidates: string[], config?: Partial<FuzzyMatchConfig>): {
+    match: string | null;
+    index: number;
+    result: FuzzyMatchResult | null;
+};
+/**
+ * Find all matches above threshold
+ */
+declare function findAllMatches(source: string, candidates: string[], config?: Partial<FuzzyMatchConfig>): Array<{
+    candidate: string;
+    index: number;
+    result: FuzzyMatchResult;
+}>;
+/**
+ * Check if source contains target (fuzzy)
+ */
+declare function fuzzyContains(source: string, target: string, config?: Partial<FuzzyMatchConfig>): boolean;
+/**
+ * Calculate word-level similarity
+ * Useful for comparing phrases
+ */
+declare function wordSimilarity(s1: string, s2: string, config?: Partial<FuzzyMatchConfig>): number;
+/**
+ * Tokenize a string for matching
+ * Handles camelCase, PascalCase, snake_case, kebab-case
+ */
+declare function tokenize(s: string): string[];
+/**
+ * Calculate token-based similarity
+ * Better for matching identifiers and labels
+ */
+declare function tokenSimilarity(s1: string, s2: string): number;
+
+/**
+ * Alias Generator
+ *
+ * Auto-generates element aliases from visible text, aria-label, placeholders,
+ * titles, and common synonyms for natural language matching.
+ */
+/**
+ * Configuration for alias generation
+ */
+interface AliasGeneratorConfig {
+    /** Include text content as alias */
+    includeText: boolean;
+    /** Include aria-label as alias */
+    includeAriaLabel: boolean;
+    /** Include placeholder text as alias */
+    includePlaceholder: boolean;
+    /** Include title attribute as alias */
+    includeTitle: boolean;
+    /** Include common synonyms */
+    includeSynonyms: boolean;
+    /** Maximum number of aliases to generate */
+    maxAliases: number;
+    /** Minimum alias length */
+    minLength: number;
+    /** Maximum alias length */
+    maxLength: number;
+}
+/**
+ * Default alias generator configuration
+ */
+declare const DEFAULT_ALIAS_CONFIG: AliasGeneratorConfig;
+/**
+ * Interface for element information used in alias generation
+ */
+interface AliasGeneratorInput {
+    /** Element text content */
+    textContent?: string | null;
+    /** ARIA label */
+    ariaLabel?: string | null;
+    /** ARIA labelledby resolved text */
+    ariaLabelledBy?: string | null;
+    /** Placeholder text */
+    placeholder?: string | null;
+    /** Title attribute */
+    title?: string | null;
+    /** Element type */
+    elementType?: string;
+    /** Element tag name */
+    tagName?: string;
+    /** Input type */
+    inputType?: string;
+    /** Element ID */
+    id?: string | null;
+    /** Element name attribute */
+    name?: string | null;
+    /** Associated label text */
+    labelText?: string | null;
+    /** Value attribute */
+    value?: string | null;
+}
+/**
+ * Generate aliases for an element
+ */
+declare function generateAliases(input: AliasGeneratorInput, config?: Partial<AliasGeneratorConfig>): string[];
+/**
+ * Generate a human-readable description for an element
+ */
+declare function generateDescription(input: AliasGeneratorInput): string;
+/**
+ * Generate a purpose statement for an element
+ */
+declare function generatePurpose(input: AliasGeneratorInput): string | undefined;
+/**
+ * Generate suggested actions for an element
+ */
+declare function generateSuggestedActions(input: AliasGeneratorInput): string[];
+/**
+ * Get synonyms for a word
+ */
+declare function getSynonyms(word: string): string[];
+/**
+ * Check if two words are synonyms
+ */
+declare function areSynonyms(word1: string, word2: string): boolean;
+
+/**
+ * Search Engine
+ *
+ * Multi-strategy element search using text, role, accessibility,
+ * spatial proximity, and fuzzy matching.
+ */
+
+/**
+ * Configuration for the search engine
+ */
+interface SearchEngineConfig {
+    /** Default fuzzy threshold */
+    fuzzyThreshold: number;
+    /** Weight for text matching */
+    textWeight: number;
+    /** Weight for accessibility matching */
+    accessibilityWeight: number;
+    /** Weight for role matching */
+    roleWeight: number;
+    /** Weight for spatial matching */
+    spatialWeight: number;
+    /** Weight for alias matching */
+    aliasWeight: number;
+    /** Maximum results to return */
+    maxResults: number;
+    /** Include hidden elements */
+    includeHidden: boolean;
+}
+/**
+ * Default search engine configuration
+ */
+declare const DEFAULT_SEARCH_CONFIG: SearchEngineConfig;
+/**
+ * Search Engine class
+ */
+declare class SearchEngine {
+    private config;
+    private cachedElements;
+    private cacheTimestamp;
+    private readonly cacheValidityMs;
+    constructor(config?: Partial<SearchEngineConfig>);
+    /**
+     * Update cached elements from various sources
+     */
+    updateElements(elements: Array<DiscoveredElement | RegisteredElement>, getState?: (el: RegisteredElement) => ElementState): void;
+    /**
+     * Convert an element to searchable format
+     */
+    private toSearchable;
+    /**
+     * Search for elements matching the criteria
+     */
+    search(criteria: SearchCriteria, elements?: Array<DiscoveredElement | RegisteredElement>): SearchResponse;
+    /**
+     * Find the best matching element
+     */
+    findBest(criteria: SearchCriteria, elements?: Array<DiscoveredElement | RegisteredElement>): SearchResult | null;
+    /**
+     * Find elements by text content
+     */
+    findByText(text: string, fuzzy?: boolean, elements?: Array<DiscoveredElement | RegisteredElement>): SearchResult[];
+    /**
+     * Find elements by role
+     */
+    findByRole(role: string, name?: string, elements?: Array<DiscoveredElement | RegisteredElement>): SearchResult[];
+    /**
+     * Find elements by accessible name
+     */
+    findByAccessibleName(name: string, elements?: Array<DiscoveredElement | RegisteredElement>): SearchResult[];
+    /**
+     * Find elements near another element
+     */
+    findNear(referenceId: string, criteria?: SearchCriteria, elements?: Array<DiscoveredElement | RegisteredElement>): SearchResult[];
+    /**
+     * Find elements within a container
+     */
+    findWithin(containerId: string, criteria?: SearchCriteria, elements?: Array<DiscoveredElement | RegisteredElement>): SearchResult[];
+    /**
+     * Score an element against search criteria
+     */
+    private scoreElement;
+    /**
+     * Score text match
+     */
+    private scoreTextMatch;
+    /**
+     * Score contains match
+     */
+    private scoreContainsMatch;
+    /**
+     * Score accessibility match
+     */
+    private scoreAccessibilityMatch;
+    /**
+     * Score role match
+     */
+    private scoreRoleMatch;
+    /**
+     * Score spatial match (proximity to another element)
+     */
+    private scoreSpatialMatch;
+    /**
+     * Calculate distance between two element rectangles
+     */
+    private calculateDistance;
+    /**
+     * Score alias match
+     */
+    private scoreAliasMatch;
+    /**
+     * Match a string against a pattern (supports * wildcard)
+     */
+    private matchPattern;
+    /**
+     * Convert searchable element to AI discovered element
+     */
+    private toAIDiscoveredElement;
+    /**
+     * Infer a semantic type for the element
+     */
+    private inferSemanticType;
+}
+/**
+ * Create a default search engine instance
+ */
+declare function createSearchEngine(config?: Partial<SearchEngineConfig>): SearchEngine;
+
+/**
+ * Summary Generator
+ *
+ * Generates LLM-friendly text summaries of pages and elements
+ * for AI agents to understand the current UI state.
+ */
+
+/**
+ * Configuration for summary generation
+ */
+interface SummaryConfig {
+    /** Maximum summary length in characters */
+    maxLength: number;
+    /** Include form details */
+    includeForms: boolean;
+    /** Include element counts */
+    includeElementCounts: boolean;
+    /** Include active modals */
+    includeModals: boolean;
+    /** Include focused element */
+    includeFocused: boolean;
+    /** Verbosity level */
+    verbosity: 'brief' | 'normal' | 'detailed';
+}
+/**
+ * Generate a page summary from elements
+ */
+declare function generatePageSummary(elements: AIDiscoveredElement[], pageContext?: Partial<PageContext>, config?: Partial<SummaryConfig>): string;
+/**
+ * Generate an element description
+ */
+declare function generateElementDescription(element: AIDiscoveredElement): string;
+/**
+ * Generate a snapshot summary
+ */
+declare function generateSnapshotSummary(snapshot: SemanticSnapshot, config?: Partial<SummaryConfig>): string;
+/**
+ * Generate diff summary
+ */
+declare function generateDiffSummary(appeared: string[], disappeared: string[], modified: Array<{
+    description: string;
+    property: string;
+    from: string;
+    to: string;
+}>): string;
+/**
+ * Infer page type from URL and elements
+ */
+declare function inferPageType(url: string, title: string, elements: AIDiscoveredElement[]): PageContext['pageType'];
+
+/**
+ * Natural Language Action Parser
+ *
+ * Parses natural language instructions into structured action requests.
+ * Handles patterns like "click the Submit button" or "type 'hello' in the search box".
+ */
+
+/**
+ * Parse a natural language instruction into a structured action
+ */
+declare function parseNLInstruction(instruction: string): ParsedAction | null;
+/**
+ * Parse multiple instructions
+ */
+declare function parseNLInstructions(instructions: string[]): ParsedAction[];
+/**
+ * Split a complex instruction into simple ones
+ * e.g., "click Login and type 'admin' in username" -> ["click Login", "type 'admin' in username"]
+ */
+declare function splitCompoundInstruction(instruction: string): string[];
+/**
+ * Extract modifiers from instruction
+ */
+declare function extractModifiers(instruction: string): ParsedAction['modifiers'];
+/**
+ * Validate a parsed action
+ */
+declare function validateParsedAction(action: ParsedAction): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Generate a human-readable description of a parsed action
+ */
+declare function describeAction(action: ParsedAction): string;
+
+/**
+ * Natural Language Action Executor
+ *
+ * Executes parsed natural language actions by searching for elements
+ * and performing the requested actions with confidence scoring.
+ */
+
+/**
+ * Configuration for the NL action executor
+ */
+interface NLActionExecutorConfig {
+    /** Default confidence threshold for element matching */
+    defaultConfidenceThreshold: number;
+    /** Default timeout for actions */
+    defaultTimeout: number;
+    /** Maximum alternatives to return on failure */
+    maxAlternatives: number;
+    /** Search engine configuration */
+    searchConfig?: Partial<SearchEngineConfig>;
+    /** Enable verbose logging */
+    verbose: boolean;
+}
+/**
+ * Default executor configuration
+ */
+declare const DEFAULT_EXECUTOR_CONFIG: NLActionExecutorConfig;
+/**
+ * Natural Language Action Executor
+ */
+declare class NLActionExecutor {
+    private config;
+    private searchEngine;
+    private actionExecutor;
+    private elements;
+    constructor(config?: Partial<NLActionExecutorConfig>);
+    /**
+     * Set the action executor for performing DOM actions
+     */
+    setActionExecutor(executor: ActionExecutor): void;
+    /**
+     * Update available elements for search
+     */
+    updateElements(elements: Array<DiscoveredElement | RegisteredElement>): void;
+    /**
+     * Execute a natural language instruction
+     */
+    execute(request: NLActionRequest): Promise<NLActionResponse>;
+    /**
+     * Execute a parsed action directly (skip parsing)
+     */
+    executeParsed(parsed: ParsedAction, threshold?: number): Promise<NLActionResponse>;
+    /**
+     * Build search criteria from a parsed action
+     */
+    private buildSearchCriteria;
+    /**
+     * Perform the actual action on an element
+     */
+    private performAction;
+    /**
+     * Create a failure response with suggestions
+     */
+    private createFailureResponse;
+    /**
+     * Generate recovery suggestions
+     */
+    private generateSuggestions;
+    /**
+     * Get rich error context for debugging
+     */
+    getErrorContext(errorCode: string, instruction: string, searchCriteria?: SearchCriteria, nearestMatch?: SearchResult): AIErrorContext;
+}
+/**
+ * Create a default NL action executor
+ */
+declare function createNLActionExecutor(config?: Partial<NLActionExecutorConfig>): NLActionExecutor;
+
+/**
+ * Assertions Module
+ *
+ * Provides verification/assertion API for AI agents to validate
+ * page state without writing Playwright tests.
+ */
+
+/**
+ * Configuration for assertions
+ */
+interface AssertionConfig {
+    /** Default timeout for wait-based assertions */
+    defaultTimeout: number;
+    /** Polling interval for wait-based assertions */
+    pollInterval: number;
+    /** Default fuzzy threshold for element search */
+    fuzzyThreshold: number;
+    /** Include suggestions in failure messages */
+    includeSuggestions: boolean;
+}
+/**
+ * Default assertion configuration
+ */
+declare const DEFAULT_ASSERTION_CONFIG: AssertionConfig;
+/**
+ * Assertion executor class
+ */
+declare class AssertionExecutor {
+    private config;
+    private searchEngine;
+    private elements;
+    constructor(config?: Partial<AssertionConfig>);
+    /**
+     * Update available elements for assertions
+     */
+    updateElements(elements: Array<DiscoveredElement | AIDiscoveredElement>): void;
+    /**
+     * Execute a single assertion
+     */
+    assert(request: AssertionRequest): Promise<AssertionResult>;
+    /**
+     * Execute multiple assertions
+     */
+    assertBatch(request: BatchAssertionRequest): Promise<BatchAssertionResult>;
+    /**
+     * Convenience method: assert element is visible
+     */
+    assertVisible(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is hidden
+     */
+    assertHidden(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is enabled
+     */
+    assertEnabled(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element is disabled
+     */
+    assertDisabled(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element has text
+     */
+    assertHasText(target: string | SearchCriteria, text: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element contains text
+     */
+    assertContainsText(target: string | SearchCriteria, text: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element has value
+     */
+    assertHasValue(target: string | SearchCriteria, value: string, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element exists
+     */
+    assertExists(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element does not exist
+     */
+    assertNotExists(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert checkbox is checked
+     */
+    assertChecked(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert checkbox is unchecked
+     */
+    assertUnchecked(target: string | SearchCriteria, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Convenience method: assert element count
+     */
+    assertCount(target: SearchCriteria, expectedCount: number, timeout?: number): Promise<AssertionResult>;
+    /**
+     * Find element by target (string or criteria)
+     */
+    private findElement;
+    /**
+     * Execute the actual assertion
+     */
+    private executeAssertion;
+    /**
+     * Assert visibility state
+     */
+    private assertVisibility;
+    /**
+     * Assert enabled state
+     */
+    private assertEnabledState;
+    /**
+     * Assert focused state
+     */
+    private assertFocused;
+    /**
+     * Assert checked state
+     */
+    private assertCheckedState;
+    /**
+     * Assert text content
+     */
+    private assertTextMatch;
+    /**
+     * Assert input value
+     */
+    private assertValue;
+    /**
+     * Assert element count
+     */
+    private assertElementCount;
+    /**
+     * Assert attribute value (placeholder for DOM attribute assertions)
+     */
+    private assertAttribute;
+    /**
+     * Assert element has CSS class
+     */
+    private assertHasClass;
+    /**
+     * Assert CSS property value
+     */
+    private assertCssProperty;
+    /**
+     * Create an assertion result
+     */
+    private createResult;
+}
+/**
+ * Create a default assertion executor
+ */
+declare function createAssertionExecutor(config?: Partial<AssertionConfig>): AssertionExecutor;
+
+/**
+ * Semantic Snapshot
+ *
+ * Creates enhanced state snapshots with AI-friendly element descriptions,
+ * form analysis, and modal detection.
+ */
+
+/**
+ * Configuration for semantic snapshots
+ */
+interface SemanticSnapshotConfig {
+    /** Include form analysis */
+    analyzeForms: boolean;
+    /** Include modal detection */
+    detectModals: boolean;
+    /** Include page type inference */
+    inferPageType: boolean;
+    /** Generate element descriptions */
+    generateDescriptions: boolean;
+    /** Maximum elements to include */
+    maxElements: number;
+}
+/**
+ * Default snapshot configuration
+ */
+declare const DEFAULT_SNAPSHOT_CONFIG: SemanticSnapshotConfig;
+/**
+ * Semantic Snapshot Manager
+ */
+declare class SemanticSnapshotManager {
+    private config;
+    private searchEngine;
+    private history;
+    private readonly maxHistorySize;
+    private snapshotCounter;
+    constructor(config?: Partial<SemanticSnapshotConfig>);
+    /**
+     * Create a semantic snapshot from a control snapshot
+     */
+    createSnapshot(controlSnapshot: ControlSnapshot, pageContext?: Partial<PageContext>): SemanticSnapshot;
+    /**
+     * Get the last snapshot
+     */
+    getLastSnapshot(): SemanticSnapshot | null;
+    /**
+     * Get snapshot by ID
+     */
+    getSnapshot(snapshotId: string): SemanticSnapshot | null;
+    /**
+     * Get snapshot history
+     */
+    getHistory(): SemanticSnapshot[];
+    /**
+     * Clear history
+     */
+    clearHistory(): void;
+    /**
+     * Convert control snapshot elements to AI elements
+     */
+    private convertElements;
+    /**
+     * Convert a single element to AI element
+     */
+    private convertElement;
+    /**
+     * Build full page context
+     */
+    private buildPageContext;
+    /**
+     * Analyze forms in the snapshot
+     */
+    private analyzeForms;
+    /**
+     * Detect implicit form from inputs
+     */
+    private detectImplicitForm;
+    /**
+     * Analyze a specific form
+     */
+    private analyzeForm;
+    /**
+     * Analyze form fields
+     */
+    private analyzeFormFields;
+    /**
+     * Detect modal dialogs
+     */
+    private detectModals;
+    /**
+     * Infer modal type
+     */
+    private inferModalType;
+    /**
+     * Count elements by type
+     */
+    private countElementTypes;
+    /**
+     * Infer form purpose from fields
+     */
+    private inferFormPurpose;
+    /**
+     * Infer tag name from element type
+     */
+    private inferTagName;
+    /**
+     * Infer ARIA role from element type
+     */
+    private inferRole;
+    /**
+     * Infer semantic type
+     */
+    private inferSemanticType;
+    /**
+     * Add snapshot to history
+     */
+    private addToHistory;
+}
+/**
+ * Create a semantic snapshot manager
+ */
+declare function createSnapshotManager(config?: Partial<SemanticSnapshotConfig>): SemanticSnapshotManager;
+
+/**
+ * Semantic Diff
+ *
+ * Tracks and describes semantic changes between snapshots
+ * with LLM-friendly summaries and suggested actions.
+ */
+
+/**
+ * Configuration for semantic diff
+ */
+interface SemanticDiffConfig {
+    /** Ignore insignificant changes */
+    ignoreInsignificant: boolean;
+    /** Properties to track for modifications */
+    trackedProperties: string[];
+    /** Generate suggested actions */
+    generateSuggestions: boolean;
+    /** Maximum modifications to report */
+    maxModifications: number;
+}
+/**
+ * Default diff configuration
+ */
+declare const DEFAULT_DIFF_CONFIG: SemanticDiffConfig;
+/**
+ * Compute semantic diff between two snapshots
+ */
+declare function computeDiff(fromSnapshot: SemanticSnapshot, toSnapshot: SemanticSnapshot, config?: Partial<SemanticDiffConfig>): SemanticDiff;
+/**
+ * Create a diff manager for tracking changes over time
+ */
+declare class SemanticDiffManager {
+    private config;
+    private lastSnapshot;
+    constructor(config?: Partial<SemanticDiffConfig>);
+    /**
+     * Update with new snapshot and get diff
+     */
+    update(newSnapshot: SemanticSnapshot): SemanticDiff | null;
+    /**
+     * Get diff from a specific snapshot to current
+     */
+    diffFrom(fromSnapshot: SemanticSnapshot): SemanticDiff | null;
+    /**
+     * Reset the manager
+     */
+    reset(): void;
+    /**
+     * Get the last known snapshot
+     */
+    getLastSnapshot(): SemanticSnapshot | null;
+}
+/**
+ * Create a semantic diff manager
+ */
+declare function createDiffManager(config?: Partial<SemanticDiffConfig>): SemanticDiffManager;
+/**
+ * Utility: Check if any significant changes occurred
+ */
+declare function hasSignificantChanges(diff: SemanticDiff): boolean;
+/**
+ * Utility: Get a brief description of what changed
+ */
+declare function describeDiff(diff: SemanticDiff): string;
+
+/**
+ * Error Context
+ *
+ * Creates rich error context for AI agents to understand and recover
+ * from failures during UI automation.
+ */
+
+/**
+ * Any element type that can be used with error context
+ */
+type AnyElement = DiscoveredElement | AIDiscoveredElement | RegisteredElement;
+/**
+ * Standard error codes
+ */
+declare const ErrorCodes: {
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly ELEMENT_NOT_FOUND: "ELEMENT_NOT_FOUND";
+    readonly ELEMENT_NOT_VISIBLE: "ELEMENT_NOT_VISIBLE";
+    readonly ELEMENT_DISABLED: "ELEMENT_DISABLED";
+    readonly ELEMENT_BLOCKED: "ELEMENT_BLOCKED";
+    readonly MULTIPLE_ELEMENTS: "MULTIPLE_ELEMENTS";
+    readonly LOW_CONFIDENCE: "LOW_CONFIDENCE";
+    readonly AMBIGUOUS_MATCH: "AMBIGUOUS_MATCH";
+    readonly ACTION_FAILED: "ACTION_FAILED";
+    readonly ACTION_TIMEOUT: "ACTION_TIMEOUT";
+    readonly UNSUPPORTED_ACTION: "UNSUPPORTED_ACTION";
+    readonly UNEXPECTED_STATE: "UNEXPECTED_STATE";
+    readonly STALE_ELEMENT: "STALE_ELEMENT";
+    readonly PAGE_LOAD_ERROR: "PAGE_LOAD_ERROR";
+    readonly NAVIGATION_ERROR: "NAVIGATION_ERROR";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Create a rich error context
+ */
+declare function createErrorContext(errorCode: ErrorCode, attemptedAction: string, availableElements: AnyElement[], searchCriteria?: SearchCriteria, nearestMatch?: SearchResult): AIErrorContext;
+/**
+ * Format error context for display
+ */
+declare function formatErrorContext(context: AIErrorContext): string;
+/**
+ * Create a simple error response
+ */
+declare function createSimpleError(code: ErrorCode, message?: string): {
+    code: string;
+    message: string;
+};
+/**
+ * Check if an error is recoverable
+ */
+declare function isRecoverableError(code: ErrorCode): boolean;
+/**
+ * Get the best recovery suggestion for an error
+ */
+declare function getBestRecoverySuggestion(context: AIErrorContext): RecoverySuggestion | null;
+
+export { AIDiscoveredElement, AIErrorContext, type AliasGeneratorConfig, type AliasGeneratorInput, type AssertionConfig, AssertionExecutor, AssertionRequest, AssertionResult, BatchAssertionRequest, BatchAssertionResult, DEFAULT_ALIAS_CONFIG, DEFAULT_ASSERTION_CONFIG, DEFAULT_DIFF_CONFIG, DEFAULT_EXECUTOR_CONFIG, DEFAULT_FUZZY_CONFIG, DEFAULT_SEARCH_CONFIG, DEFAULT_SNAPSHOT_CONFIG, type ErrorCode, ErrorCodes, type FuzzyMatchConfig, type FuzzyMatchResult, NLActionExecutor, type NLActionExecutorConfig, NLActionRequest, NLActionResponse, PageContext, ParsedAction, RecoverySuggestion, SearchCriteria, SearchEngine, type SearchEngineConfig, SearchResponse, SearchResult, SemanticDiff, type SemanticDiffConfig, SemanticDiffManager, SemanticSnapshot, type SemanticSnapshotConfig, SemanticSnapshotManager, type SummaryConfig, areSynonyms, computeDiff, createAssertionExecutor, createDiffManager, createErrorContext, createNLActionExecutor, createSearchEngine, createSimpleError, createSnapshotManager, describeAction, describeDiff, extractModifiers, findAllMatches, findBestMatch, formatErrorContext, fuzzyContains, fuzzyMatch, generateAliases, generateDescription, generateDiffSummary, generateElementDescription, generateNgrams, generatePageSummary, generatePurpose, generateSnapshotSummary, generateSuggestedActions, getBestRecoverySuggestion, getSynonyms, hasSignificantChanges, inferPageType, isRecoverableError, jaroSimilarity, jaroWinklerSimilarity, levenshteinDistance, levenshteinSimilarity, ngramSimilarity, normalizeString, parseNLInstruction, parseNLInstructions, splitCompoundInstruction, tokenSimilarity, tokenize, validateParsedAction, wordSimilarity };