@qontinui/ui-bridge-native 0.1.6 → 0.2.0

package/dist/http-server-Dj3grQW4.d.ts

@@ -0,0 +1,622 @@
+import { a as NativeUIBridgeRegistry } from './registry-z-3WJsxp.js';
+import { c as ComponentActionResponse, e as PageNavigationResponse, N as NativeActionExecutor } from './types-ajakyp-l.js';
+import { w as NativeUIBridgeConfig, d as NativeActionResponse, n as NativeFindResponse, e as NativeBridgeSnapshot } from './types-Oz13YLZq.js';
+import { E as ElementDesignData, S as StateStyles, R as ResponsiveSnapshot } from './design-types-BHr6Q1FX.js';
+
+/**
+ * UI Bridge Native Server Types
+ *
+ * Types for the embedded HTTP server.
+ */
+
+/**
+ * Navigation provider for React Native apps.
+ *
+ * Apps supply this to enable programmatic navigation via the UI Bridge
+ * (e.g., `control/page/navigate` and `control/page/back`).
+ * For Expo Router: pass `router.push` and `router.back`.
+ */
+interface NavigationProvider {
+    navigate: (url: string) => void;
+    back?: () => void;
+    /** Replace current route (no back-stack entry). For Expo Router: router.replace */
+    replace?: (url: string) => void;
+    /** Refresh the current route. For Expo Router: router.replace(currentPath) */
+    refresh?: () => void;
+}
+/**
+ * Screenshot provider for React Native apps.
+ *
+ * Apps supply this to enable screen capture via the UI Bridge
+ * (`control/screenshot`). For react-native-view-shot: pass a function
+ * that calls `captureRef` on the root view and returns base64 PNG data.
+ */
+interface ScreenshotProvider {
+    /** Capture the current screen and return base64-encoded PNG data (no data: prefix). */
+    capture: () => Promise<{
+        base64: string;
+        width: number;
+        height: number;
+    }>;
+}
+/**
+ * Route provider for React Native apps.
+ *
+ * Apps supply this to expose the current navigation route in UI Bridge snapshots.
+ * For Expo Router: render a RouteTracker component inside the router context that
+ * calls `usePathname()` / `useSegments()` and writes the result to a module-level ref.
+ */
+interface RouteProvider {
+    /** Return the current route path (e.g. "/(tabs)/runs"), or null if unknown. */
+    getCurrentRoute: () => string | null;
+    /** Return the current route segments (e.g. ["(tabs)", "runs"]), if available. */
+    getSegments?: () => string[];
+    /**
+     * Subscribe to route changes. Required so the UI Bridge can clear stale
+     * layouts on route changes with zero lag.
+     *
+     * Implementers must invoke `listener` synchronously whenever the route
+     * changes, passing the new route (or null if unknown). The returned function
+     * must unsubscribe the listener.
+     *
+     * For Expo Router: wrap your RouteTracker component in a module-level
+     * listener set and call each listener from within the tracker's effect.
+     */
+    subscribe: (listener: (route: string | null) => void) => () => void;
+}
+/**
+ * Server configuration
+ */
+interface NativeServerConfig extends NativeUIBridgeConfig {
+    /** Enable CORS */
+    cors?: boolean;
+    /** Allowed origins for CORS */
+    allowedOrigins?: string[];
+}
+/**
+ * Route definition
+ */
+interface RouteDefinition {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    description: string;
+}
+/**
+ * All UI Bridge Native routes
+ */
+declare const UI_BRIDGE_NATIVE_ROUTES: Record<string, RouteDefinition>;
+/**
+ * API response wrapper
+ */
+interface APIResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    code?: string;
+    timestamp: number;
+}
+/**
+ * Handler context
+ */
+interface HandlerContext {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    body: unknown;
+}
+/**
+ * Handler function type
+ */
+type HandlerFunction<T = unknown> = (context: HandlerContext) => Promise<APIResponse<T>>;
+/**
+ * Server handlers interface
+ */
+interface NativeServerHandlers {
+    getElements: HandlerFunction<{
+        elements: unknown[];
+    }>;
+    getElement: HandlerFunction<{
+        element: unknown;
+    }>;
+    getElementState: HandlerFunction<{
+        state: unknown;
+    }>;
+    executeAction: HandlerFunction<NativeActionResponse>;
+    getComponents: HandlerFunction<{
+        components: unknown[];
+    }>;
+    getComponent: HandlerFunction<{
+        component: unknown;
+    }>;
+    executeComponentAction: HandlerFunction<ComponentActionResponse>;
+    find: HandlerFunction<NativeFindResponse>;
+    getSnapshot: HandlerFunction<NativeBridgeSnapshot>;
+    getWorkflows: HandlerFunction<{
+        workflows: unknown[];
+    }>;
+    runWorkflow: HandlerFunction<{
+        runId: string;
+        status: string;
+        steps: Array<{
+            stepId: string;
+            type: string;
+            status: string;
+            result?: unknown;
+            error?: string;
+            durationMs: number;
+        }>;
+        totalSteps: number;
+        completedSteps: number;
+        failedSteps: number;
+        skippedSteps: number;
+        durationMs: number;
+    }>;
+    pageRefresh: HandlerFunction<PageNavigationResponse>;
+    pageNavigate: HandlerFunction<PageNavigationResponse>;
+    pageReplace: HandlerFunction<PageNavigationResponse>;
+    pageGoBack: HandlerFunction<PageNavigationResponse>;
+    pageGoForward: HandlerFunction<PageNavigationResponse>;
+    getScreenshot: HandlerFunction<{
+        screenshot: string;
+        width: number;
+        height: number;
+    }>;
+    getElementStyles: HandlerFunction<ElementDesignData>;
+    getElementStateStyles: HandlerFunction<{
+        elementId: string;
+        stateStyles: StateStyles[];
+    }>;
+    getDesignSnapshot: HandlerFunction<{
+        elements: ElementDesignData[];
+        timestamp: number;
+    }>;
+    getResponsiveSnapshots: HandlerFunction<ResponsiveSnapshot[]>;
+    runDesignAudit: HandlerFunction<unknown>;
+    loadStyleGuide: HandlerFunction<{
+        loaded: boolean;
+    }>;
+    getStyleGuide: HandlerFunction<unknown>;
+    clearStyleGuide: HandlerFunction<{
+        cleared: boolean;
+    }>;
+    evaluateQuality: HandlerFunction<unknown>;
+    getQualityContexts: HandlerFunction<Array<{
+        name: string;
+        description: string;
+    }>>;
+    saveBaseline: HandlerFunction<{
+        saved: boolean;
+        elementCount: number;
+    }>;
+    diffBaseline: HandlerFunction<unknown>;
+    getMethods: HandlerFunction<{
+        methods: Array<{
+            method: string;
+            httpMethods?: string[];
+            description?: string;
+        }>;
+    }>;
+    health: HandlerFunction<{
+        status: string;
+        timestamp: number;
+    }>;
+}
+
+/**
+ * WebSocket JSON-RPC message types for the UI Bridge protocol.
+ */
+/** Standard JSON-RPC request */
+interface JsonRpcRequest {
+    id: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** Batch request — execute multiple requests concurrently */
+interface JsonRpcBatchRequest {
+    id: number | string;
+    batch: JsonRpcRequest[];
+}
+/** Subscribe to registry events */
+interface JsonRpcSubscribe {
+    id: number | string;
+    method: 'subscribe';
+    params: {
+        events: string[];
+        /** Optional throttle in ms — batch rapid events within this window */
+        throttleMs?: number;
+    };
+}
+/** Unsubscribe from registry events */
+interface JsonRpcUnsubscribe {
+    id: number | string;
+    method: 'unsubscribe';
+    params: {
+        events: string[];
+    };
+}
+/** Any client message */
+type JsonRpcClientMessage = JsonRpcRequest | JsonRpcBatchRequest | JsonRpcSubscribe | JsonRpcUnsubscribe;
+/** Standard JSON-RPC response */
+interface JsonRpcResponse {
+    id: number | string;
+    result?: {
+        success: boolean;
+        data?: unknown;
+        error?: string;
+        code?: string;
+        timestamp?: number;
+    };
+}
+/** Batch response */
+interface JsonRpcBatchResponse {
+    id: number | string;
+    results: JsonRpcResponse[];
+}
+/** Server-pushed event (no id — not a response to a request) */
+interface JsonRpcEvent {
+    event: string;
+    data: unknown;
+    timestamp: number;
+}
+/** Any server message */
+type JsonRpcServerMessage = JsonRpcResponse | JsonRpcBatchResponse | JsonRpcEvent;
+/** Check if a message is a batch request */
+declare function isBatchRequest(msg: unknown): msg is JsonRpcBatchRequest;
+/** Check if a message is a subscribe request */
+declare function isSubscribe(msg: unknown): msg is JsonRpcSubscribe;
+/** Check if a message is an unsubscribe request */
+declare function isUnsubscribe(msg: unknown): msg is JsonRpcUnsubscribe;
+
+/**
+ * WebSocket connection wrapper for the UI Bridge server.
+ *
+ * Manages a single WebSocket connection after the HTTP upgrade handshake,
+ * handling frame-level I/O, heartbeat, and event subscriptions.
+ */
+
+/**
+ * Callback for text messages received from the client.
+ * Returns a response string to send back, or null for no response.
+ */
+type WebSocketMessageHandler = (connId: string, message: string) => Promise<string | null>;
+declare class WebSocketConnection {
+    readonly id: string;
+    readonly subscriptions: Set<string>;
+    /** Heartbeat liveness flag — set false before ping, set true on pong */
+    alive: boolean;
+    private socket;
+    private buffer;
+    private fragmentBuffer;
+    private fragmentOpcode;
+    private closed;
+    private onMessage;
+    private onClose;
+    constructor(id: string, socket: WebSocketConnection['socket'], onMessage: WebSocketMessageHandler, onClose: (connId: string) => void);
+    /** Send a text message to the client. */
+    send(message: string): void;
+    /**
+     * Send an event if the client is subscribed to it. Subscription patterns
+     * may be exact event names, `*` (all), or glob patterns containing `*`
+     * (e.g. `element:*`, `*:stateChanged`). Exact matches and `*` are checked
+     * via fast Set lookups; glob patterns fall through to a regex test.
+     */
+    sendEvent(event: JsonRpcEvent): void;
+    private matchesSubscription;
+    /** Send a ping frame for heartbeat. */
+    ping(): void;
+    /** Close the connection gracefully. */
+    close(code?: number, reason?: string): void;
+    /** Forcefully destroy the connection without a close frame. */
+    destroy(): void;
+    /** Whether the connection is still open. */
+    get isOpen(): boolean;
+    private writeRaw;
+    private handleData;
+    private handleFrame;
+}
+
+/**
+ * Bridges NativeUIBridgeRegistry events to WebSocket clients.
+ *
+ * Subscribes to all registry event types and broadcasts them as
+ * JsonRpcEvent messages to connected WebSocket clients based on
+ * their per-connection subscription sets.
+ */
+
+/** Options for the WebSocketEventBridge constructor. */
+interface WebSocketEventBridgeOptions {
+    /** Heartbeat ping interval in ms (default 30000) */
+    heartbeatIntervalMs?: number;
+    /** Max number of events to retain in the replay history buffer (default 100, 0 disables) */
+    maxHistory?: number;
+}
+declare class WebSocketEventBridge {
+    private connections;
+    private throttles;
+    private unsubscribers;
+    private heartbeatTimer;
+    private registry;
+    private heartbeatIntervalMs;
+    /**
+     * True ring buffer for event replay history.
+     *
+     * `historyBuf` is a fixed-capacity slot array; `historyHead` points at the
+     * NEXT write position; `historyCount` is the number of valid slots
+     * (clamped to capacity). Append is O(1) — no array shifting.
+     */
+    private historyBuf;
+    private historyHead;
+    private historyCount;
+    constructor(registry: NativeUIBridgeRegistry, optionsOrHeartbeatMs?: WebSocketEventBridgeOptions | number);
+    /** Effective ring buffer capacity. 0 means history is disabled. */
+    private get historyCapacity();
+    /**
+     * Start listening to registry events and broadcasting to WS clients.
+     * Also starts the heartbeat timer.
+     */
+    start(): void;
+    /** Stop listening to registry events and clear connections. */
+    stop(): void;
+    /** Register a new WebSocket connection. */
+    addConnection(conn: WebSocketConnection): void;
+    /** Remove a WebSocket connection (called on disconnect). */
+    removeConnection(connId: string): void;
+    /** Get the number of active connections. */
+    get connectionCount(): number;
+    /**
+     * Add event subscriptions for a connection.
+     *
+     * Event names are stored as glob patterns. Supported forms:
+     *   - Exact:  "element:registered"
+     *   - Prefix: "element:*"
+     *   - Suffix: "*:stateChanged"
+     *   - All:    "*"
+     *
+     * @param throttleMs — if >0, batch rapid events within this window before sending
+     */
+    handleSubscribe(connId: string, events: string[], throttleMs?: number): boolean;
+    /**
+     * Remove event subscriptions for a connection.
+     * If all subscriptions are cleared, also drops the throttle entry
+     * (and any pending flush timer) so a subsequent resubscribe starts clean.
+     */
+    handleUnsubscribe(connId: string, events: string[]): boolean;
+    /**
+     * Get the subscription set for a connection.
+     * Returns the original pattern strings (not compiled regexes).
+     */
+    getSubscriptions(connId: string): string[];
+    /**
+     * Check if a connection is subscribed to a specific event.
+     * Matches exact names first (fast path), then tests each stored
+     * pattern as a glob against the event type.
+     */
+    isSubscribed(connId: string, eventType: string): boolean;
+    /** Get the throttle window (in ms) configured for a connection, or undefined if none. */
+    getThrottleMs(connId: string): number | undefined;
+    /**
+     * Get recent events from the replay history buffer.
+     *
+     * @param filter.events — optional list of glob patterns to match event types against
+     * @param filter.since — optional timestamp (ms); only events at or after this time
+     */
+    getHistory(filter?: {
+        events?: string[];
+        since?: number;
+    }): JsonRpcEvent[];
+    /**
+     * Configure the max history buffer size at runtime. 0 disables history.
+     * Reallocates the ring buffer, preserving the most recent
+     * min(historyCount, newCapacity) events in chronological order.
+     */
+    setMaxHistory(maxHistory: number): void;
+    private broadcastEvent;
+    /** Queue an event for throttled delivery, flushing after the throttle window. */
+    private enqueueThrottled;
+    private startHeartbeat;
+}
+
+/**
+ * UI Bridge Native HTTP Server
+ *
+ * Abstract HTTP server implementation for React Native.
+ * This provides a framework-agnostic server interface that can be
+ * implemented using various React Native HTTP server libraries.
+ *
+ * Supported libraries:
+ * - react-native-http-bridge (recommended)
+ * - @aspect/react-native-http-server
+ * - Custom implementations
+ */
+
+/**
+ * HTTP Request interface (library-agnostic)
+ */
+interface HTTPRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * HTTP Response interface (library-agnostic)
+ */
+interface HTTPResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Request handler type
+ */
+type RequestHandler = (request: HTTPRequest) => Promise<HTTPResponse>;
+/**
+ * Server adapter interface
+ *
+ * Implement this interface to integrate with your chosen HTTP server library.
+ */
+interface ServerAdapter {
+    /** Start the server */
+    start(port: number, handler: RequestHandler): Promise<void>;
+    /** Stop the server */
+    stop(): Promise<void>;
+    /** Check if server is running */
+    isRunning(): boolean;
+}
+/**
+ * WebSocket-aware server adapter interface.
+ *
+ * Extends ServerAdapter with callbacks for WebSocket connections.
+ * The adapter manages the raw TCP/WS layer; these callbacks let the
+ * UI Bridge server handle message routing and event broadcasting.
+ */
+interface WebSocketServerAdapter extends ServerAdapter {
+    /** Called when a JSON text frame is received from a WS client. Returns response string or null. */
+    onWebSocketMessage?: (connId: string, message: string) => Promise<string | null>;
+    /** Called when a new WS connection is established after the HTTP 101 upgrade. */
+    onWebSocketConnect?: (connId: string) => void;
+    /** Called when a WS connection is closed or drops. */
+    onWebSocketDisconnect?: (connId: string) => void;
+    /** Send a message to a specific WS connection by ID. */
+    sendToConnection?: (connId: string, message: string) => void;
+    /** Send a message to all connected WS clients. */
+    broadcast?: (message: string) => void;
+}
+/**
+ * Native UI Bridge HTTP Server
+ */
+declare class NativeUIBridgeServer {
+    private registry;
+    private executor;
+    private config;
+    private handlers;
+    private adapter?;
+    private running;
+    /**
+     * Per-connection cleanup thunks for in-flight waiters (waitForElement,
+     * waitForCondition, ...). Aborted when a client disconnects so the
+     * underlying timers/listeners don't leak.
+     */
+    private pendingWaiters;
+    constructor(registry: NativeUIBridgeRegistry, executor: NativeActionExecutor, config?: NativeServerConfig);
+    /**
+     * Set the server adapter
+     */
+    setAdapter(adapter: ServerAdapter): void;
+    /**
+     * Set a navigation provider for programmatic route navigation.
+     * This enables `control/page/navigate` and `control/page/back` on native.
+     */
+    setNavigationProvider(provider: NavigationProvider): void;
+    /**
+     * Set a route provider for reporting the current navigation route.
+     * When set, `control/snapshot` responses include `currentRoute` and `segments`.
+     */
+    setRouteProvider(provider: RouteProvider): void;
+    /**
+     * Set a screenshot provider for native screen capture.
+     * This enables `control/screenshot` on native.
+     */
+    setScreenshotProvider(provider: ScreenshotProvider): void;
+    /**
+     * Start the HTTP server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the HTTP server
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if server is running
+     */
+    isRunning(): boolean;
+    private eventBridge?;
+    /**
+     * Set the event bridge for WebSocket event broadcasting and subscriptions.
+     */
+    setEventBridge(bridge: WebSocketEventBridge): void;
+    /**
+     * Handle a JSON-RPC message from a WebSocket client.
+     * Parses the message, routes to the appropriate handler, and returns
+     * a JSON string response (or null for events that need no response).
+     */
+    handleWebSocketMessage(connId: string, rawMessage: string): Promise<string | null>;
+    /**
+     * Execute a batch of JSON-RPC requests concurrently.
+     */
+    handleBatchRequest(batch: JsonRpcRequest[]): Promise<JsonRpcResponse[]>;
+    /**
+     * Register an in-flight waiter's cleanup thunk under the given connection.
+     * Returns an `unregister` thunk that the natural-resolution path should
+     * call so the cleanup isn't re-invoked on disconnect.
+     */
+    private registerWaiter;
+    /**
+     * Abort all pending waiters associated with a connection. Called by the
+     * provider's WS disconnect handler so timers/listeners don't leak after
+     * the client goes away.
+     */
+    abortWaitersForConnection(connId: string): void;
+    /**
+     * Wait for an element to be registered, or resolve immediately if it already exists.
+     * Returns a JsonRpcResponse JSON string.
+     */
+    private handleWaitForElement;
+    /**
+     * Wait for an arbitrary element-state predicate to become true.
+     *
+     * Supported `condition` shapes:
+     *   {field: "mounted"|"visible"|"enabled"|"focused", equals: boolean}
+     *   {field: "layout", exists: true}
+     *   {field: string, equals: unknown}  // generic: state[field] === equals
+     *
+     * Resolves immediately with `waited:false` if the predicate already
+     * holds. Otherwise subscribes to `element:registered` and
+     * `element:stateChanged` until the predicate matches or timeout fires.
+     */
+    private handleWaitForCondition;
+    /**
+     * Execute a sequence of JSON-RPC steps in order, stopping on first failure.
+     * Returns a JsonRpcResponse JSON string with per-step results.
+     */
+    private handleSequence;
+    /**
+     * Route a JSON-RPC method string to the appropriate handler using path-style matching.
+     *
+     * Method strings mirror HTTP routes but without the /ui-bridge/ prefix.
+     * Path params are extracted from :name placeholders in the route pattern.
+     *
+     * Examples:
+     *   "health"                                           → handlers.health
+     *   "control/snapshot"                                 → handlers.getSnapshot
+     *   "control/element/tab-runs/action"                  → handlers.executeAction ({id:'tab-runs'})
+     *   "control/component/my-comp/action/submit"          → handlers.executeComponentAction
+     */
+    private routeMethodToHandler;
+    /**
+     * Handle incoming HTTP request
+     *
+     * Exposed as public so that CloudRelayClient can call it directly (without
+     * loopback TCP overhead) when processing tunneled requests.
+     */
+    handleRequest(request: HTTPRequest): Promise<HTTPResponse>;
+    /**
+     * Route an HTTP request to the appropriate handler using WS_ROUTES.
+     *
+     * Strips the `/ui-bridge/` prefix from the path, then iterates the shared
+     * WS_ROUTES table. Each route's `pattern` is matched against the stripped
+     * path via the module-level `parsePath` helper; path params are merged
+     * with the request body into a HandlerContext.
+     *
+     * `httpMethods` disambiguates routes that share a pattern but differ
+     * by verb (e.g. GET vs DELETE on `design/style-guide`). A route without
+     * `httpMethods` is WS-only and will not be matched on HTTP.
+     */
+    private routeRequest;
+}
+/**
+ * Create a UI Bridge Native server
+ */
+declare function createNativeServer(registry: NativeUIBridgeRegistry, executor: NativeActionExecutor, config?: NativeServerConfig): NativeUIBridgeServer;
+
+export { type APIResponse as A, type HTTPRequest as H, type JsonRpcBatchRequest as J, type NativeServerConfig as N, type RequestHandler as R, type ScreenshotProvider as S, UI_BRIDGE_NATIVE_ROUTES as U, WebSocketConnection as W, type HTTPResponse as a, type HandlerContext as b, type HandlerFunction as c, type JsonRpcBatchResponse as d, type JsonRpcEvent as e, type JsonRpcRequest as f, type JsonRpcResponse as g, type NativeServerHandlers as h, NativeUIBridgeServer as i, type NavigationProvider as j, type RouteDefinition as k, type RouteProvider as l, type ServerAdapter as m, WebSocketEventBridge as n, type WebSocketMessageHandler as o, type WebSocketServerAdapter as p, createNativeServer as q, type JsonRpcClientMessage as r, type JsonRpcServerMessage as s, type JsonRpcSubscribe as t, type JsonRpcUnsubscribe as u, isBatchRequest as v, isSubscribe as w, isUnsubscribe as x };