@qontinui/ui-bridge 0.1.1 → 0.2.0

package/dist/types-CFT3Dnx4.d.mts

@@ -0,0 +1,534 @@
+import { i as ElementType, h as ElementState } from './types-CPMbN_Iw.mjs';
+import { D as DiscoveredElement } from './types-Dr6tH-bm.mjs';
+
+/**
+ * AI Module Types
+ *
+ * Defines types for AI-native UI Bridge functionality including
+ * search criteria, natural language actions, assertions, and semantic snapshots.
+ */
+
+/**
+ * Criteria for searching elements using multiple strategies
+ */
+interface SearchCriteria {
+    /** Exact visible text match: "Start Extraction" */
+    text?: string;
+    /** Partial text match: "Start" */
+    textContains?: string;
+    /** Accessible name (aria-label, associated labels) */
+    accessibleName?: string;
+    /** ARIA role: "button", "input" */
+    role?: string;
+    /** Element type (more specific than role) */
+    type?: ElementType;
+    /** Spatial proximity: "near the URL input" */
+    near?: string;
+    /** Container context: "within the login form" */
+    within?: string;
+    /** Enable fuzzy matching (default: true) */
+    fuzzy?: boolean;
+    /** Fuzzy match confidence threshold 0-1 (default: 0.7) */
+    fuzzyThreshold?: number;
+    /** Element ID pattern (supports wildcards) */
+    idPattern?: string;
+    /** CSS selector */
+    selector?: string;
+    /** Placeholder text (for inputs) */
+    placeholder?: string;
+    /** Title attribute */
+    title?: string;
+    /** Data attributes to match */
+    dataAttributes?: Record<string, string>;
+}
+/**
+ * Result from a search operation
+ */
+interface SearchResult {
+    /** The matched element */
+    element: AIDiscoveredElement;
+    /** Match confidence 0-1 */
+    confidence: number;
+    /** Reasons why this element matched */
+    matchReasons: string[];
+    /** Match scores by strategy */
+    scores: {
+        text?: number;
+        accessibility?: number;
+        role?: number;
+        spatial?: number;
+        fuzzy?: number;
+    };
+}
+/**
+ * Response from search operations
+ */
+interface SearchResponse {
+    /** All matching results sorted by confidence */
+    results: SearchResult[];
+    /** Best match (highest confidence above threshold) */
+    bestMatch: SearchResult | null;
+    /** Total elements scanned */
+    scannedCount: number;
+    /** Search duration in milliseconds */
+    durationMs: number;
+    /** Search criteria used */
+    criteria: SearchCriteria;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Element with AI-generated metadata and descriptions
+ */
+interface AIDiscoveredElement extends DiscoveredElement {
+    /** Human-readable description: "Blue submit button in the form" */
+    description: string;
+    /** Auto-generated aliases for natural language matching */
+    aliases: string[];
+    /** Inferred purpose: "Submits the form" */
+    purpose?: string;
+    /** Parent context identifier */
+    parentContext?: string;
+    /** Suggested actions in natural language */
+    suggestedActions: string[];
+    /** Semantic type (more descriptive than ElementType) */
+    semanticType?: string;
+    /** Associated label text */
+    labelText?: string;
+    /** Placeholder text (for inputs) */
+    placeholder?: string;
+    /** Title attribute */
+    title?: string;
+    /** ARIA description */
+    ariaDescription?: string;
+}
+/**
+ * Response from AI find operations
+ */
+interface AIFindResponse {
+    /** All discovered elements with AI metadata */
+    elements: AIDiscoveredElement[];
+    /** LLM-friendly text summary of the page */
+    summary: string;
+    /** Detected forms with their fields */
+    forms?: FormAnalysis[];
+    /** Page context information */
+    pageContext: PageContext;
+    /** Find duration */
+    durationMs: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Page context information
+ */
+interface PageContext {
+    /** Current URL */
+    url: string;
+    /** Page title */
+    title: string;
+    /** Inferred page type */
+    pageType?: 'login' | 'dashboard' | 'form' | 'list' | 'detail' | 'search' | 'checkout' | 'settings' | 'unknown';
+    /** Active modals/dialogs */
+    activeModals: string[];
+    /** Currently focused element */
+    focusedElement?: string;
+    /** Detected navigation elements */
+    navigation?: string[];
+}
+/**
+ * Form analysis result
+ */
+interface FormAnalysis {
+    /** Form element ID */
+    id: string;
+    /** Form name attribute */
+    name?: string;
+    /** Detected form purpose */
+    purpose?: string;
+    /** Form fields */
+    fields: FormFieldAnalysis[];
+    /** Whether form is valid */
+    isValid: boolean;
+    /** Submit button ID */
+    submitButton?: string;
+    /** Cancel/reset button ID */
+    cancelButton?: string;
+}
+/**
+ * Form field analysis
+ */
+interface FormFieldAnalysis {
+    /** Field element ID */
+    id: string;
+    /** Field label */
+    label: string;
+    /** Input type */
+    type: string;
+    /** Current value */
+    value: string;
+    /** Whether field is valid */
+    valid: boolean;
+    /** Validation error message */
+    error?: string;
+    /** Whether field is required */
+    required: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+}
+/**
+ * Natural language action request
+ */
+interface NLActionRequest {
+    /** Natural language instruction: "click the Start Extraction button" */
+    instruction: string;
+    /** Optional context to help disambiguate */
+    context?: string;
+    /** Timeout for the operation */
+    timeout?: number;
+    /** Confidence threshold for element matching */
+    confidenceThreshold?: number;
+}
+/**
+ * Parsed action from natural language
+ */
+interface ParsedAction {
+    /** Action type */
+    action: 'click' | 'type' | 'select' | 'check' | 'uncheck' | 'scroll' | 'wait' | 'assert' | 'hover' | 'focus' | 'clear' | 'doubleClick' | 'rightClick';
+    /** Description of the target element */
+    targetDescription: string;
+    /** Value for type/select actions */
+    value?: string;
+    /** Key modifiers */
+    modifiers?: ('shift' | 'ctrl' | 'alt' | 'meta')[];
+    /** Scroll direction for scroll actions */
+    scrollDirection?: 'up' | 'down' | 'left' | 'right';
+    /** Wait condition for wait actions */
+    waitCondition?: string;
+    /** Assertion type for assert actions */
+    assertionType?: AssertionType;
+    /** Raw instruction that was parsed */
+    rawInstruction: string;
+    /** Parse confidence */
+    parseConfidence: number;
+}
+/**
+ * Response from executing a natural language action
+ */
+interface NLActionResponse {
+    /** Whether the action succeeded */
+    success: boolean;
+    /** Human-readable description of what was done */
+    executedAction: string;
+    /** The element that was used */
+    elementUsed: AIDiscoveredElement;
+    /** Match confidence for the element */
+    confidence: number;
+    /** Element state after the action */
+    elementState: ElementState;
+    /** Action duration */
+    durationMs: number;
+    /** Timestamp */
+    timestamp: number;
+    /** Error message if failed */
+    error?: string;
+    /** Error code */
+    errorCode?: string;
+    /** Suggestions for recovery */
+    suggestions?: string[];
+    /** Alternative elements that could have been used */
+    alternatives?: SearchResult[];
+}
+/**
+ * Types of assertions that can be made about elements
+ */
+type AssertionType = 'visible' | 'hidden' | 'enabled' | 'disabled' | 'focused' | 'checked' | 'unchecked' | 'hasText' | 'containsText' | 'hasValue' | 'hasClass' | 'exists' | 'notExists' | 'count' | 'attribute' | 'cssProperty';
+/**
+ * Assertion request
+ */
+interface AssertionRequest {
+    /** Element target (ID or natural language description) */
+    target: string | SearchCriteria;
+    /** Type of assertion */
+    type: AssertionType;
+    /** Expected value (for hasText, hasValue, count, attribute, cssProperty) */
+    expected?: unknown;
+    /** Attribute name (for attribute assertions) */
+    attributeName?: string;
+    /** CSS property name (for cssProperty assertions) */
+    propertyName?: string;
+    /** Timeout for waiting (ms) */
+    timeout?: number;
+    /** Custom failure message */
+    message?: string;
+    /** Whether to use fuzzy matching for element search */
+    fuzzy?: boolean;
+}
+/**
+ * Assertion result
+ */
+interface AssertionResult {
+    /** Whether the assertion passed */
+    passed: boolean;
+    /** Element target that was checked */
+    target: string;
+    /** Human-readable description of the target */
+    targetDescription: string;
+    /** Expected value */
+    expected: unknown;
+    /** Actual value */
+    actual: unknown;
+    /** Failure reason if assertion failed */
+    failureReason?: string;
+    /** Suggestion for fixing the failure */
+    suggestion?: string;
+    /** Element state at time of assertion */
+    elementState?: ElementState;
+    /** Duration of the assertion */
+    durationMs: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Batch assertion request
+ */
+interface BatchAssertionRequest {
+    /** Assertions to execute */
+    assertions: AssertionRequest[];
+    /** Mode: 'all' requires all to pass, 'any' requires at least one */
+    mode: 'all' | 'any';
+    /** Stop on first failure */
+    stopOnFailure?: boolean;
+}
+/**
+ * Batch assertion result
+ */
+interface BatchAssertionResult {
+    /** Overall pass/fail */
+    passed: boolean;
+    /** Individual assertion results */
+    results: AssertionResult[];
+    /** Number of passed assertions */
+    passedCount: number;
+    /** Number of failed assertions */
+    failedCount: number;
+    /** Total duration */
+    durationMs: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Semantic snapshot of the current page state
+ */
+interface SemanticSnapshot {
+    /** Snapshot timestamp */
+    timestamp: number;
+    /** Snapshot ID for diffing */
+    snapshotId: string;
+    /** Page information */
+    page: PageContext;
+    /** All elements with AI metadata */
+    elements: AIDiscoveredElement[];
+    /** Form states */
+    forms: FormState[];
+    /** Active modals */
+    activeModals: ModalState[];
+    /** Currently focused element */
+    focusedElement?: string;
+    /** LLM-readable summary */
+    summary: string;
+    /** Element count by type */
+    elementCounts: Record<string, number>;
+}
+/**
+ * Form state in semantic snapshot
+ */
+interface FormState {
+    /** Form ID */
+    id: string;
+    /** Form name */
+    name?: string;
+    /** Form purpose */
+    purpose?: string;
+    /** Field states */
+    fields: FormFieldState[];
+    /** Overall validity */
+    isValid: boolean;
+    /** Submit button */
+    submitButton?: string;
+    /** Whether form is dirty (has changes) */
+    isDirty: boolean;
+}
+/**
+ * Form field state
+ */
+interface FormFieldState {
+    /** Field ID */
+    id: string;
+    /** Field label */
+    label: string;
+    /** Input type */
+    type: string;
+    /** Current value */
+    value: string;
+    /** Validity */
+    valid: boolean;
+    /** Error message */
+    error?: string;
+    /** Required flag */
+    required: boolean;
+    /** Touched flag */
+    touched: boolean;
+}
+/**
+ * Modal/dialog state
+ */
+interface ModalState {
+    /** Modal ID */
+    id: string;
+    /** Modal title */
+    title?: string;
+    /** Modal type */
+    type: 'dialog' | 'alert' | 'confirm' | 'prompt' | 'drawer' | 'popup';
+    /** Whether modal is blocking */
+    blocking: boolean;
+    /** Close button ID */
+    closeButton?: string;
+    /** Primary action button */
+    primaryAction?: string;
+    /** Secondary action button */
+    secondaryAction?: string;
+}
+/**
+ * Semantic diff between two snapshots
+ */
+interface SemanticDiff {
+    /** LLM-readable summary of changes */
+    summary: string;
+    /** From snapshot ID */
+    fromSnapshotId: string;
+    /** To snapshot ID */
+    toSnapshotId: string;
+    /** Detailed changes */
+    changes: {
+        /** Elements that appeared */
+        appeared: ElementChange[];
+        /** Elements that disappeared */
+        disappeared: ElementChange[];
+        /** Elements that were modified */
+        modified: ElementModification[];
+    };
+    /** Probable trigger for the changes */
+    probableTrigger?: string;
+    /** Suggested next actions based on changes */
+    suggestedActions?: string[];
+    /** Page context changes */
+    pageChanges?: {
+        urlChanged: boolean;
+        titleChanged: boolean;
+        newUrl?: string;
+        newTitle?: string;
+    };
+    /** Duration of diff computation */
+    durationMs: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Element change (appeared/disappeared)
+ */
+interface ElementChange {
+    /** Element ID */
+    elementId: string;
+    /** Element description */
+    description: string;
+    /** Element type */
+    type: string;
+    /** Semantic type */
+    semanticType?: string;
+}
+/**
+ * Element modification
+ */
+interface ElementModification {
+    /** Element ID */
+    elementId: string;
+    /** Element description */
+    description: string;
+    /** Property that changed */
+    property: string;
+    /** Previous value */
+    from: string;
+    /** New value */
+    to: string;
+    /** Whether this is a significant change */
+    significant: boolean;
+}
+/**
+ * Rich error context for AI agents
+ */
+interface AIErrorContext {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** What action was attempted */
+    attemptedAction: string;
+    /** Search criteria used (if applicable) */
+    searchCriteria?: SearchCriteria;
+    /** Information about what was found */
+    searchResults: {
+        /** Number of candidates found */
+        candidatesFound: number;
+        /** Nearest match if any */
+        nearestMatch?: {
+            element: AIDiscoveredElement;
+            confidence: number;
+            whyNotSelected: string;
+        };
+    };
+    /** Page state at time of error */
+    pageContext: {
+        url: string;
+        title: string;
+        visibleElements: number;
+        /** Possible blockers like modals */
+        possibleBlockers: string[];
+    };
+    /** Recovery suggestions */
+    suggestions: RecoverySuggestion[];
+    /** Stack trace if available */
+    stack?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Recovery suggestion for errors
+ */
+interface RecoverySuggestion {
+    /** Human-readable action description */
+    action: string;
+    /** Command to execute (if applicable) */
+    command?: string;
+    /** Confidence that this will help */
+    confidence: number;
+    /** Priority (lower = try first) */
+    priority: number;
+}
+/**
+ * Extended element registration options with AI metadata
+ */
+interface AIElementRegistrationOptions {
+    /** Alternative names for the element */
+    aliases?: string[];
+    /** Human-readable description */
+    description?: string;
+    /** Semantic type (more descriptive than ElementType) */
+    semanticType?: string;
+    /** Purpose of the element */
+    purpose?: string;
+    /** Whether to auto-generate aliases */
+    autoGenerateAliases?: boolean;
+}
+
+export type { AIDiscoveredElement as A, BatchAssertionRequest as B, ElementChange as E, FormAnalysis as F, ModalState as M, NLActionRequest as N, PageContext as P, RecoverySuggestion as R, SearchCriteria as S, AIElementRegistrationOptions as a, AIErrorContext as b, AIFindResponse as c, AssertionRequest as d, AssertionResult as e, AssertionType as f, BatchAssertionResult as g, ElementModification as h, FormFieldAnalysis as i, FormFieldState as j, FormState as k, NLActionResponse as l, ParsedAction as m, SearchResponse as n, SearchResult as o, SemanticDiff as p, SemanticSnapshot as q };

package/dist/{types-BpvpStn3.d.mts → types-CPMbN_Iw.d.mts}

@@ -108,6 +108,14 @@ interface RegisteredElement {
     registeredAt: number;
     /** Whether this element is currently mounted */
     mounted: boolean;
+    /** Alternative names for natural language matching */
+    aliases?: string[];
+    /** Human-readable description for AI agents */
+    description?: string;
+    /** Semantic type (more descriptive than ElementType) */
+    semanticType?: string;
+    /** Purpose of the element */
+    purpose?: string;
 }
 /**
  * Component action definition

package/dist/{types-BpvpStn3.d.ts → types-CPMbN_Iw.d.ts}

@@ -108,6 +108,14 @@ interface RegisteredElement {
     registeredAt: number;
     /** Whether this element is currently mounted */
     mounted: boolean;
+    /** Alternative names for natural language matching */
+    aliases?: string[];
+    /** Human-readable description for AI agents */
+    description?: string;
+    /** Semantic type (more descriptive than ElementType) */
+    semanticType?: string;
+    /** Purpose of the element */
+    purpose?: string;
 }
 /**
  * Component action definition

package/dist/{types-DdJD9yw5.d.mts → types-Dr6tH-bm.d.mts}

@@ -1,4 +1,4 @@
-import { a as ActionRequest, b as ActionResponse, a0 as WaitOptions, h as ElementState } from './types-BpvpStn3.mjs';
+import { h as ElementState, a as ActionRequest, b as ActionResponse, a0 as WaitOptions } from './types-CPMbN_Iw.mjs';
 
 /**
  * Control Module Types

package/dist/{types-BDkXy5si.d.ts → types-oCTrRxSw.d.ts}

@@ -1,4 +1,4 @@
-import { a as ActionRequest, b as ActionResponse, a0 as WaitOptions, h as ElementState } from './types-BpvpStn3.js';
+import { h as ElementState, a as ActionRequest, b as ActionResponse, a0 as WaitOptions } from './types-CPMbN_Iw.js';
 
 /**
  * Control Module Types

package/dist/{websocket-client-DupH0X7B.d.ts → websocket-client-CX4QJesI.d.ts}

@@ -1,4 +1,4 @@
-import { W as WSClientConfig, t as WSConnectionState, X as WSSubscriptionOptions, e as BridgeEventType, f as BridgeSnapshot, a as ActionRequest, b as ActionResponse, c as BridgeEvent } from './types-BpvpStn3.js';
+import { W as WSClientConfig, t as WSConnectionState, X as WSSubscriptionOptions, e as BridgeEventType, f as BridgeSnapshot, a as ActionRequest, b as ActionResponse, c as BridgeEvent } from './types-CPMbN_Iw.js';
 
 /**
  * WebSocket Client for UI Bridge

package/dist/{websocket-client-B2LC9CYc.d.mts → websocket-client-C_Na0OSp.d.mts}

@@ -1,4 +1,4 @@
-import { W as WSClientConfig, t as WSConnectionState, X as WSSubscriptionOptions, e as BridgeEventType, f as BridgeSnapshot, a as ActionRequest, b as ActionResponse, c as BridgeEvent } from './types-BpvpStn3.mjs';
+import { W as WSClientConfig, t as WSConnectionState, X as WSSubscriptionOptions, e as BridgeEventType, f as BridgeSnapshot, a as ActionRequest, b as ActionResponse, c as BridgeEvent } from './types-CPMbN_Iw.mjs';
 
 /**
  * WebSocket Client for UI Bridge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qontinui/ui-bridge",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "UI Bridge Framework - React hooks and providers for UI observation, control, and debugging",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -35,6 +35,11 @@
       "types": "./dist/debug/index.d.ts",
       "import": "./dist/debug/index.mjs",
       "require": "./dist/debug/index.js"
+    },
+    "./ai": {
+      "types": "./dist/ai/index.d.ts",
+      "import": "./dist/ai/index.mjs",
+      "require": "./dist/ai/index.js"
     }
   },
   "files": [