@qontinui/ui-bridge-native 0.1.6 → 0.2.1

package/dist/types-BwdPNpII.d.ts

@@ -0,0 +1,525 @@
+/**
+ * UI Bridge Native Core Types
+ *
+ * Defines the fundamental types used throughout the UI Bridge Native framework.
+ * Adapted from ui-bridge for React Native environments.
+ */
+type AnyNativeElement = any;
+interface WaitOptions {
+    /** Wait for element to be visible */
+    visible?: boolean;
+    /** Wait for element to be enabled */
+    enabled?: boolean;
+    /** Wait for element to have focus */
+    focused?: boolean;
+    /** Wait for element state to match */
+    state?: Record<string, unknown>;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Polling interval in milliseconds */
+    interval?: number;
+}
+type ActionHandler<TParams = unknown, TResult = unknown> = (params?: TParams) => TResult | Promise<TResult>;
+interface CustomAction<TParams = unknown, TResult = unknown> {
+    id: string;
+    label?: string;
+    description?: string;
+    handler: ActionHandler<TParams, TResult>;
+}
+interface ComponentAction<TParams = unknown, TResult = unknown> {
+    id: string;
+    label?: string;
+    description?: string;
+    paramSchema?: Record<string, unknown>;
+    handler: ActionHandler<TParams, TResult>;
+}
+type WorkflowStepType = 'element-action' | 'component-action' | 'wait' | 'assert' | 'navigate' | 'branch' | 'loop' | 'extract' | 'log' | 'custom';
+interface WorkflowStep {
+    id: string;
+    type: WorkflowStepType;
+    target?: string;
+    action?: string;
+    params?: Record<string, unknown>;
+    waitOptions?: WaitOptions;
+    handler?: () => unknown | Promise<unknown>;
+}
+interface Workflow {
+    id: string;
+    name: string;
+    description?: string;
+    steps: WorkflowStep[];
+    defaultParams?: Record<string, unknown>;
+}
+type BridgeEventType = 'element:registered' | 'element:unregistered' | 'element:stateChanged' | 'component:registered' | 'component:unregistered' | 'action:started' | 'action:completed' | 'action:failed' | 'workflow:started' | 'workflow:stepCompleted' | 'workflow:completed' | 'workflow:failed' | 'render:snapshot' | 'error';
+interface BridgeEvent<T = unknown> {
+    type: BridgeEventType;
+    timestamp: number;
+    data: T;
+}
+type BridgeEventListener<T = unknown> = (event: BridgeEvent<T>) => void;
+/**
+ * React Native element reference type.
+ * Uses a generic type to avoid conflicts between different react-native versions.
+ */
+type NativeElementRef = AnyNativeElement | null;
+/**
+ * Element identification for React Native (replaces XPath/CSS selectors)
+ */
+interface NativeElementIdentifier {
+    /** Explicit UI Bridge identifier */
+    uiId?: string;
+    /** React Native testID prop */
+    testId?: string;
+    /** Accessibility label */
+    accessibilityLabel?: string;
+    /** Accessibility hint */
+    accessibilityHint?: string;
+    /** Tree path for element (e.g., "App/HomeScreen/Button[0]") */
+    treePath: string;
+    /** Native handle (platform-specific) */
+    nativeHandle?: number;
+}
+/**
+ * Layout information from onLayout callback
+ */
+interface NativeLayout {
+    /** X position relative to parent */
+    x: number;
+    /** Y position relative to parent */
+    y: number;
+    /** Element width */
+    width: number;
+    /** Element height */
+    height: number;
+    /** Absolute X position on screen (from measureInWindow) */
+    pageX: number;
+    /** Absolute Y position on screen (from measureInWindow) */
+    pageY: number;
+}
+/**
+ * Current state of a native UI element
+ */
+interface NativeElementState {
+    /** Whether the element is mounted in the tree */
+    mounted: boolean;
+    /** Whether the element is visible on screen */
+    visible: boolean;
+    /** Whether the element is enabled (not disabled) */
+    enabled: boolean;
+    /** Whether the element has focus */
+    focused: boolean;
+    /** Layout information */
+    layout: NativeLayout | null;
+    /** Current value for text inputs */
+    value?: string;
+    /** Selected state for toggles/checkboxes */
+    selected?: boolean;
+    /** Checked state for checkboxes/radios */
+    checked?: boolean;
+    /** Text content of the element */
+    textContent?: string;
+    /** Additional accessibility state */
+    accessibilityState?: {
+        disabled?: boolean;
+        selected?: boolean;
+        checked?: boolean | 'mixed';
+        busy?: boolean;
+        expanded?: boolean;
+    };
+}
+/**
+ * Types of native UI elements that can be registered
+ */
+type NativeElementType = 'button' | 'input' | 'text' | 'view' | 'scroll' | 'list' | 'listItem' | 'switch' | 'checkbox' | 'radio' | 'image' | 'touchable' | 'pressable' | 'modal' | 'custom';
+/**
+ * Standard actions available on native elements
+ */
+type NativeStandardAction = 'press' | 'click' | 'longPress' | 'doubleTap' | 'type' | 'clear' | 'focus' | 'blur' | 'scroll' | 'swipe' | 'toggle';
+/**
+ * Custom action definition for native elements
+ */
+interface NativeCustomAction<TParams = unknown, TResult = unknown> {
+    /** Action identifier */
+    id: string;
+    /** Human-readable label */
+    label?: string;
+    /** Description of what the action does */
+    description?: string;
+    /** Action handler function */
+    handler: (params?: TParams) => TResult | Promise<TResult>;
+}
+/**
+ * A native UI element registered with the bridge
+ */
+interface RegisteredNativeElement {
+    /** Unique identifier for this element */
+    id: string;
+    /** Reference to the native element */
+    ref: React.RefObject<NativeElementRef>;
+    /** Type of UI element */
+    type: NativeElementType;
+    /** Human-readable label */
+    label?: string;
+    /** Available standard actions for this element */
+    actions: NativeStandardAction[];
+    /** Custom actions specific to this element */
+    customActions?: Record<string, NativeCustomAction>;
+    /** Props passed to the element (for action execution) */
+    props?: Record<string, unknown>;
+    /** Function to get the current state */
+    getState: () => NativeElementState;
+    /** Function to get the element identifier */
+    getIdentifier: () => NativeElementIdentifier;
+    /** Timestamp when the element was registered */
+    registeredAt: number;
+    /** Whether this element is currently mounted */
+    mounted: boolean;
+    /** Route path where this element was registered (for page-scoped filtering) */
+    registrationRoute?: string | null;
+    /** Flattened RN style for design review */
+    flatStyle?: Record<string, unknown>;
+    /** State-specific style overrides (pressed, focused, disabled) */
+    stateStyles?: {
+        pressed?: Record<string, unknown>;
+        focused?: Record<string, unknown>;
+        disabled?: Record<string, unknown>;
+    };
+}
+/**
+ * Component action definition for native components
+ */
+interface NativeComponentAction<TParams = unknown, TResult = unknown> {
+    /** Action identifier */
+    id: string;
+    /** Human-readable label */
+    label?: string;
+    /** Description of what the action does */
+    description?: string;
+    /** Parameter schema (for documentation/validation) */
+    paramSchema?: Record<string, unknown>;
+    /** Action handler function */
+    handler: (params?: TParams) => TResult | Promise<TResult>;
+}
+/**
+ * A native component registered with the bridge (higher-level than elements)
+ */
+interface RegisteredNativeComponent {
+    /** Unique identifier for this component */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the component's purpose */
+    description?: string;
+    /** Available actions on this component */
+    actions: NativeComponentAction[];
+    /** Child element IDs owned by this component */
+    elementIds?: string[];
+    /** Timestamp when the component was registered */
+    registeredAt: number;
+    /** Whether this component is currently mounted */
+    mounted: boolean;
+}
+/**
+ * Action request for native elements
+ */
+interface NativeActionRequest {
+    /** Action to execute */
+    action: NativeStandardAction | string;
+    /** Action parameters */
+    params?: {
+        /** Text to type */
+        text?: string;
+        /** Scroll offset */
+        offset?: {
+            x: number;
+            y: number;
+        };
+        /** Swipe direction */
+        direction?: 'up' | 'down' | 'left' | 'right';
+        /** Duration in milliseconds */
+        duration?: number;
+        /** Additional custom parameters */
+        [key: string]: unknown;
+    };
+    /** Wait options before executing */
+    waitOptions?: WaitOptions;
+}
+/**
+ * Response from a native action execution
+ */
+interface NativeActionResponse {
+    /** Whether the action succeeded */
+    success: boolean;
+    /** Element state after the action */
+    elementState?: NativeElementState;
+    /** Result of the action (for custom actions) */
+    result?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Stack trace if failed */
+    stack?: string;
+    /** Duration of the action in milliseconds */
+    durationMs: number;
+    /** Timestamp when the action completed */
+    timestamp: number;
+    /** Request ID for correlation */
+    requestId?: string;
+    /** Time spent waiting for conditions */
+    waitDurationMs?: number;
+}
+/**
+ * Registration coverage metadata. Lets automation agents detect routes that
+ * have interactive controls but never registered any of them with the bridge,
+ * without having to read source code.
+ *
+ * - `totalRegistered`: number of elements currently in the registry.
+ * - `everHadRegistrations`: sticks `true` once any element is registered, even
+ *   after every element has been unregistered. A route that registered then
+ *   unmounted should NOT be reported as "never wired".
+ * - `byRoute`: count of currently-registered elements grouped by
+ *   `registrationRoute`. Elements registered without a route are bucketed
+ *   under `'?'`, which is itself a useful diagnostic signal.
+ */
+interface NativeRegistrationCoverage {
+    totalRegistered: number;
+    everHadRegistrations: boolean;
+    byRoute: Record<string, number>;
+}
+/**
+ * Snapshot of the entire native UI bridge state
+ */
+interface NativeBridgeSnapshot {
+    /** Timestamp of the snapshot */
+    timestamp: number;
+    /** All registered elements */
+    elements: Array<{
+        id: string;
+        type: NativeElementType;
+        label?: string;
+        identifier: NativeElementIdentifier;
+        state: NativeElementState;
+        actions: NativeStandardAction[];
+        customActions?: string[];
+        /** Handler names actually registered via updateElementProps (e.g. ['onPress', 'onChangeText']) */
+        registeredHandlers?: string[];
+        /** Route path where this element was registered (for page-scoped filtering) */
+        registrationRoute?: string | null;
+    }>;
+    /** All registered components */
+    components: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        actions: string[];
+        elementIds?: string[];
+    }>;
+    /** Available workflows */
+    workflows: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        stepCount: number;
+    }>;
+    /** Current navigation route path (if a RouteProvider is configured) */
+    currentRoute?: string | null;
+    /** Current route segments (if a RouteProvider is configured) */
+    segments?: string[];
+    /** Modal/sheet/drawer context (populated when a modalDetector enricher is registered) */
+    modalStack?: NativeSnapshotModalContext;
+    /** Toast/snackbar context (populated when a toastCapture enricher is registered) */
+    toasts?: NativeSnapshotToastContext;
+    /** Undo/redo context (populated when an undoTracker enricher is registered) */
+    undoRedo?: NativeSnapshotUndoContext;
+    /**
+     * Registration coverage metadata so agents can detect routes that have
+     * interactive controls but did not register them with the bridge.
+     */
+    registration?: NativeRegistrationCoverage;
+}
+/** A single detected modal-like surface (modal, sheet, drawer, popover, alert) */
+interface NativeModalInfo {
+    id: string;
+    title?: string;
+    type: 'modal' | 'sheet' | 'drawer' | 'popover' | 'alertdialog' | 'dialog';
+    /** Whether the modal blocks interaction with the underlying UI */
+    blocking: boolean;
+    /** Whether it can be dismissed by the user (backdrop tap, swipe, esc, etc.) */
+    dismissible: boolean;
+    detectedAt: number;
+}
+/**
+ * Modal context attached to a snapshot. Field names match the web SDK's
+ * `SnapshotModalContext` so external agents can write transport-agnostic checks
+ * like `snapshot.modalStack?.hasBlockingModal`.
+ */
+interface NativeSnapshotModalContext {
+    modals: NativeModalInfo[];
+    topModal?: NativeModalInfo;
+    hasBlockingModal: boolean;
+    count: number;
+}
+/** A captured toast/snackbar */
+interface NativeCapturedToast {
+    id: string;
+    message: string;
+    level: 'info' | 'success' | 'warning' | 'error' | 'loading' | 'unknown';
+    appearedAt: number;
+    dismissedAt?: number;
+    visible: boolean;
+    /** Total duration in ms (lifetime so far if still visible, total if dismissed) */
+    durationMs: number;
+}
+/** Toast context attached to a snapshot */
+interface NativeSnapshotToastContext {
+    /** Toasts currently on screen */
+    active: NativeCapturedToast[];
+    /** Recently-dismissed toasts retained by the capture buffer (most recent first) */
+    recent: NativeCapturedToast[];
+    /** Total number of toasts ever captured by this tracker */
+    totalCaptured: number;
+}
+/**
+ * Undo/redo context attached to a snapshot. Mirrors the web SDK's
+ * `SnapshotUndoContext` minus DOM-only fields — RN has no `document.execCommand`
+ * or selectors, so the native variant relies entirely on developer declaration.
+ */
+interface NativeSnapshotUndoContext {
+    /** Whether undo appears to be available */
+    canUndo: boolean;
+    /** Whether redo appears to be available */
+    canRedo: boolean;
+    /** Description of what undo would reverse */
+    undoDescription?: string;
+    /** Description of what redo would restore */
+    redoDescription?: string;
+    /** Undo stack depth (if known) */
+    undoDepth?: number;
+    /** Redo stack depth (if known) */
+    redoDepth?: number;
+    /** Human-readable summary for AI */
+    summary: string;
+}
+/**
+ * Modal-stack tracker contract. Surfaced in NativeSnapshotEnrichers so the
+ * test-hook HTTP endpoints (`control/modal/push`, `control/modal/dismiss/:id`)
+ * can drive the same instance the snapshot reads from. Any duck-typed
+ * implementation that satisfies this shape can fill the slot — production
+ * uses the `ModalDetector` class.
+ */
+interface NativeModalDetectorLike {
+    getSnapshotModalContext(): NativeSnapshotModalContext;
+    pushModal(modal: {
+        id: string;
+        title?: string;
+        type?: NativeModalInfo['type'];
+        blocking?: boolean;
+        dismissible?: boolean;
+    }): void;
+    dismissModal(id: string): boolean | void;
+    getActive(): NativeModalInfo[];
+}
+/**
+ * Canonical enricher slot. Each tracker exposes a `getSnapshot*Context()` method
+ * that the registry calls during `createSnapshot`. NavigationTracker is intentionally
+ * NOT here — route info already flows through `currentRoute` / `segments`.
+ */
+interface NativeSnapshotEnrichers {
+    modalDetector?: NativeModalDetectorLike;
+    toastCapture?: {
+        getSnapshotToastContext(): NativeSnapshotToastContext;
+    };
+    undoTracker?: {
+        getSnapshotUndoContext(): NativeSnapshotUndoContext;
+    };
+}
+/**
+ * Pluggable snapshot enricher: receives base context and returns extra fields
+ * that get `Object.assign`ed onto the snapshot. Used for ad-hoc/custom trackers
+ * (e.g. runner sidebar tabs) without growing the canonical enricher set.
+ */
+type NativeSnapshotEnricher = (ctx: {
+    elements: RegisteredNativeElement[];
+    currentRoute: string | null;
+}) => Record<string, unknown>;
+/**
+ * UI Bridge Native feature flags
+ */
+interface NativeUIBridgeFeatures {
+    /** Enable HTTP control server */
+    server?: boolean;
+    /** Enable debug tools (inspector overlay) */
+    debug?: boolean;
+    /**
+     * Enable test-only HTTP endpoints that let external runners drive
+     * registry-internal state (currently `control/modal/push` and
+     * `control/modal/dismiss/:id`). Default `false` so production builds
+     * cannot have their modal stack manipulated remotely; set to `true`
+     * (typically gated on `__DEV__`) when running automated tests.
+     */
+    testHooks?: boolean;
+}
+/**
+ * UI Bridge Native configuration
+ */
+interface NativeUIBridgeConfig {
+    /** Port for HTTP server */
+    serverPort?: number;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Path prefix for parent components (for treePath generation) */
+    parentPath?: string;
+    /** Application info for discovery */
+    appInfo?: {
+        appId: string;
+        appName: string;
+        appType: 'web' | 'desktop' | 'mobile' | 'other';
+        framework?: string;
+    };
+}
+/**
+ * Find request for discovering native elements
+ */
+interface NativeFindRequest {
+    /** Filter by element type */
+    types?: NativeElementType[];
+    /** Filter by testID pattern (supports wildcards) */
+    testIdPattern?: string;
+    /** Filter by accessibility label pattern */
+    accessibilityLabelPattern?: string;
+    /** Include only visible elements */
+    visibleOnly?: boolean;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Discovered native element
+ */
+interface DiscoveredNativeElement {
+    /** Element ID */
+    id: string;
+    /** Element type */
+    type: NativeElementType;
+    /** Element identifier */
+    identifier: NativeElementIdentifier;
+    /** Current state */
+    state: NativeElementState;
+    /** Available actions */
+    actions: NativeStandardAction[];
+    /** Label */
+    label?: string;
+}
+/**
+ * Find response
+ */
+interface NativeFindResponse {
+    /** Discovered elements */
+    elements: DiscoveredNativeElement[];
+    /** Total count */
+    total: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Timestamp */
+    timestamp: number;
+}
+
+export type { ActionHandler as A, BridgeEvent as B, ComponentAction as C, DiscoveredNativeElement as D, Workflow as E, WorkflowStep as F, WorkflowStepType as G, NativeModalDetectorLike as H, NativeActionRequest as N, RegisteredNativeComponent as R, WaitOptions as W, BridgeEventListener as a, BridgeEventType as b, CustomAction as c, NativeActionResponse as d, NativeBridgeSnapshot as e, NativeCapturedToast as f, NativeComponentAction as g, NativeCustomAction as h, NativeElementIdentifier as i, NativeElementRef as j, NativeElementState as k, NativeElementType as l, NativeFindRequest as m, NativeFindResponse as n, NativeLayout as o, NativeModalInfo as p, NativeRegistrationCoverage as q, NativeSnapshotEnricher as r, NativeSnapshotEnrichers as s, NativeSnapshotModalContext as t, NativeSnapshotToastContext as u, NativeSnapshotUndoContext as v, NativeStandardAction as w, NativeUIBridgeConfig as x, NativeUIBridgeFeatures as y, RegisteredNativeElement as z };

package/dist/{control/types.d.ts → types-DCEv5qb6.d.ts}

@@ -1,13 +1,15 @@
+import { W as WaitOptions, N as NativeActionRequest, d as NativeActionResponse, m as NativeFindRequest, n as NativeFindResponse, k as NativeElementState } from './types-BwdPNpII.js';
+
 /**
  * UI Bridge Native Control Types
  *
  * Types for action execution and control operations.
  */
-import type { NativeActionRequest, NativeActionResponse, NativeFindRequest, NativeFindResponse, NativeElementState, WaitOptions } from '../core/types';
+
 /**
  * Extended action request with control-specific options
  */
-export interface ControlActionRequest extends NativeActionRequest {
+interface ControlActionRequest extends NativeActionRequest {
     /** Request ID for correlation */
     requestId?: string;
     /** Capture snapshot after action */
@@ -21,7 +23,7 @@ export interface ControlActionRequest extends NativeActionRequest {
 /**
  * Extended action response with control-specific data
  */
-export interface ControlActionResponse extends NativeActionResponse {
+interface ControlActionResponse extends NativeActionResponse {
     /** Request ID for correlation */
     requestId?: string;
     /** Retry count */
@@ -30,7 +32,7 @@ export interface ControlActionResponse extends NativeActionResponse {
 /**
  * Component action request
  */
-export interface ComponentActionRequest {
+interface ComponentActionRequest {
     /** Action to execute */
     action: string;
     /** Action parameters */
@@ -41,7 +43,7 @@ export interface ComponentActionRequest {
 /**
  * Component action response
  */
-export interface ComponentActionResponse {
+interface ComponentActionResponse {
     /** Whether the action succeeded */
     success: boolean;
     /** Result of the action */
@@ -60,7 +62,7 @@ export interface ComponentActionResponse {
 /**
  * Wait result
  */
-export interface WaitResult {
+interface WaitResult {
     /** Whether conditions were met */
     met: boolean;
     /** Time spent waiting in milliseconds */
@@ -70,10 +72,26 @@ export interface WaitResult {
     /** Error message if failed */
     error?: string;
 }
+/**
+ * Action event emitted after executeAction completes (success or failure).
+ */
+interface NativeActionEvent {
+    elementId: string;
+    action: string;
+    params?: unknown;
+    success: boolean;
+    error?: string;
+    /** ms since epoch when the executor finished the action */
+    timestamp: number;
+    /** request id propagated from ControlActionRequest, if any */
+    requestId?: string;
+    durationMs: number;
+}
+type NativeActionListener = (event: NativeActionEvent) => void;
 /**
  * Native action executor interface
  */
-export interface NativeActionExecutor {
+interface NativeActionExecutor {
     /**
      * Execute an action on an element
      */
@@ -90,18 +108,20 @@ export interface NativeActionExecutor {
      * Wait for element conditions
      */
     waitForElement(elementId: string, options: WaitOptions): Promise<WaitResult>;
+    /** Subscribe to action events. Returns an unsubscribe function. */
+    onActionExecuted(listener: NativeActionListener): () => void;
 }
 /**
  * Page navigation request
  */
-export interface PageNavigateRequest {
+interface PageNavigateRequest {
     /** URL to navigate to */
     url: string;
 }
 /**
  * Page navigation response
  */
-export interface PageNavigationResponse {
+interface PageNavigationResponse {
     /** Whether the navigation succeeded */
     success: boolean;
     /** Current URL after navigation */
@@ -112,7 +132,7 @@ export interface PageNavigationResponse {
 /**
  * Action execution options
  */
-export interface ActionExecutionOptions {
+interface ActionExecutionOptions {
     /** Timeout in milliseconds */
     timeout?: number;
     /** Whether to wait for element to be ready */
@@ -123,7 +143,7 @@ export interface ActionExecutionOptions {
 /**
  * Type action params
  */
-export interface TypeActionParams {
+interface TypeActionParams {
     /** Text to type */
     text: string;
     /** Typing delay between characters (ms) */
@@ -136,7 +156,7 @@ export interface TypeActionParams {
 /**
  * Scroll action params
  */
-export interface ScrollActionParams {
+interface ScrollActionParams {
     /** Scroll offset */
     offset?: {
         x: number;
@@ -153,7 +173,7 @@ export interface ScrollActionParams {
 /**
  * Swipe action params
  */
-export interface SwipeActionParams {
+interface SwipeActionParams {
     /** Swipe direction */
     direction: 'up' | 'down' | 'left' | 'right';
     /** Swipe distance (in points) */
@@ -164,7 +184,7 @@ export interface SwipeActionParams {
 /**
  * Press action params
  */
-export interface PressActionParams {
+interface PressActionParams {
     /** Position relative to element */
     position?: {
         x: number;
@@ -173,4 +193,5 @@ export interface PressActionParams {
     /** Press duration (ms) for long press */
     duration?: number;
 }
-//# sourceMappingURL=types.d.ts.map
+
+export type { ActionExecutionOptions as A, ControlActionRequest as C, NativeActionExecutor as N, PressActionParams as P, ScrollActionParams as S, TypeActionParams as T, WaitResult as W, ControlActionResponse as a, ComponentActionRequest as b, ComponentActionResponse as c, SwipeActionParams as d, PageNavigationResponse as e, NativeActionListener as f, NativeActionEvent as g, PageNavigateRequest as h };