@qontinui/ui-bridge 0.3.0 → 0.3.1

package/dist/react/index.d.mts

@@ -1,12 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { ReactNode } from 'react';
-import { D as UIBridgeFeatures, U as UIBridgeConfig, M as WSConnectionState, x as RegisteredElement, w as RegisteredComponent, l as BridgeSnapshot, k as BridgeEventType, j as BridgeEventListener, a9 as WSSubscriptionOptions, i as BridgeEvent, r as ElementType, S as StandardAction, o as CustomAction, q as ElementState, p as ElementIdentifier, af as Workflow, G as UIStateGroup, F as UIState, z as StateSnapshot, ag as WorkflowStep, T as TransitionResult, H as UITransition, N as NavigationResult, v as PathResult } from '../types-jKVgTI6_.mjs';
-import { U as UIBridgeRegistry } from '../registry-BmZgyCz8.mjs';
+import { a2 as UIBridgeFeatures, a1 as UIBridgeConfig, aa as WSConnectionState, X as RegisteredElement, W as RegisteredComponent, m as BridgeSnapshot, l as BridgeEventType, k as BridgeEventListener, as as WSSubscriptionOptions, j as BridgeEvent, Q as OnBrowserEventCallback, n as BrowserCaptureConfig, F as ElementType, Z as StandardAction, x as CustomAction, z as ElementState, y as ElementIdentifier, az as Workflow, a4 as UIStateGroup, a3 as UIState, $ as StateSnapshot, aA as WorkflowStep, a0 as TransitionResult, a5 as UITransition, O as NavigationResult, T as PathResult, v as ContentRole } from '../types-suaYwWWg.mjs';
+import { U as UIBridgeRegistry } from '../registry-POtcxnal.mjs';
 import { UIBridgeWSClient } from '../core/index.mjs';
 import { RenderLogManager } from '../render-log/index.mjs';
-import { M as MetricsCollector } from '../metrics-DTA2bwG7.mjs';
-import { A as ActionExecutor, i as WorkflowEngine, b as ControlActionRequest, c as ControlActionResponse, C as ComponentActionRequest, a as ComponentActionResponse, F as FindRequest, g as FindResponse, j as WorkflowRunRequest, k as WorkflowRunResponse } from '../types-B7J7noLK.mjs';
-import '../types-B5Q0GVo0.mjs';
+import { M as MetricsCollector } from '../metrics-DuA2qIIz.mjs';
+import { A as ActionExecutor, k as WorkflowEngine, b as ControlActionRequest, c as ControlActionResponse, C as ComponentActionRequest, a as ComponentActionResponse, F as FindRequest, h as FindResponse, l as WorkflowRunRequest, m as WorkflowRunResponse } from '../types-CJGrBEhC.mjs';
+import { E as ElementAnnotation } from '../types-UBtp7R0u.mjs';
+import '../types-D_ypYl3T.mjs';
 
 /**
  * UI Bridge context value
@@ -36,6 +37,8 @@ interface UIBridgeContextValue {
     getComponents: () => RegisteredComponent[];
     /** Create a snapshot */
     createSnapshot: () => BridgeSnapshot;
+    /** Create a snapshot asynchronously (non-blocking) */
+    createSnapshotAsync: (batchSize?: number) => Promise<BridgeSnapshot>;
     /** Subscribe to events */
     on: <T = unknown>(type: BridgeEventType, listener: BridgeEventListener<T>) => () => void;
     /** Unsubscribe from events */
@@ -63,13 +66,17 @@ interface UIBridgeProviderProps {
     config?: UIBridgeConfig;
     /** Event handler */
     onEvent?: BridgeEventListener;
+    /** Callback fired for each captured browser event */
+    onBrowserEvent?: OnBrowserEventCallback;
+    /** Configuration for browser event capture sub-modules */
+    browserCaptureConfig?: BrowserCaptureConfig;
 }
 /**
  * UI Bridge Provider
  *
  * Provides UI Bridge context to child components.
  */
-declare function UIBridgeProvider({ children, features, config, onEvent, }: UIBridgeProviderProps): react_jsx_runtime.JSX.Element;
+declare function UIBridgeProvider({ children, features, config, onEvent, onBrowserEvent, browserCaptureConfig, }: UIBridgeProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * useUIBridgeContext hook
  *
@@ -309,6 +316,8 @@ interface UseUIBridgeReturn {
     workflows: Workflow[];
     /** Create a snapshot of the current state */
     createSnapshot: () => BridgeSnapshot;
+    /** Create a snapshot asynchronously (non-blocking, yields between batches) */
+    createSnapshotAsync: (batchSize?: number) => Promise<BridgeSnapshot>;
     /** Execute an action on an element */
     executeAction: (elementId: string, request: ControlActionRequest) => Promise<ControlActionResponse>;
     /** Execute an action on a component */
@@ -715,6 +724,36 @@ declare function useCanNavigateTo(targetStates: string[]): boolean;
  */
 declare function useNavigationPath(targetStates: string[]): PathResult;
 
+/**
+ * Content Discovery
+ *
+ * Discovers static text content elements (headings, paragraphs, table cells, etc.)
+ * and generates stable IDs and semantic metadata for AI consumption.
+ *
+ * Separate from the interactive element discovery in useAutoRegister.ts —
+ * content elements have no interactive actions and use ContentType instead of ElementType.
+ */
+
+/**
+ * Options for content discovery
+ */
+interface ContentDiscoveryOptions {
+    /** Enable content discovery (default: true) */
+    enabled?: boolean;
+    /** Additional CSS selectors to include */
+    includeContentSelectors?: string[];
+    /** Additional CSS selectors to exclude */
+    excludeContentSelectors?: string[];
+    /** Minimum text length to register (default: 1) */
+    minTextLength?: number;
+    /** Maximum content elements to register (default: 500) */
+    maxContentElements?: number;
+    /** Debounce interval for content registration (default: 250ms) */
+    contentDebounceMs?: number;
+    /** Only register elements with these content roles */
+    contentRoles?: ContentRole[];
+}
+
 /**
  * useAutoRegister Hook
  *
@@ -728,6 +767,7 @@ declare function useNavigationPath(targetStates: string[]): PathResult;
  * - Debounced updates for performance
  * - Respects existing manually registered elements
  */
+
 /**
  * ID generation strategy
  */
@@ -756,6 +796,8 @@ interface AutoRegisterOptions {
     onRegister?: (id: string, element: HTMLElement) => void;
     /** Callback when element is unregistered */
     onUnregister?: (id: string) => void;
+    /** Content discovery options (enabled by default) */
+    contentDiscovery?: ContentDiscoveryOptions;
 }
 /**
  * Hook for automatic element registration
@@ -782,6 +824,8 @@ interface AutoRegisterProviderProps extends Omit<AutoRegisterOptions, 'root'> {
     children: ReactNode;
     /** Use this element as the observation root instead of document.body */
     scopeToChildren?: boolean;
+    /** Content discovery options (enabled by default) */
+    contentDiscovery?: ContentDiscoveryOptions;
 }
 /**
  * Provider component that enables automatic element registration.
@@ -795,6 +839,61 @@ interface AutoRegisterProviderProps extends Omit<AutoRegisterOptions, 'root'> {
  * Place this component at the root of your app (inside UIBridgeProvider)
  * for comprehensive automatic element registration.
  */
-declare function AutoRegisterProvider({ children, scopeToChildren, enabled, idStrategy, debounceMs, includeHidden, includeSelectors, excludeSelectors, generateId, onRegister, onUnregister, }: AutoRegisterProviderProps): react_jsx_runtime.JSX.Element;
+declare function AutoRegisterProvider({ children, scopeToChildren, enabled, idStrategy, debounceMs, includeHidden, includeSelectors, excludeSelectors, generateId, onRegister, onUnregister, contentDiscovery, }: AutoRegisterProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useUIAnnotation Hook
+ *
+ * Registers a semantic annotation for a UI element in the global annotation store.
+ */
+
+/**
+ * Register a semantic annotation for a UI element.
+ *
+ * The annotation is set in the global annotation store and persists
+ * across renders. It is NOT cleaned up on unmount because annotations
+ * represent persistent developer knowledge about elements.
+ *
+ * @param elementId - The UI Bridge element ID to annotate
+ * @param annotation - The annotation data
+ *
+ * @example Basic annotation for a button
+ * ```tsx
+ * function LoginButton() {
+ *   useUIAnnotation('login-btn', {
+ *     description: 'Primary login button',
+ *     purpose: 'Submits the login form',
+ *     tags: ['auth', 'primary-action'],
+ *   });
+ *
+ *   return <button data-ui-id="login-btn">Log In</button>;
+ * }
+ * ```
+ *
+ * @example Annotations enrich the semantic snapshot
+ * ```tsx
+ * // When an element has an annotation, the semantic snapshot includes it.
+ * // Without annotation, the snapshot only has DOM-derived information.
+ * // With annotation, the snapshot gains human-authored context.
+ *
+ * function SearchBar() {
+ *   useUIAnnotation('search-input', {
+ *     description: 'Global search input',
+ *     purpose: 'Searches across all projects and workflows',
+ *     notes: 'Debounces input by 300ms. Supports advanced query syntax.',
+ *     tags: ['search', 'global'],
+ *     relatedElements: ['search-results-panel', 'search-clear-btn'],
+ *   });
+ *
+ *   return <input data-ui-id="search-input" placeholder="Search..." />;
+ * }
+ *
+ * // The annotation data is then available via:
+ * //   GET /annotations/search-input
+ * //   GET /annotations/export (in the full config)
+ * //   store.get('search-input')
+ * ```
+ */
+declare function useUIAnnotation(elementId: string, annotation: ElementAnnotation): void;
 
-export { type AutoRegisterOptions, AutoRegisterProvider, type AutoRegisterProviderProps, type ComponentActionDef, type ComputedPropertyDef, type IdStrategy, type UIBridgeContextValue, UIBridgeProvider, type UIBridgeProviderProps, type UseUIBridgeReturn, type UseUIComponentOptions, type UseUIComponentReturn, type UseUIElementOptions, type UseUIElementReturn, type UseUINavigationReturn, type UseUIStateGroupOptions, type UseUIStateGroupReturn, type UseUIStateOptions, type UseUIStateReturn, type UseUITransitionOptions, type UseUITransitionReturn, useActiveStates, useAutoRegister, useAvailableTransitions, useCanNavigateTo, useNavigationPath, useStateSnapshot, useTransitions, useUIBridge, useUIBridgeContext, useUIBridgeOptional, useUIBridgeRequired, useUIComponent, useUIComponentAction, useUIElement, useUIElementRef, useUINavigation, useUIState, useUIStateGroup, useUITransition };
+export { type AutoRegisterOptions, AutoRegisterProvider, type AutoRegisterProviderProps, type ComponentActionDef, type ComputedPropertyDef, type ContentDiscoveryOptions, type IdStrategy, type UIBridgeContextValue, UIBridgeProvider, type UIBridgeProviderProps, type UseUIBridgeReturn, type UseUIComponentOptions, type UseUIComponentReturn, type UseUIElementOptions, type UseUIElementReturn, type UseUINavigationReturn, type UseUIStateGroupOptions, type UseUIStateGroupReturn, type UseUIStateOptions, type UseUIStateReturn, type UseUITransitionOptions, type UseUITransitionReturn, useActiveStates, useAutoRegister, useAvailableTransitions, useCanNavigateTo, useNavigationPath, useStateSnapshot, useTransitions, useUIAnnotation, useUIBridge, useUIBridgeContext, useUIBridgeOptional, useUIBridgeRequired, useUIComponent, useUIComponentAction, useUIElement, useUIElementRef, useUINavigation, useUIState, useUIStateGroup, useUITransition };

package/dist/react/index.d.ts

@@ -1,12 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { ReactNode } from 'react';
-import { D as UIBridgeFeatures, U as UIBridgeConfig, M as WSConnectionState, x as RegisteredElement, w as RegisteredComponent, l as BridgeSnapshot, k as BridgeEventType, j as BridgeEventListener, a9 as WSSubscriptionOptions, i as BridgeEvent, r as ElementType, S as StandardAction, o as CustomAction, q as ElementState, p as ElementIdentifier, af as Workflow, G as UIStateGroup, F as UIState, z as StateSnapshot, ag as WorkflowStep, T as TransitionResult, H as UITransition, N as NavigationResult, v as PathResult } from '../types-jKVgTI6_.js';
-import { U as UIBridgeRegistry } from '../registry-BKLEm-yk.js';
+import { a2 as UIBridgeFeatures, a1 as UIBridgeConfig, aa as WSConnectionState, X as RegisteredElement, W as RegisteredComponent, m as BridgeSnapshot, l as BridgeEventType, k as BridgeEventListener, as as WSSubscriptionOptions, j as BridgeEvent, Q as OnBrowserEventCallback, n as BrowserCaptureConfig, F as ElementType, Z as StandardAction, x as CustomAction, z as ElementState, y as ElementIdentifier, az as Workflow, a4 as UIStateGroup, a3 as UIState, $ as StateSnapshot, aA as WorkflowStep, a0 as TransitionResult, a5 as UITransition, O as NavigationResult, T as PathResult, v as ContentRole } from '../types-suaYwWWg.js';
+import { U as UIBridgeRegistry } from '../registry-C6dDtn1v.js';
 import { UIBridgeWSClient } from '../core/index.js';
 import { RenderLogManager } from '../render-log/index.js';
-import { M as MetricsCollector } from '../metrics-BfiT_rhZ.js';
-import { A as ActionExecutor, i as WorkflowEngine, b as ControlActionRequest, c as ControlActionResponse, C as ComponentActionRequest, a as ComponentActionResponse, F as FindRequest, g as FindResponse, j as WorkflowRunRequest, k as WorkflowRunResponse } from '../types-BkNRILUa.js';
-import '../types-DfPqwU-i.js';
+import { M as MetricsCollector } from '../metrics-KFAAKNEB.js';
+import { A as ActionExecutor, k as WorkflowEngine, b as ControlActionRequest, c as ControlActionResponse, C as ComponentActionRequest, a as ComponentActionResponse, F as FindRequest, h as FindResponse, l as WorkflowRunRequest, m as WorkflowRunResponse } from '../types-C7gVYRnF.js';
+import { E as ElementAnnotation } from '../types-UBtp7R0u.js';
+import '../types-CebMQj76.js';
 
 /**
  * UI Bridge context value
@@ -36,6 +37,8 @@ interface UIBridgeContextValue {
     getComponents: () => RegisteredComponent[];
     /** Create a snapshot */
     createSnapshot: () => BridgeSnapshot;
+    /** Create a snapshot asynchronously (non-blocking) */
+    createSnapshotAsync: (batchSize?: number) => Promise<BridgeSnapshot>;
     /** Subscribe to events */
     on: <T = unknown>(type: BridgeEventType, listener: BridgeEventListener<T>) => () => void;
     /** Unsubscribe from events */
@@ -63,13 +66,17 @@ interface UIBridgeProviderProps {
     config?: UIBridgeConfig;
     /** Event handler */
     onEvent?: BridgeEventListener;
+    /** Callback fired for each captured browser event */
+    onBrowserEvent?: OnBrowserEventCallback;
+    /** Configuration for browser event capture sub-modules */
+    browserCaptureConfig?: BrowserCaptureConfig;
 }
 /**
  * UI Bridge Provider
  *
  * Provides UI Bridge context to child components.
  */
-declare function UIBridgeProvider({ children, features, config, onEvent, }: UIBridgeProviderProps): react_jsx_runtime.JSX.Element;
+declare function UIBridgeProvider({ children, features, config, onEvent, onBrowserEvent, browserCaptureConfig, }: UIBridgeProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * useUIBridgeContext hook
  *
@@ -309,6 +316,8 @@ interface UseUIBridgeReturn {
     workflows: Workflow[];
     /** Create a snapshot of the current state */
     createSnapshot: () => BridgeSnapshot;
+    /** Create a snapshot asynchronously (non-blocking, yields between batches) */
+    createSnapshotAsync: (batchSize?: number) => Promise<BridgeSnapshot>;
     /** Execute an action on an element */
     executeAction: (elementId: string, request: ControlActionRequest) => Promise<ControlActionResponse>;
     /** Execute an action on a component */
@@ -715,6 +724,36 @@ declare function useCanNavigateTo(targetStates: string[]): boolean;
  */
 declare function useNavigationPath(targetStates: string[]): PathResult;
 
+/**
+ * Content Discovery
+ *
+ * Discovers static text content elements (headings, paragraphs, table cells, etc.)
+ * and generates stable IDs and semantic metadata for AI consumption.
+ *
+ * Separate from the interactive element discovery in useAutoRegister.ts —
+ * content elements have no interactive actions and use ContentType instead of ElementType.
+ */
+
+/**
+ * Options for content discovery
+ */
+interface ContentDiscoveryOptions {
+    /** Enable content discovery (default: true) */
+    enabled?: boolean;
+    /** Additional CSS selectors to include */
+    includeContentSelectors?: string[];
+    /** Additional CSS selectors to exclude */
+    excludeContentSelectors?: string[];
+    /** Minimum text length to register (default: 1) */
+    minTextLength?: number;
+    /** Maximum content elements to register (default: 500) */
+    maxContentElements?: number;
+    /** Debounce interval for content registration (default: 250ms) */
+    contentDebounceMs?: number;
+    /** Only register elements with these content roles */
+    contentRoles?: ContentRole[];
+}
+
 /**
  * useAutoRegister Hook
  *
@@ -728,6 +767,7 @@ declare function useNavigationPath(targetStates: string[]): PathResult;
  * - Debounced updates for performance
  * - Respects existing manually registered elements
  */
+
 /**
  * ID generation strategy
  */
@@ -756,6 +796,8 @@ interface AutoRegisterOptions {
     onRegister?: (id: string, element: HTMLElement) => void;
     /** Callback when element is unregistered */
     onUnregister?: (id: string) => void;
+    /** Content discovery options (enabled by default) */
+    contentDiscovery?: ContentDiscoveryOptions;
 }
 /**
  * Hook for automatic element registration
@@ -782,6 +824,8 @@ interface AutoRegisterProviderProps extends Omit<AutoRegisterOptions, 'root'> {
     children: ReactNode;
     /** Use this element as the observation root instead of document.body */
     scopeToChildren?: boolean;
+    /** Content discovery options (enabled by default) */
+    contentDiscovery?: ContentDiscoveryOptions;
 }
 /**
  * Provider component that enables automatic element registration.
@@ -795,6 +839,61 @@ interface AutoRegisterProviderProps extends Omit<AutoRegisterOptions, 'root'> {
  * Place this component at the root of your app (inside UIBridgeProvider)
  * for comprehensive automatic element registration.
  */
-declare function AutoRegisterProvider({ children, scopeToChildren, enabled, idStrategy, debounceMs, includeHidden, includeSelectors, excludeSelectors, generateId, onRegister, onUnregister, }: AutoRegisterProviderProps): react_jsx_runtime.JSX.Element;
+declare function AutoRegisterProvider({ children, scopeToChildren, enabled, idStrategy, debounceMs, includeHidden, includeSelectors, excludeSelectors, generateId, onRegister, onUnregister, contentDiscovery, }: AutoRegisterProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useUIAnnotation Hook
+ *
+ * Registers a semantic annotation for a UI element in the global annotation store.
+ */
+
+/**
+ * Register a semantic annotation for a UI element.
+ *
+ * The annotation is set in the global annotation store and persists
+ * across renders. It is NOT cleaned up on unmount because annotations
+ * represent persistent developer knowledge about elements.
+ *
+ * @param elementId - The UI Bridge element ID to annotate
+ * @param annotation - The annotation data
+ *
+ * @example Basic annotation for a button
+ * ```tsx
+ * function LoginButton() {
+ *   useUIAnnotation('login-btn', {
+ *     description: 'Primary login button',
+ *     purpose: 'Submits the login form',
+ *     tags: ['auth', 'primary-action'],
+ *   });
+ *
+ *   return <button data-ui-id="login-btn">Log In</button>;
+ * }
+ * ```
+ *
+ * @example Annotations enrich the semantic snapshot
+ * ```tsx
+ * // When an element has an annotation, the semantic snapshot includes it.
+ * // Without annotation, the snapshot only has DOM-derived information.
+ * // With annotation, the snapshot gains human-authored context.
+ *
+ * function SearchBar() {
+ *   useUIAnnotation('search-input', {
+ *     description: 'Global search input',
+ *     purpose: 'Searches across all projects and workflows',
+ *     notes: 'Debounces input by 300ms. Supports advanced query syntax.',
+ *     tags: ['search', 'global'],
+ *     relatedElements: ['search-results-panel', 'search-clear-btn'],
+ *   });
+ *
+ *   return <input data-ui-id="search-input" placeholder="Search..." />;
+ * }
+ *
+ * // The annotation data is then available via:
+ * //   GET /annotations/search-input
+ * //   GET /annotations/export (in the full config)
+ * //   store.get('search-input')
+ * ```
+ */
+declare function useUIAnnotation(elementId: string, annotation: ElementAnnotation): void;
 
-export { type AutoRegisterOptions, AutoRegisterProvider, type AutoRegisterProviderProps, type ComponentActionDef, type ComputedPropertyDef, type IdStrategy, type UIBridgeContextValue, UIBridgeProvider, type UIBridgeProviderProps, type UseUIBridgeReturn, type UseUIComponentOptions, type UseUIComponentReturn, type UseUIElementOptions, type UseUIElementReturn, type UseUINavigationReturn, type UseUIStateGroupOptions, type UseUIStateGroupReturn, type UseUIStateOptions, type UseUIStateReturn, type UseUITransitionOptions, type UseUITransitionReturn, useActiveStates, useAutoRegister, useAvailableTransitions, useCanNavigateTo, useNavigationPath, useStateSnapshot, useTransitions, useUIBridge, useUIBridgeContext, useUIBridgeOptional, useUIBridgeRequired, useUIComponent, useUIComponentAction, useUIElement, useUIElementRef, useUINavigation, useUIState, useUIStateGroup, useUITransition };
+export { type AutoRegisterOptions, AutoRegisterProvider, type AutoRegisterProviderProps, type ComponentActionDef, type ComputedPropertyDef, type ContentDiscoveryOptions, type IdStrategy, type UIBridgeContextValue, UIBridgeProvider, type UIBridgeProviderProps, type UseUIBridgeReturn, type UseUIComponentOptions, type UseUIComponentReturn, type UseUIElementOptions, type UseUIElementReturn, type UseUINavigationReturn, type UseUIStateGroupOptions, type UseUIStateGroupReturn, type UseUIStateOptions, type UseUIStateReturn, type UseUITransitionOptions, type UseUITransitionReturn, useActiveStates, useAutoRegister, useAvailableTransitions, useCanNavigateTo, useNavigationPath, useStateSnapshot, useTransitions, useUIAnnotation, useUIBridge, useUIBridgeContext, useUIBridgeOptional, useUIBridgeRequired, useUIComponent, useUIComponentAction, useUIElement, useUIElementRef, useUINavigation, useUIState, useUIStateGroup, useUITransition };