@qontinui/ui-bridge-native 0.3.2 → 0.5.1

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

@@ -0,0 +1,269 @@
+/**
+ * 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
+ */
+import type { NativeUIBridgeRegistry } from '../core/registry';
+import type { NativeActionExecutor } from '../control/types';
+import type { NativeServerConfig, NavigationProvider, RouteProvider, ScreenshotProvider, KeepAwakeProvider } from './types';
+import type { WebSocketEventBridge } from './ws-event-bridge';
+import type { JsonRpcRequest, JsonRpcResponse } from './ws-types';
+/**
+ * HTTP Request interface (library-agnostic)
+ */
+export interface HTTPRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    query: Record<string, string>;
+    body?: unknown;
+}
+/**
+ * HTTP Response interface (library-agnostic)
+ */
+export interface HTTPResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Request handler type
+ */
+export type RequestHandler = (request: HTTPRequest) => Promise<HTTPResponse>;
+/**
+ * Server adapter interface
+ *
+ * Implement this interface to integrate with your chosen HTTP server library.
+ */
+export 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.
+ */
+export 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
+ */
+export declare class NativeUIBridgeServer {
+    private registry;
+    private executor;
+    private config;
+    private handlers;
+    private adapter?;
+    private running;
+    private keepAwakeProvider?;
+    /**
+     * 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;
+    /**
+     * Observability ring buffers backing `/control/console-errors` and
+     * `/sdk/network-requests`. Allocated unconditionally so the handler can
+     * always read them, but the global patches (`install()`) only fire on
+     * `start()` when `testHooks` is set — production builds don't monkey-patch.
+     */
+    private consoleErrorBuffer;
+    private networkRequestBuffer;
+    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`.
+     *
+     * Also forwards the provider into the registry so the *default*
+     * `getSnapshot` handler (and any other call site of
+     * `registry.createSnapshot`) reads the route too — without this the
+     * cloud-relay/bare-server path returned `currentRoute: null` even when
+     * a `RouteTracker` was wired, because that path never installed the
+     * server-level handler override below.
+     */
+    setRouteProvider(provider: RouteProvider): void;
+    /**
+     * Set a screenshot provider for native screen capture.
+     * This enables `control/screenshot` on native.
+     */
+    setScreenshotProvider(provider: ScreenshotProvider): void;
+    /**
+     * Set a keep-awake provider for native screen-wake control.
+     * This enables `control/keep-awake` and arms the auto-arm hook in
+     * handleRequest (every request keeps the screen alive for 60s).
+     */
+    setKeepAwakeProvider(provider: KeepAwakeProvider): 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
+ */
+export declare function createNativeServer(registry: NativeUIBridgeRegistry, executor: NativeActionExecutor, config?: NativeServerConfig): NativeUIBridgeServer;
+/**
+ * Example adapter using react-native-http-bridge
+ *
+ * To use this adapter:
+ * 1. Install: npm install react-native-http-bridge
+ * 2. Link native modules
+ * 3. Create adapter and pass to server
+ *
+ * ```tsx
+ * import httpBridge from 'react-native-http-bridge';
+ *
+ * const adapter: ServerAdapter = {
+ *   start: async (port, handler) => {
+ *     httpBridge.start(port, 'ui-bridge', async (request) => {
+ *       const response = await handler({
+ *         method: request.type,
+ *         path: request.url,
+ *         headers: request.headers || {},
+ *         query: parseQuery(request.url),
+ *         body: request.postData ? JSON.parse(request.postData) : undefined,
+ *       });
+ *       httpBridge.respond(
+ *         request.requestId,
+ *         response.status,
+ *         response.headers['Content-Type'],
+ *         response.body
+ *       );
+ *     });
+ *   },
+ *   stop: async () => {
+ *     httpBridge.stop();
+ *   },
+ *   isRunning: () => true,
+ * };
+ *
+ * server.setAdapter(adapter);
+ * await server.start();
+ * ```
+ */
+//# sourceMappingURL=http-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../../src/server/http-server.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -1,178 +1,16 @@
-import { C as ConsoleErrorEntry, u as NetworkRequestEntry, k as NativeServerHandlers, e as HandlerContext, A as APIResponse } from '../http-server-C9NaNBEP.js';
-export { v as ConsoleErrorsResponse, D as DismissModalResponse, F as FillFormFieldInput, a as FillFormFieldResult, b as FillFormRequest, c as FillFormResponse, H as HTTPRequest, d as HTTPResponse, f as HandlerFunction, J as JsonRpcBatchRequest, g as JsonRpcBatchResponse, w as JsonRpcClientMessage, h as JsonRpcEvent, i as JsonRpcRequest, j as JsonRpcResponse, x as JsonRpcServerMessage, y as JsonRpcSubscribe, z as JsonRpcUnsubscribe, N as NativeServerConfig, l as NativeUIBridgeServer, m as NavigationProvider, B as NetworkRequestsResponse, P as PushModalRequest, E as PushModalResponse, R as RequestHandler, n as RouteDefinition, o as RouteProvider, S as ScreenshotProvider, p as ServerAdapter, T as TapAtRequest, G as TapAtResponse, U as UI_BRIDGE_NATIVE_ROUTES, W as WebSocketConnection, q as WebSocketEventBridge, r as WebSocketMessageHandler, s as WebSocketServerAdapter, t as createNativeServer, I as isBatchRequest, K as isSubscribe, L as isUnsubscribe } from '../http-server-C9NaNBEP.js';
-import { a as NativeUIBridgeRegistry } from '../registry-pAUpQq2O.js';
-import { N as NativeActionExecutor } from '../types-CjEKTDYT.js';
-import { E as ElementDesignData, S as StateStyles, R as ResponsiveSnapshot } from '../design-types-BHr6Q1FX.js';
-import '../types-CGVut7mc.js';
-
 /**
- * UI Bridge Native — observability ring buffers.
+ * UI Bridge Native - Server
  *
- * Two small last-N buffers backing the `/control/console-errors` and
- * `/sdk/network-requests` endpoints. Each buffer monkey-patches the relevant
- * global on `install()` and restores the original on `uninstall()`, so they
- * can be installed/torn-down with the server's lifecycle.
- *
- * Both buffers are gated behind `features.testHooks` by the caller (see
- * NativeUIBridgeServer). Production builds default to `testHooks: false`,
- * so these patches never run on real users' devices.
- *
- * Implementation notes:
- *   - Buffers default to capacity 100 entries and drop oldest on overflow.
- *   - Patches are idempotent: `install()` is a no-op when already installed;
- *     `uninstall()` is a no-op when not installed.
- *   - Patches only restore the *original* function captured at install time;
- *     if other code wraps `console.error` / `fetch` between install and
- *     uninstall, those wrappers will be lost. Acceptable for test hooks.
- */
-
-declare class ConsoleErrorBuffer {
-    private buffer;
-    private installed;
-    private originalError?;
-    private originalWarn?;
-    constructor(capacity?: number);
-    install(): void;
-    uninstall(): void;
-    entries(opts?: {
-        since?: number;
-        limit?: number;
-    }): ConsoleErrorEntry[];
-    size(): number;
-    clear(): void;
-    isInstalled(): boolean;
-}
-declare class NetworkRequestBuffer {
-    private buffer;
-    private installed;
-    private originalFetch?;
-    private originalXhrOpen?;
-    private originalXhrSend?;
-    constructor(capacity?: number);
-    install(): void;
-    uninstall(): void;
-    entries(opts?: {
-        since?: number;
-        limit?: number;
-    }): NetworkRequestEntry[];
-    size(): number;
-    clear(): void;
-    isInstalled(): boolean;
-}
-
-/**
- * UI Bridge Native Server Handlers
- *
- * Request handlers for the HTTP API endpoints.
- */
-
-/**
- * Create server handlers
- */
-declare function createServerHandlers(registry: NativeUIBridgeRegistry, executor: NativeActionExecutor, config?: {
-    appInfo?: {
-        appId: string;
-        appName: string;
-        appType: string;
-        framework?: string;
-    };
-    /** Optional console-error ring buffer powering `GET /control/console-errors`. */
-    consoleErrorBuffer?: ConsoleErrorBuffer;
-    /** Optional network-request ring buffer powering `GET /sdk/network-requests`. */
-    networkRequestBuffer?: NetworkRequestBuffer;
-}): NativeServerHandlers;
-
-/**
- * Pure-JS RFC 6455 WebSocket protocol implementation.
- *
- * Provides frame encoding/decoding and handshake utilities for running
- * a WebSocket server on react-native-tcp-socket without native crypto deps.
- */
-declare const OPCODE_CONTINUATION = 0;
-declare const OPCODE_TEXT = 1;
-declare const OPCODE_BINARY = 2;
-declare const OPCODE_CLOSE = 8;
-declare const OPCODE_PING = 9;
-declare const OPCODE_PONG = 10;
-interface DecodedFrame {
-    opcode: number;
-    fin: boolean;
-    payload: Uint8Array;
-    masked: boolean;
-}
-interface DecodeResult {
-    frames: DecodedFrame[];
-    remainder: Uint8Array<any>;
-}
-/**
- * Compute the Sec-WebSocket-Accept value from the client's Sec-WebSocket-Key.
- */
-declare function computeAcceptKey(clientKey: string): string;
-/**
- * Build the HTTP 101 Switching Protocols response for a WebSocket upgrade.
- */
-declare function buildUpgradeResponse(clientKey: string): string;
-/** Encode a text message as a WebSocket frame. */
-declare function encodeTextFrame(text: string): Uint8Array;
-/** Encode a PING frame with optional payload. */
-declare function encodePingFrame(payload?: Uint8Array): Uint8Array;
-/** Encode a PONG frame with the payload from the PING. */
-declare function encodePongFrame(payload: Uint8Array): Uint8Array;
-/** Encode a CLOSE frame with optional status code and reason. */
-declare function encodeCloseFrame(code?: number, reason?: string): Uint8Array;
-/**
- * Decode one or more WebSocket frames from a byte buffer.
- * Returns decoded frames and any unconsumed bytes (for partial frames).
- */
-declare function decodeFrames(buffer: Uint8Array): DecodeResult;
-/**
- * Decode a text payload from a Uint8Array.
- */
-declare function decodeTextPayload(payload: Uint8Array): string;
-
-/**
- * UI Bridge Native Design Review Handlers
- *
- * HTTP handlers for the 8 design review endpoints.
- * Maps registered element styles to the web SDK's design data format.
- */
-
-/**
- * Design handler interface (subset of NativeServerHandlers)
- */
-interface NativeDesignHandlers {
-    getElementStyles: (ctx: HandlerContext) => Promise<APIResponse<ElementDesignData>>;
-    getElementStateStyles: (ctx: HandlerContext) => Promise<APIResponse<{
-        elementId: string;
-        stateStyles: StateStyles[];
-    }>>;
-    getDesignSnapshot: (ctx: HandlerContext) => Promise<APIResponse<{
-        elements: ElementDesignData[];
-        timestamp: number;
-    }>>;
-    getResponsiveSnapshots: (ctx: HandlerContext) => Promise<APIResponse<ResponsiveSnapshot[]>>;
-    runDesignAudit: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
-    loadStyleGuide: (ctx: HandlerContext) => Promise<APIResponse<{
-        loaded: boolean;
-    }>>;
-    getStyleGuide: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
-    clearStyleGuide: (ctx: HandlerContext) => Promise<APIResponse<{
-        cleared: boolean;
-    }>>;
-    evaluateQuality: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
-    getQualityContexts: (ctx: HandlerContext) => Promise<APIResponse<Array<{
-        name: string;
-        description: string;
-    }>>>;
-    saveBaseline: (ctx: HandlerContext) => Promise<APIResponse<{
-        saved: boolean;
-        elementCount: number;
-    }>>;
-    diffBaseline: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
-}
-/**
- * Create design review handlers.
- */
-declare function createDesignHandlers(registry: NativeUIBridgeRegistry): NativeDesignHandlers;
-
-export { APIResponse, ConsoleErrorBuffer, ConsoleErrorEntry, type DecodeResult, type DecodedFrame, HandlerContext, type NativeDesignHandlers, NativeServerHandlers, NetworkRequestBuffer, NetworkRequestEntry, OPCODE_BINARY, OPCODE_CLOSE, OPCODE_CONTINUATION, OPCODE_PING, OPCODE_PONG, OPCODE_TEXT, buildUpgradeResponse, computeAcceptKey, createDesignHandlers, createServerHandlers, decodeFrames, decodeTextPayload, encodeCloseFrame, encodePingFrame, encodePongFrame, encodeTextFrame };
+ * HTTP and WebSocket server for external control of native apps.
+ */
+export * from './types';
+export * from './handlers';
+export * from './design-handlers';
+export * from './http-server';
+export * from './ws-protocol';
+export * from './ws-types';
+export { WebSocketConnection } from './ws-connection';
+export type { WebSocketMessageHandler } from './ws-connection';
+export { WebSocketEventBridge } from './ws-event-bridge';
+export { ConsoleErrorBuffer, NetworkRequestBuffer } from './observability';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/server/index.js

@@ -1117,6 +1117,14 @@ function createServerHandlers(registry, executor, config) {
         "NOT_SUPPORTED"
       );
     },
+    // Keep-awake (stub — apps should override via setKeepAwakeProvider, which
+    // the provider wires when a keepAwakeProvider prop is supplied)
+    keepAwake: async () => {
+      return error2(
+        "keep-awake not configured. Provide a keepAwakeProvider to UIBridgeNativeProvider.",
+        "NOT_SUPPORTED"
+      );
+    },
     // Meta / Introspection (stub — server constructor overrides with real route table)
     getMethods: async () => {
       return error2("Methods introspection not configured", "NOT_SUPPORTED");
@@ -1790,6 +1798,12 @@ var WS_ROUTES = [
     httpMethods: ["POST"],
     requiresTestHooks: true
   },
+  {
+    pattern: "control/keep-awake",
+    handler: "keepAwake",
+    httpMethods: ["POST"],
+    requiresTestHooks: true
+  },
   // Observability — last-N console errors + network requests. testHooks-gated
   // because patching `console.error` / `fetch` is invasive in production.
   {
@@ -1842,7 +1856,8 @@ var HANDLER_DESCRIPTIONS = {
   getConsoleErrors: "TEST HOOK \u2014 last-N console.error/console.warn entries; ?since=<ms>&limit=<n>",
   getNetworkRequests: "TEST HOOK \u2014 last-N fetch/XHR entries with status + duration; ?since=<ms>&limit=<n>",
   pushModal: "TEST HOOK \u2014 push a modal onto the snapshot.modalStack via the registry ModalDetector",
-  dismissModal: "TEST HOOK \u2014 dismiss a modal by id from the snapshot.modalStack via the registry ModalDetector"
+  dismissModal: "TEST HOOK \u2014 dismiss a modal by id from the snapshot.modalStack via the registry ModalDetector",
+  keepAwake: "TEST HOOK \u2014 keep the device screen awake via the injected keepAwakeProvider: body { enabled: boolean, durationMs?: number }"
 };
 var ACTION_REFERENCE = [
   { name: "press", aliases: ["click"], params: "PressActionParams (optional position)" },
@@ -2110,6 +2125,35 @@ var NativeUIBridgeServer = class {
       }
     };
   }
+  /**
+   * Set a keep-awake provider for native screen-wake control.
+   * This enables `control/keep-awake` and arms the auto-arm hook in
+   * handleRequest (every request keeps the screen alive for 60s).
+   */
+  setKeepAwakeProvider(provider) {
+    this.keepAwakeProvider = provider;
+    this.handlers.keepAwake = async (ctx) => {
+      const { enabled, durationMs } = ctx.body ?? {};
+      if (typeof enabled !== "boolean") {
+        return {
+          success: false,
+          error: "enabled must be boolean",
+          code: "INVALID_REQUEST",
+          timestamp: Date.now()
+        };
+      }
+      if (enabled) {
+        provider.request("ui-bridge", typeof durationMs === "number" ? durationMs : void 0);
+      } else {
+        provider.release("ui-bridge");
+      }
+      return {
+        success: true,
+        data: { enabled, durationMs: typeof durationMs === "number" ? durationMs : null },
+        timestamp: Date.now()
+      };
+    };
+  }
   /**
    * Start the HTTP server
    */
@@ -2702,6 +2746,12 @@ var NativeUIBridgeServer = class {
     if (request.method === "OPTIONS") {
       return { status: 204, headers, body: "" };
     }
+    if (this.config.testHooks === true && this.keepAwakeProvider) {
+      try {
+        this.keepAwakeProvider.request("auto-arm", 6e4);
+      } catch {
+      }
+    }
     try {
       const response = await this.routeRequest(request);
       return {