@qontinui/ui-bridge 0.2.0 → 0.3.1

package/dist/types-UBtp7R0u.d.mts

@@ -0,0 +1,132 @@
+/**
+ * Annotation Types
+ *
+ * Types for the semantic annotation system that allows developers
+ * to attach rich human-authored context to UI elements.
+ */
+/**
+ * Annotation for a single UI element.
+ *
+ * All fields are optional - annotate only what's useful.
+ * Annotations provide human-authored semantic context that enriches
+ * the UI Bridge's understanding of elements beyond what can be
+ * inferred from the DOM alone.
+ *
+ * @example Basic annotation for a button
+ * ```ts
+ * const annotation: ElementAnnotation = {
+ *   description: 'Primary login button',
+ *   purpose: 'Submits the login form and authenticates the user',
+ *   tags: ['auth', 'primary-action'],
+ * };
+ * store.set('login-btn', annotation);
+ * ```
+ *
+ * @example Detailed annotation with relationships and metadata
+ * ```ts
+ * const annotation: ElementAnnotation = {
+ *   description: 'Email input field',
+ *   purpose: 'Collects the user email for authentication',
+ *   notes: 'Validates email format on blur. Shows inline error below the field.',
+ *   tags: ['auth', 'form-input', 'required'],
+ *   relatedElements: ['email-label', 'email-error', 'login-btn'],
+ *   metadata: { validationPattern: '^[^@]+@[^@]+\\.[^@]+$' },
+ *   author: 'design-team',
+ * };
+ * ```
+ */
+interface ElementAnnotation {
+    /** Human-readable description of what this element is */
+    description?: string;
+    /** Why this element exists / what it's for */
+    purpose?: string;
+    /** Behavioral notes, edge cases, or caveats */
+    notes?: string;
+    /** Searchable tags for categorization */
+    tags?: string[];
+    /** IDs of related elements (e.g., a label and its input) */
+    relatedElements?: string[];
+    /** Arbitrary key-value metadata */
+    metadata?: Record<string, unknown>;
+    /** Timestamp of last update (auto-set by store) */
+    updatedAt?: number;
+    /** Author of this annotation */
+    author?: string;
+}
+/**
+ * Annotation configuration file format.
+ *
+ * This is the import/export format - a JSON file with version and annotations map.
+ * Use `AnnotationStore.exportConfig()` to generate this object, and
+ * `AnnotationStore.importConfig()` to load it back.
+ *
+ * @example JSON file format (`annotations.json`)
+ * ```json
+ * {
+ *   "version": "1.0.0",
+ *   "annotations": {
+ *     "login-btn": {
+ *       "description": "Primary login button",
+ *       "purpose": "Submits the login form",
+ *       "tags": ["auth", "primary-action"]
+ *     },
+ *     "email-input": {
+ *       "description": "Email address input",
+ *       "purpose": "Collects user email for authentication",
+ *       "relatedElements": ["email-label", "email-error"]
+ *     }
+ *   },
+ *   "metadata": {
+ *     "appName": "MyApp",
+ *     "description": "Annotations for the login page"
+ *   }
+ * }
+ * ```
+ */
+interface AnnotationConfig {
+    /** Config format version */
+    version: string;
+    /** Map of element ID to annotation */
+    annotations: Record<string, ElementAnnotation>;
+    /** Optional file-level metadata */
+    metadata?: {
+        appName?: string;
+        exportedAt?: number;
+        description?: string;
+    };
+}
+/**
+ * Annotation coverage statistics.
+ */
+interface AnnotationCoverage {
+    /** Total elements known to the system */
+    totalElements: number;
+    /** Elements that have annotations */
+    annotatedElements: number;
+    /** Coverage as a percentage (0-100) */
+    coveragePercent: number;
+    /** IDs of annotated elements */
+    annotatedIds: string[];
+    /** IDs of unannotated elements */
+    unannotatedIds: string[];
+    /** When this coverage was computed */
+    timestamp: number;
+}
+/**
+ * Event types emitted by the annotation store.
+ */
+type AnnotationEventType = 'annotation:set' | 'annotation:deleted' | 'annotation:imported' | 'annotation:cleared';
+/**
+ * Event payload for annotation store events.
+ */
+interface AnnotationEvent {
+    type: AnnotationEventType;
+    elementId?: string;
+    annotation?: ElementAnnotation;
+    count?: number;
+    timestamp: number;
+}
+/** Current annotation config version */
+declare const ANNOTATION_CONFIG_VERSION = "1.0.0";
+
+export { ANNOTATION_CONFIG_VERSION as A, type ElementAnnotation as E, type AnnotationConfig as a, type AnnotationCoverage as b, type AnnotationEvent as c, type AnnotationEventType as d };

package/dist/types-UBtp7R0u.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Annotation Types
+ *
+ * Types for the semantic annotation system that allows developers
+ * to attach rich human-authored context to UI elements.
+ */
+/**
+ * Annotation for a single UI element.
+ *
+ * All fields are optional - annotate only what's useful.
+ * Annotations provide human-authored semantic context that enriches
+ * the UI Bridge's understanding of elements beyond what can be
+ * inferred from the DOM alone.
+ *
+ * @example Basic annotation for a button
+ * ```ts
+ * const annotation: ElementAnnotation = {
+ *   description: 'Primary login button',
+ *   purpose: 'Submits the login form and authenticates the user',
+ *   tags: ['auth', 'primary-action'],
+ * };
+ * store.set('login-btn', annotation);
+ * ```
+ *
+ * @example Detailed annotation with relationships and metadata
+ * ```ts
+ * const annotation: ElementAnnotation = {
+ *   description: 'Email input field',
+ *   purpose: 'Collects the user email for authentication',
+ *   notes: 'Validates email format on blur. Shows inline error below the field.',
+ *   tags: ['auth', 'form-input', 'required'],
+ *   relatedElements: ['email-label', 'email-error', 'login-btn'],
+ *   metadata: { validationPattern: '^[^@]+@[^@]+\\.[^@]+$' },
+ *   author: 'design-team',
+ * };
+ * ```
+ */
+interface ElementAnnotation {
+    /** Human-readable description of what this element is */
+    description?: string;
+    /** Why this element exists / what it's for */
+    purpose?: string;
+    /** Behavioral notes, edge cases, or caveats */
+    notes?: string;
+    /** Searchable tags for categorization */
+    tags?: string[];
+    /** IDs of related elements (e.g., a label and its input) */
+    relatedElements?: string[];
+    /** Arbitrary key-value metadata */
+    metadata?: Record<string, unknown>;
+    /** Timestamp of last update (auto-set by store) */
+    updatedAt?: number;
+    /** Author of this annotation */
+    author?: string;
+}
+/**
+ * Annotation configuration file format.
+ *
+ * This is the import/export format - a JSON file with version and annotations map.
+ * Use `AnnotationStore.exportConfig()` to generate this object, and
+ * `AnnotationStore.importConfig()` to load it back.
+ *
+ * @example JSON file format (`annotations.json`)
+ * ```json
+ * {
+ *   "version": "1.0.0",
+ *   "annotations": {
+ *     "login-btn": {
+ *       "description": "Primary login button",
+ *       "purpose": "Submits the login form",
+ *       "tags": ["auth", "primary-action"]
+ *     },
+ *     "email-input": {
+ *       "description": "Email address input",
+ *       "purpose": "Collects user email for authentication",
+ *       "relatedElements": ["email-label", "email-error"]
+ *     }
+ *   },
+ *   "metadata": {
+ *     "appName": "MyApp",
+ *     "description": "Annotations for the login page"
+ *   }
+ * }
+ * ```
+ */
+interface AnnotationConfig {
+    /** Config format version */
+    version: string;
+    /** Map of element ID to annotation */
+    annotations: Record<string, ElementAnnotation>;
+    /** Optional file-level metadata */
+    metadata?: {
+        appName?: string;
+        exportedAt?: number;
+        description?: string;
+    };
+}
+/**
+ * Annotation coverage statistics.
+ */
+interface AnnotationCoverage {
+    /** Total elements known to the system */
+    totalElements: number;
+    /** Elements that have annotations */
+    annotatedElements: number;
+    /** Coverage as a percentage (0-100) */
+    coveragePercent: number;
+    /** IDs of annotated elements */
+    annotatedIds: string[];
+    /** IDs of unannotated elements */
+    unannotatedIds: string[];
+    /** When this coverage was computed */
+    timestamp: number;
+}
+/**
+ * Event types emitted by the annotation store.
+ */
+type AnnotationEventType = 'annotation:set' | 'annotation:deleted' | 'annotation:imported' | 'annotation:cleared';
+/**
+ * Event payload for annotation store events.
+ */
+interface AnnotationEvent {
+    type: AnnotationEventType;
+    elementId?: string;
+    annotation?: ElementAnnotation;
+    count?: number;
+    timestamp: number;
+}
+/** Current annotation config version */
+declare const ANNOTATION_CONFIG_VERSION = "1.0.0";
+
+export { ANNOTATION_CONFIG_VERSION as A, type ElementAnnotation as E, type AnnotationConfig as a, type AnnotationCoverage as b, type AnnotationEvent as c, type AnnotationEventType as d };

package/dist/types-gO696T_t.d.mts

@@ -0,0 +1,236 @@
+import { a1 as UIBridgeConfig, C as CapturedError, a3 as UIState, a4 as UIStateGroup, a5 as UITransition, a0 as TransitionResult, T as PathResult, O as NavigationResult, $ as StateSnapshot } from './types-suaYwWWg.mjs';
+import { d as ControlSnapshot, b as ControlActionRequest, c as ControlActionResponse, C as ComponentActionRequest, a as ComponentActionResponse, F as FindRequest, h as FindResponse, l as WorkflowRunRequest, m as WorkflowRunResponse, i as PageNavigationResponse, P as PageNavigateRequest } from './types-CJGrBEhC.mjs';
+import { a8 as SearchCriteria, a9 as SearchResponse, X as NLActionRequest, Y as NLActionResponse, d as AssertionRequest, e as AssertionResult, B as BatchAssertionRequest, g as BatchAssertionResult, af as SemanticSnapshot, ab as SemanticDiff, ac as SemanticSearchCriteria, ad as SemanticSearchResponse, M as IntentExecutionResult, O as IntentSearchResponse, L as Intent, a4 as RecoveryAttemptRequest, a5 as RecoveryAttemptResult, a0 as PageDataMap, a2 as PageRegionMap, ai as StructuredDataExtraction, i as ComponentInfo, m as CrossAppComparisonReport } from './types-D_ypYl3T.mjs';
+import { RenderLogEntryType, RenderLogEntry } from './render-log/index.mjs';
+import { E as ElementAnnotation, a as AnnotationConfig, b as AnnotationCoverage } from './types-UBtp7R0u.mjs';
+
+/**
+ * UI Bridge Server Types
+ *
+ * Shared types for server adapters.
+ */
+
+/**
+ * Server configuration
+ */
+interface UIBridgeServerConfig extends UIBridgeConfig {
+    /** Base path for API routes */
+    basePath?: string;
+    /** Enable CORS */
+    cors?: boolean | CORSOptions;
+    /** Authentication middleware */
+    authenticate?: (req: unknown) => boolean | Promise<boolean>;
+    /** Rate limiting */
+    rateLimit?: RateLimitOptions;
+}
+/**
+ * CORS options
+ */
+interface CORSOptions {
+    /** Allowed origins */
+    origin?: string | string[] | boolean;
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    headers?: string[];
+    /** Expose headers */
+    exposeHeaders?: string[];
+    /** Allow credentials */
+    credentials?: boolean;
+    /** Max age for preflight cache */
+    maxAge?: number;
+}
+/**
+ * Rate limit options
+ */
+interface RateLimitOptions {
+    /** Time window in milliseconds */
+    windowMs?: number;
+    /** Max requests per window */
+    max?: number;
+    /** Message when rate limited */
+    message?: string;
+}
+/**
+ * API response wrapper
+ */
+interface APIResponse<T = unknown> {
+    /** Whether the request succeeded */
+    success: boolean;
+    /** Response data */
+    data?: T;
+    /** Error message if failed */
+    error?: string;
+    /** Error code */
+    code?: string;
+    /** Request timestamp */
+    timestamp: number;
+}
+/**
+ * Render log query parameters
+ */
+interface RenderLogQuery {
+    /** Filter by entry type */
+    type?: RenderLogEntryType;
+    /** Filter entries since timestamp */
+    since?: number;
+    /** Filter entries until timestamp */
+    until?: number;
+    /** Limit number of results */
+    limit?: number;
+}
+/**
+ * Server handler interface
+ *
+ * Implementations provide these handlers for different frameworks.
+ */
+interface UIBridgeServerHandlers {
+    getRenderLog: (query?: RenderLogQuery) => Promise<APIResponse<RenderLogEntry[]>>;
+    clearRenderLog: () => Promise<APIResponse<void>>;
+    captureSnapshot: () => Promise<APIResponse<unknown>>;
+    getRenderLogPath: () => Promise<APIResponse<{
+        path: string;
+    }>>;
+    getElements: () => Promise<APIResponse<ControlSnapshot['elements']>>;
+    getElement: (id: string) => Promise<APIResponse<ControlSnapshot['elements'][0]>>;
+    getElementState: (id: string) => Promise<APIResponse<unknown>>;
+    executeElementAction: (id: string, request: ControlActionRequest) => Promise<APIResponse<ControlActionResponse>>;
+    getComponents: () => Promise<APIResponse<ControlSnapshot['components']>>;
+    getComponent: (id: string) => Promise<APIResponse<ControlSnapshot['components'][0]>>;
+    getComponentState: (id: string) => Promise<APIResponse<{
+        state: Record<string, unknown>;
+        computed: Record<string, unknown>;
+        timestamp: number;
+    }>>;
+    executeComponentAction: (id: string, request: ComponentActionRequest) => Promise<APIResponse<ComponentActionResponse>>;
+    find: (request?: FindRequest) => Promise<APIResponse<FindResponse>>;
+    /**
+     * @deprecated Use find() instead
+     */
+    discover: (request?: FindRequest) => Promise<APIResponse<FindResponse>>;
+    getControlSnapshot: () => Promise<APIResponse<ControlSnapshot>>;
+    getWorkflows: () => Promise<APIResponse<ControlSnapshot['workflows']>>;
+    runWorkflow: (id: string, request?: WorkflowRunRequest) => Promise<APIResponse<WorkflowRunResponse>>;
+    getWorkflowStatus: (runId: string) => Promise<APIResponse<WorkflowRunResponse>>;
+    getActionHistory: (limit?: number) => Promise<APIResponse<unknown[]>>;
+    getMetrics: () => Promise<APIResponse<unknown>>;
+    highlightElement: (id: string) => Promise<APIResponse<void>>;
+    getElementTree: () => Promise<APIResponse<unknown>>;
+    getConsoleErrors: (params?: {
+        since?: number;
+        limit?: number;
+    }) => Promise<APIResponse<{
+        errors: CapturedError[];
+        count: number;
+    }>>;
+    clearConsoleErrors: () => Promise<APIResponse<{
+        cleared: boolean;
+    }>>;
+    aiSearch: (criteria: SearchCriteria) => Promise<APIResponse<SearchResponse>>;
+    aiExecute: (request: NLActionRequest) => Promise<APIResponse<NLActionResponse>>;
+    aiAssert: (request: AssertionRequest) => Promise<APIResponse<AssertionResult>>;
+    aiAssertBatch: (request: BatchAssertionRequest) => Promise<APIResponse<BatchAssertionResult>>;
+    getSemanticSnapshot: () => Promise<APIResponse<SemanticSnapshot>>;
+    getSemanticDiff: (since?: number) => Promise<APIResponse<SemanticDiff | null>>;
+    getPageSummary: () => Promise<APIResponse<string>>;
+    aiSemanticSearch: (criteria: SemanticSearchCriteria) => Promise<APIResponse<SemanticSearchResponse>>;
+    getStates: () => Promise<APIResponse<UIState[]>>;
+    getState: (id: string) => Promise<APIResponse<UIState>>;
+    getActiveStates: () => Promise<APIResponse<UIState[]>>;
+    activateState: (id: string) => Promise<APIResponse<void>>;
+    deactivateState: (id: string) => Promise<APIResponse<void>>;
+    getStateGroups: () => Promise<APIResponse<UIStateGroup[]>>;
+    activateStateGroup: (id: string) => Promise<APIResponse<void>>;
+    deactivateStateGroup: (id: string) => Promise<APIResponse<void>>;
+    getTransitions: () => Promise<APIResponse<UITransition[]>>;
+    canExecuteTransition: (id: string) => Promise<APIResponse<{
+        canExecute: boolean;
+        reason?: string;
+    }>>;
+    executeTransition: (id: string) => Promise<APIResponse<TransitionResult>>;
+    findPath: (request: {
+        targetStates: string[];
+    }) => Promise<APIResponse<PathResult>>;
+    navigateTo: (request: {
+        targetStates: string[];
+    }) => Promise<APIResponse<NavigationResult>>;
+    getStateSnapshot: () => Promise<APIResponse<StateSnapshot>>;
+    executeIntent: (request: {
+        intentId: string;
+        params?: Record<string, unknown>;
+    }) => Promise<APIResponse<IntentExecutionResult>>;
+    findIntent: (request: {
+        query: string;
+    }) => Promise<APIResponse<IntentSearchResponse>>;
+    listIntents: () => Promise<APIResponse<Intent[]>>;
+    registerIntent: (intent: Intent) => Promise<APIResponse<Intent>>;
+    executeIntentFromQuery: (request: {
+        query: string;
+        params?: Record<string, unknown>;
+    }) => Promise<APIResponse<IntentExecutionResult>>;
+    attemptRecovery: (request: RecoveryAttemptRequest) => Promise<APIResponse<RecoveryAttemptResult>>;
+    analyzePageData: () => Promise<APIResponse<PageDataMap>>;
+    analyzePageRegions: () => Promise<APIResponse<PageRegionMap>>;
+    analyzeStructuredData: () => Promise<APIResponse<StructuredDataExtraction>>;
+    crossAppCompare: (request: {
+        sourceSnapshot: SemanticSnapshot;
+        targetSnapshot: SemanticSnapshot;
+        sourceComponents?: ComponentInfo[];
+        targetComponents?: ComponentInfo[];
+    }) => Promise<APIResponse<CrossAppComparisonReport>>;
+    pageRefresh: () => Promise<APIResponse<PageNavigationResponse>>;
+    pageNavigate: (request: PageNavigateRequest) => Promise<APIResponse<PageNavigationResponse>>;
+    pageGoBack: () => Promise<APIResponse<PageNavigationResponse>>;
+    pageGoForward: () => Promise<APIResponse<PageNavigationResponse>>;
+    getAnnotations: () => Promise<APIResponse<Record<string, ElementAnnotation>>>;
+    getAnnotation: (id: string) => Promise<APIResponse<ElementAnnotation>>;
+    setAnnotation: (id: string, annotation: ElementAnnotation) => Promise<APIResponse<ElementAnnotation>>;
+    deleteAnnotation: (id: string) => Promise<APIResponse<void>>;
+    importAnnotations: (config: AnnotationConfig) => Promise<APIResponse<{
+        count: number;
+    }>>;
+    exportAnnotations: () => Promise<APIResponse<AnnotationConfig>>;
+    getAnnotationCoverage: () => Promise<APIResponse<AnnotationCoverage>>;
+    getPerformanceEntries: () => Promise<APIResponse<unknown>>;
+    clearPerformanceEntries: () => Promise<APIResponse<{
+        cleared: boolean;
+    }>>;
+    getBrowserEvents: (params?: {
+        type?: string;
+        since?: number;
+        limit?: number;
+    }) => Promise<APIResponse<{
+        events: unknown[];
+        count: number;
+    }>>;
+}
+/**
+ * Route definition
+ */
+interface RouteDefinition {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    path: string;
+    handler: string;
+    params?: string[];
+    bodyRequired?: boolean;
+}
+/**
+ * All UI Bridge routes
+ */
+declare const UI_BRIDGE_ROUTES: RouteDefinition[];
+/**
+ * WebSocket message types
+ */
+type WebSocketMessageType = 'subscribe' | 'unsubscribe' | 'event' | 'snapshot' | 'action' | 'error';
+/**
+ * WebSocket message
+ */
+interface WebSocketMessage<T = unknown> {
+    type: WebSocketMessageType;
+    channel?: string;
+    data?: T;
+    error?: string;
+    timestamp: number;
+}
+
+export { type APIResponse as A, type CORSOptions as C, type RateLimitOptions as R, type UIBridgeServerConfig as U, type WebSocketMessage as W, type RenderLogQuery as a, type RouteDefinition as b, type UIBridgeServerHandlers as c, UI_BRIDGE_ROUTES as d, type WebSocketMessageType as e };