@qontinui/ui-bridge-native 0.1.5 → 0.1.6

package/dist/useUIBridge-CDZbWxII.d.ts

@@ -1,571 +0,0 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import React$1 from 'react';
-import { q as NativeUIBridgeFeatures, p as NativeUIBridgeConfig, r as RegisteredNativeElement, R as RegisteredNativeComponent, e as NativeBridgeSnapshot, b as BridgeEventType, a as BridgeEventListener, k as NativeElementType, o as NativeStandardAction, g as NativeCustomAction, j as NativeElementState, i as NativeElementRef, h as NativeElementIdentifier, s as Workflow, N as NativeActionRequest, d as NativeActionResponse, l as NativeFindRequest, m as NativeFindResponse } from './types-BPNuYxDx.js';
-import { a as NativeUIBridgeRegistry } from './registry-B8A_EoxS.js';
-import { N as NativeActionExecutor } from './types-BCYWwyVy.js';
-import { i as NativeUIBridgeServer, m as ServerAdapter, l as RouteProvider } from './http-server-B7KudcYJ.js';
-
-/**
- * Cloud Relay Client — WebSocket tunnel from mobile device to backend
- *
- * Maintains a persistent WebSocket connection to the qontinui.io backend.
- * Receives tunneled HTTP requests from runners, calls the local NativeUIBridgeServer,
- * and sends responses back through the tunnel.
- */
-
-interface CloudRelayConfig {
-    /** WebSocket URL for the device bridge endpoint */
-    relayUrl: string;
-    /** Stable device identifier */
-    deviceId: string;
-    /** Authentication token */
-    authToken: string;
-    /** Reference to the local UI Bridge server for processing requests */
-    uiBridgeServer: NativeUIBridgeServer;
-}
-/**
- * Manages a WebSocket tunnel from the mobile device to the qontinui.io backend.
- *
- * When a runner sends an HTTP request to a cloud device it is serialised as a
- * `TunnelRequest` JSON frame by the backend and forwarded here. This client
- * deserializes it, calls `NativeUIBridgeServer.handleRequest()` directly
- * (avoiding loopback TCP overhead), and sends the `TunnelResponse` back.
- */
-declare class CloudRelayClient {
-    private ws;
-    private config;
-    private reconnectDelay;
-    private maxReconnectDelay;
-    private stopped;
-    private _isConnected;
-    private reconnectTimer;
-    constructor(config: CloudRelayConfig);
-    /** Whether the relay WebSocket is currently connected */
-    get isConnected(): boolean;
-    /** Connect to the relay and start processing tunneled requests. */
-    start(): void;
-    /** Disconnect and stop reconnecting. */
-    stop(): void;
-    private connect;
-    private onMessage;
-    /**
-     * Process a tunneled HTTP request by calling the local NativeUIBridgeServer
-     * directly (no loopback TCP involved).
-     */
-    private handleTunneledRequest;
-    private scheduleReconnect;
-}
-
-/**
- * UI Bridge Native context value
- */
-interface UIBridgeNativeContextValue {
-    /** Feature flags */
-    features: NativeUIBridgeFeatures;
-    /** Configuration */
-    config: NativeUIBridgeConfig;
-    /** Element registry */
-    registry: NativeUIBridgeRegistry;
-    /** Action executor */
-    executor: NativeActionExecutor;
-    /** Get all registered elements */
-    getElements: () => RegisteredNativeElement[];
-    /** Get all registered components */
-    getComponents: () => RegisteredNativeComponent[];
-    /** Create a snapshot */
-    createSnapshot: () => NativeBridgeSnapshot;
-    /** Subscribe to events */
-    on: <T = unknown>(type: BridgeEventType, listener: BridgeEventListener<T>) => () => void;
-    /** Unsubscribe from events */
-    off: <T = unknown>(type: BridgeEventType, listener: BridgeEventListener<T>) => void;
-    /** Whether the provider is initialized */
-    initialized: boolean;
-    /** Server running status */
-    serverRunning: boolean;
-    /** Start the HTTP server */
-    startServer: () => Promise<void>;
-    /** Stop the HTTP server */
-    stopServer: () => void;
-    /** Get the current navigation route (if a RouteProvider is configured) */
-    getCurrentRoute: () => string | null;
-}
-/**
- * UI Bridge Native provider props
- */
-interface UIBridgeNativeProviderProps {
-    /** Child components */
-    children: React$1.ReactNode;
-    /** Feature flags */
-    features?: NativeUIBridgeFeatures;
-    /** Configuration */
-    config?: NativeUIBridgeConfig;
-    /** Event handler */
-    onEvent?: BridgeEventListener;
-    /**
-     * A ServerAdapter instance for the HTTP server.
-     * The app is responsible for creating this using its preferred native TCP/HTTP library.
-     * @see ServerAdapter interface in server/http-server.ts
-     */
-    serverAdapter?: ServerAdapter;
-    /**
-     * Navigation provider for programmatic route navigation via UI Bridge.
-     * Pass Expo Router's push/back functions to enable `control/page/navigate`.
-     */
-    navigationProvider?: {
-        navigate: (url: string) => void;
-        back?: () => void;
-    };
-    /**
-     * Screenshot provider for native screen capture via UI Bridge.
-     * Pass a function that captures the current screen as base64 PNG.
-     */
-    screenshotProvider?: {
-        capture: () => Promise<{
-            base64: string;
-            width: number;
-            height: number;
-        }>;
-    };
-    /**
-     * Route provider for exposing the current navigation route in snapshots.
-     * Wire this to Expo Router's `usePathname()` / `useSegments()` via a module-level ref.
-     */
-    routeProvider?: RouteProvider;
-    /**
-     * Configuration for the cloud relay tunnel (enables remote device verification
-     * when USB/LAN are not available).  Omit `uiBridgeServer` — the provider wires
-     * that automatically after the server starts.
-     */
-    cloudRelayConfig?: Omit<CloudRelayConfig, 'uiBridgeServer'>;
-    /**
-     * Enable mDNS advertisement so that runners on the same LAN can discover this
-     * device automatically (requires react-native-zeroconf).
-     */
-    enableMdnsAnnounce?: boolean;
-    /**
-     * Stable device identifier used for mDNS TXT records and cloud relay
-     * registration.  Typically sourced from expo-device or a UUID stored in
-     * AsyncStorage.
-     */
-    deviceId?: string;
-}
-/**
- * UI Bridge Native Provider
- *
- * Provides UI Bridge Native context to child components.
- *
- * @example
- * ```tsx
- * // app/_layout.tsx
- * import { UIBridgeNativeProvider } from 'ui-bridge-native';
- *
- * export default function RootLayout() {
- *   return (
- *     <UIBridgeNativeProvider
- *       features={{ server: __DEV__, debug: __DEV__ }}
- *       config={{ serverPort: 8087 }}
- *     >
- *       <Stack>{children}</Stack>
- *     </UIBridgeNativeProvider>
- *   );
- * }
- * ```
- */
-declare function UIBridgeNativeProvider({ children, features, config, onEvent, serverAdapter, navigationProvider, screenshotProvider, routeProvider, cloudRelayConfig, enableMdnsAnnounce, deviceId, }: UIBridgeNativeProviderProps): react_jsx_runtime.JSX.Element;
-/**
- * useUIBridgeNative hook
- *
- * Access the UI Bridge Native context. Throws if used outside provider.
- */
-declare function useUIBridgeNative(): UIBridgeNativeContextValue;
-/**
- * useUIBridgeNativeOptional hook
- *
- * Access the UI Bridge Native context, returning null if outside provider.
- */
-declare function useUIBridgeNativeOptional(): UIBridgeNativeContextValue | null;
-/**
- * useUIBridgeNativeRequired hook
- *
- * Alias for useUIBridgeNative (throws if outside provider).
- */
-declare const useUIBridgeNativeRequired: typeof useUIBridgeNative;
-
-/**
- * useUIElement Hook for React Native
- *
- * Register a native element with UI Bridge for control and observation.
- */
-
-/**
- * useUIElement options
- */
-interface UseUIElementOptions {
-    /** Unique identifier for the element */
-    id: string;
-    /** Element type (defaults to 'custom') */
-    type?: NativeElementType;
-    /** Human-readable label */
-    label?: string;
-    /** Override available actions */
-    actions?: NativeStandardAction[];
-    /** Custom actions */
-    customActions?: Record<string, NativeCustomAction>;
-    /** Whether to automatically register on mount */
-    autoRegister?: boolean;
-    /** Callback when state changes */
-    onStateChange?: (state: NativeElementState) => void;
-    /** Parent component path for tree path generation */
-    parentPath?: string;
-    /** RN style prop — will be flattened for design review */
-    style?: unknown;
-    /** State-specific style overrides for design review (pressed, focused, disabled) */
-    stateStyles?: {
-        pressed?: unknown;
-        focused?: unknown;
-        disabled?: unknown;
-    };
-    /**
-     * Handler props to auto-register with the bridge for action execution.
-     * When provided, the bridge can invoke these handlers via press/type/toggle actions
-     * without the component needing a separate useEffect + updateElementProps call.
-     *
-     * @example
-     * ```tsx
-     * const { ref, onLayout, bridgeProps } = useUIElement({
-     *   id: 'my-button',
-     *   type: 'pressable',
-     *   handlers: { onPress: handlePress },
-     * });
-     * ```
-     */
-    handlers?: Record<string, ((...args: any[]) => any) | undefined>;
-}
-/**
- * Bridge props to spread onto the component
- */
-interface UIBridgeProps {
-    /** Test ID for automation */
-    testID: string;
-    /** Accessibility label */
-    accessibilityLabel?: string;
-}
-/**
- * useUIElement return value
- */
-interface UseUIElementReturn {
-    /** Ref to attach to the element */
-    ref: React.RefObject<NativeElementRef>;
-    /** onLayout handler to spread onto the element - uses generic type for RN version compatibility */
-    onLayout: (event: {
-        nativeEvent: {
-            layout: {
-                x: number;
-                y: number;
-                width: number;
-                height: number;
-            };
-        };
-    }) => void;
-    /** Props to spread onto the element for identification */
-    bridgeProps: UIBridgeProps;
-    /** Whether the element is registered */
-    registered: boolean;
-    /** Get current state */
-    getState: () => NativeElementState | null;
-    /** Get element identifier */
-    getIdentifier: () => NativeElementIdentifier | null;
-    /** Trigger an action on this element */
-    trigger: (action: NativeStandardAction | string, params?: Record<string, unknown>) => Promise<void>;
-    /** Manually register the element */
-    register: () => void;
-    /** Manually unregister the element */
-    unregister: () => void;
-    /** The registered element info */
-    registeredElement: RegisteredNativeElement | null;
-    /** Update style for design review (flattens and stores in registry) */
-    updateStyle: (style: unknown, stateStyles?: {
-        pressed?: unknown;
-        focused?: unknown;
-        disabled?: unknown;
-    }) => void;
-}
-/**
- * useUIElement hook for React Native
- *
- * Registers a native element with UI Bridge for programmatic control.
- *
- * @example
- * ```tsx
- * function SubmitButton() {
- *   const { ref, onLayout, bridgeProps, trigger } = useUIElement({
- *     id: 'submit-btn',
- *     type: 'button',
- *     label: 'Submit Form',
- *   });
- *
- *   return (
- *     <Pressable
- *       ref={ref}
- *       onLayout={onLayout}
- *       {...bridgeProps}
- *       onPress={() => handleSubmit()}
- *     >
- *       <Text>Submit</Text>
- *     </Pressable>
- *   );
- * }
- * ```
- */
-declare function useUIElement(options: UseUIElementOptions): UseUIElementReturn;
-/**
- * useUIElementWithProps hook
- *
- * Extended version that also captures component props for action execution.
- * Useful when you need the bridge to be able to call onPress, onChangeText, etc.
- *
- * @example
- * ```tsx
- * function TextInputField({ onChangeText, value }) {
- *   const { ref, onLayout, bridgeProps, captureProps } = useUIElementWithProps({
- *     id: 'email-input',
- *     type: 'input',
- *   });
- *
- *   // Capture props so bridge can call onChangeText
- *   captureProps({ onChangeText, value });
- *
- *   return (
- *     <TextInput
- *       ref={ref}
- *       onLayout={onLayout}
- *       {...bridgeProps}
- *       value={value}
- *       onChangeText={onChangeText}
- *     />
- *   );
- * }
- * ```
- */
-interface UseUIElementWithPropsReturn extends UseUIElementReturn {
-    /** Capture props for action execution */
-    captureProps: (props: Record<string, unknown>) => void;
-}
-declare function useUIElementWithProps(options: UseUIElementOptions): UseUIElementWithPropsReturn;
-
-/**
- * useUIComponent Hook for React Native
- *
- * Register a component with UI Bridge for component-level actions.
- */
-
-/**
- * Action definition for useUIComponent
- */
-interface ComponentActionDef<TParams = unknown, TResult = unknown> {
-    /** Action identifier */
-    id: string;
-    /** Human-readable label */
-    label?: string;
-    /** Description */
-    description?: string;
-    /** Handler function */
-    handler: (params?: TParams) => TResult | Promise<TResult>;
-}
-/**
- * useUIComponent options
- */
-interface UseUIComponentOptions {
-    /** Unique identifier for the component */
-    id: string;
-    /** Human-readable name */
-    name: string;
-    /** Description */
-    description?: string;
-    /** Actions available on this component */
-    actions?: ComponentActionDef[];
-    /** Child element IDs owned by this component */
-    elementIds?: string[];
-    /** Whether to automatically register on mount */
-    autoRegister?: boolean;
-}
-/**
- * useUIComponent return value
- */
-interface UseUIComponentReturn {
-    /** Whether the component is registered */
-    registered: boolean;
-    /** Execute an action on this component */
-    executeAction: <TParams = unknown, TResult = unknown>(actionId: string, params?: TParams) => Promise<TResult>;
-    /** Manually register the component */
-    register: () => void;
-    /** Manually unregister the component */
-    unregister: () => void;
-    /** Update actions dynamically */
-    updateActions: (actions: ComponentActionDef[]) => void;
-    /** Add an element ID to this component */
-    addElement: (elementId: string) => void;
-    /** Remove an element ID from this component */
-    removeElement: (elementId: string) => void;
-    /** The registered component info */
-    registeredComponent: RegisteredNativeComponent | null;
-}
-/**
- * useUIComponent hook for React Native
- *
- * Registers a component with UI Bridge for component-level control.
- * Components can expose high-level actions that may orchestrate multiple element interactions.
- *
- * @example
- * ```tsx
- * function LoginForm() {
- *   const [email, setEmail] = useState('');
- *   const [password, setPassword] = useState('');
- *
- *   useUIComponent({
- *     id: 'login-form',
- *     name: 'Login Form',
- *     actions: [
- *       {
- *         id: 'login',
- *         label: 'Submit Login',
- *         handler: async ({ email, password }) => {
- *           setEmail(email);
- *           setPassword(password);
- *           await submitLogin();
- *         },
- *       },
- *       {
- *         id: 'clear',
- *         label: 'Clear Form',
- *         handler: () => {
- *           setEmail('');
- *           setPassword('');
- *         },
- *       },
- *     ],
- *   });
- *
- *   return (
- *     <View>
- *       <TextInput value={email} onChangeText={setEmail} />
- *       <TextInput value={password} onChangeText={setPassword} secureTextEntry />
- *       <Button title="Login" onPress={handleSubmit} />
- *     </View>
- *   );
- * }
- * ```
- */
-declare function useUIComponent(options: UseUIComponentOptions): UseUIComponentReturn;
-/**
- * useUIComponentAction hook
- *
- * Create a stable action handler that can be used with useUIComponent.
- * Useful for memoizing action handlers.
- */
-declare function useUIComponentAction<TParams = unknown, TResult = unknown>(handler: (params?: TParams) => TResult | Promise<TResult>, deps: React.DependencyList): (params?: TParams) => TResult | Promise<TResult>;
-
-/**
- * useUIBridge Hook for React Native
- *
- * Provides a simplified interface for common UI Bridge operations.
- */
-
-/**
- * Component action request
- */
-interface ComponentActionRequest {
-    /** Action ID */
-    action: string;
-    /** Action parameters */
-    params?: Record<string, unknown>;
-}
-/**
- * Component action response
- */
-interface ComponentActionResponse {
-    /** Whether the action succeeded */
-    success: boolean;
-    /** Result of the action */
-    result?: unknown;
-    /** Error message if failed */
-    error?: string;
-    /** Duration in milliseconds */
-    durationMs: number;
-    /** Timestamp */
-    timestamp: number;
-}
-/**
- * useUIBridge return type
- */
-interface UseUIBridgeReturn {
-    /** Whether UI Bridge is available */
-    available: boolean;
-    /** Whether UI Bridge is initialized */
-    initialized: boolean;
-    /** All registered elements */
-    elements: RegisteredNativeElement[];
-    /** All registered components */
-    components: RegisteredNativeComponent[];
-    /** All registered workflows */
-    workflows: Workflow[];
-    /** Create a snapshot of the current state */
-    createSnapshot: () => NativeBridgeSnapshot;
-    /** Execute an action on an element */
-    executeAction: (elementId: string, request: NativeActionRequest) => Promise<NativeActionResponse>;
-    /** Execute a component action */
-    executeComponentAction: (componentId: string, request: ComponentActionRequest) => Promise<ComponentActionResponse>;
-    /** Find elements */
-    find: (request?: NativeFindRequest) => Promise<NativeFindResponse>;
-    /** Get an element by ID */
-    getElement: (id: string) => RegisteredNativeElement | undefined;
-    /** Get a component by ID */
-    getComponent: (id: string) => RegisteredNativeComponent | undefined;
-    /** Get element state by ID */
-    getElementState: (id: string) => ReturnType<RegisteredNativeElement['getState']> | null;
-    /** Register a workflow */
-    registerWorkflow: (workflow: Workflow) => void;
-    /** Unregister a workflow */
-    unregisterWorkflow: (id: string) => void;
-}
-/**
- * useUIBridge hook
- *
- * Provides a simplified interface for accessing UI Bridge functionality.
- *
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { available, elements, executeAction, find } = useUIBridge();
- *
- *   if (!available) {
- *     return <Text>UI Bridge not available</Text>;
- *   }
- *
- *   const handlePress = async () => {
- *     // Find all buttons
- *     const result = await find({ types: ['button'] });
- *     console.log('Found buttons:', result.elements);
- *
- *     // Execute action on specific element
- *     await executeAction('submit-btn', { action: 'press' });
- *   };
- *
- *   return (
- *     <View>
- *       <Text>Elements: {elements.length}</Text>
- *       <Button title="Press" onPress={handlePress} />
- *     </View>
- *   );
- * }
- * ```
- */
-declare function useUIBridge(): UseUIBridgeReturn;
-/**
- * useUIBridgeRequired hook
- *
- * Same as useUIBridge but throws if not available.
- */
-declare function useUIBridgeRequired(): UseUIBridgeReturn;
-
-export { CloudRelayClient as C, type UIBridgeNativeContextValue as U, type CloudRelayConfig as a, type ComponentActionDef as b, type ComponentActionRequest as c, type ComponentActionResponse as d, UIBridgeNativeProvider as e, type UIBridgeNativeProviderProps as f, type UIBridgeProps as g, type UseUIBridgeReturn as h, type UseUIComponentOptions as i, type UseUIComponentReturn as j, type UseUIElementOptions as k, type UseUIElementReturn as l, type UseUIElementWithPropsReturn as m, useUIBridgeNative as n, useUIBridgeNativeOptional as o, useUIBridgeNativeRequired as p, useUIBridgeRequired as q, useUIComponent as r, useUIComponentAction as s, useUIElement as t, useUIBridge as u, useUIElementWithProps as v };