@qontinui/ui-bridge-native 0.1.4 → 0.1.6

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

@@ -0,0 +1,247 @@
+/**
+ * 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 } 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;
+    /**
+     * 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
+ */
+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,119 +1,15 @@
-import { h as NativeServerHandlers, b as HandlerContext, A as APIResponse } from '../http-server-B7KudcYJ.js';
-export { H as HTTPRequest, a as HTTPResponse, c as HandlerFunction, J as JsonRpcBatchRequest, d as JsonRpcBatchResponse, r as JsonRpcClientMessage, e as JsonRpcEvent, f as JsonRpcRequest, g as JsonRpcResponse, s as JsonRpcServerMessage, t as JsonRpcSubscribe, u as JsonRpcUnsubscribe, N as NativeServerConfig, i as NativeUIBridgeServer, j as NavigationProvider, R as RequestHandler, k as RouteDefinition, l as RouteProvider, S as ScreenshotProvider, m as ServerAdapter, U as UI_BRIDGE_NATIVE_ROUTES, W as WebSocketConnection, n as WebSocketEventBridge, o as WebSocketMessageHandler, p as WebSocketServerAdapter, q as createNativeServer, v as isBatchRequest, w as isSubscribe, x as isUnsubscribe } from '../http-server-B7KudcYJ.js';
-import { a as NativeUIBridgeRegistry } from '../registry-B8A_EoxS.js';
-import { N as NativeActionExecutor } from '../types-BCYWwyVy.js';
-import { E as ElementDesignData, S as StateStyles, R as ResponsiveSnapshot } from '../design-types-BHr6Q1FX.js';
-import '../types-BPNuYxDx.js';
-
 /**
- * UI Bridge Native Server Handlers
+ * UI Bridge Native - Server
  *
- * 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;
-    };
-}): 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, type DecodeResult, type DecodedFrame, HandlerContext, type NativeDesignHandlers, NativeServerHandlers, 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';
+//# 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"}

package/dist/server/index.js

@@ -1104,6 +1104,10 @@ var WS_ROUTES = [
   { pattern: "health", handler: "health", httpMethods: ["GET"] },
   // Elements
   { pattern: "control/elements", handler: "getElements", httpMethods: ["GET"] },
+  // Flat alias — matches the runner UI Bridge's `/ui-bridge/elements` path so
+  // agents can use the same URL across runner + mobile without remembering
+  // the `control/` prefix. Delegates to the same handler.
+  { pattern: "elements", handler: "getElements", httpMethods: ["GET"] },
   { pattern: "control/element/:id", handler: "getElement", httpMethods: ["GET"] },
   { pattern: "control/element/:id/state", handler: "getElementState", httpMethods: ["GET"] },
   { pattern: "control/element/:id/action", handler: "executeAction", httpMethods: ["POST"] },
@@ -1154,6 +1158,87 @@ var WS_ROUTES = [
   // Meta / Introspection
   { pattern: "meta/methods", handler: "getMethods", httpMethods: ["GET"] }
 ];
+var HANDLER_DESCRIPTIONS = {
+  health: "Liveness probe; returns app metadata + element count",
+  getElements: "Flat list of registered UI elements",
+  getElement: "Single element by id",
+  getElementState: "Dynamic state (value, focused, checked) for one element",
+  executeAction: 'Run an action on an element (see "actions" below for names)',
+  getComponents: "Higher-level components with action schemas",
+  getComponent: "Component detail + per-action paramSchema",
+  executeComponentAction: "Invoke a component action directly (preferred over button clicks)",
+  find: "AI-powered element search by natural-language query",
+  getSnapshot: "Full snapshot: elements + route + state. Supports ?visibleOnly=true and ?currentRouteOnly=true",
+  getWorkflows: "List registered workflows",
+  runWorkflow: "Trigger a workflow by id",
+  pageRefresh: "Reload the current route",
+  pageNavigate: "Imperative router.push(url) \u2014 preferred over tapping tab buttons",
+  pageReplace: "router.replace(url)",
+  pageGoBack: "router.back()",
+  pageGoForward: "router.forward()",
+  getScreenshot: "PNG screenshot of the current screen",
+  getElementStyles: "Computed styles for an element (design review)",
+  getElementStateStyles: "Computed styles per interaction state (hover/focus/disabled)",
+  getDesignSnapshot: "Visual + style snapshot for design review",
+  getResponsiveSnapshots: "Screenshots at multiple viewport widths",
+  runDesignAudit: "Accessibility + visual audit",
+  loadStyleGuide: "Load a design system style guide",
+  getStyleGuide: "Fetch the currently loaded style guide",
+  clearStyleGuide: "Unload the style guide",
+  evaluateQuality: "Score the current UI against a quality context",
+  getQualityContexts: "List available quality evaluation contexts",
+  saveBaseline: "Save a quality baseline snapshot",
+  diffBaseline: "Diff current UI against a saved baseline",
+  getMethods: "List every handler name (legacy introspection)"
+};
+var ACTION_REFERENCE = [
+  { name: "press", aliases: ["click"], params: "PressActionParams (optional position)" },
+  { name: "longPress", params: "PressActionParams (optional position)" },
+  { name: "doubleTap", params: "none" },
+  {
+    name: "type",
+    params: "TypeActionParams { text, delay?, clear? | clearFirst? } \u2014 `clear:true` replaces content atomically"
+  },
+  { name: "clear", params: "none \u2014 empties the input" },
+  { name: "focus", params: "none" },
+  { name: "blur", params: "none" },
+  { name: "scroll", params: "ScrollActionParams { offset? {x,y}, to? }" },
+  { name: "swipe", params: "SwipeActionParams { direction, distance }" },
+  { name: "toggle", params: "none \u2014 flips boolean controls" }
+];
+function buildRoutesPayload() {
+  const entries = [];
+  for (const r of WS_ROUTES) {
+    if (!r.httpMethods) continue;
+    for (const m of r.httpMethods) {
+      entries.push({ method: m, path: `/ui-bridge/${r.pattern}` });
+    }
+  }
+  entries.push({ method: "GET", path: "/ui-bridge/_help" });
+  entries.push({ method: "GET", path: "/ui-bridge/_routes" });
+  entries.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+  return { routes: entries, count: entries.length };
+}
+function buildHelpPayload() {
+  return {
+    version: 1,
+    description: "UI Bridge Native HTTP surface. Prefix every path with /ui-bridge/.",
+    routes: WS_ROUTES.map((r) => ({
+      pattern: r.pattern,
+      httpMethods: r.httpMethods ?? [],
+      wsOnly: !r.httpMethods,
+      handler: r.handler,
+      description: HANDLER_DESCRIPTIONS[r.handler] ?? ""
+    })),
+    actions: ACTION_REFERENCE,
+    tips: [
+      "Start with `GET /ui-bridge/control/snapshot?visibleOnly=true` to see what the user actually sees.",
+      "Prefer `control/component/:id/action/:actionId` over button presses \u2014 typed paramSchema, no button-id guessing.",
+      "Use `pageNavigate` for tab switches instead of pressing tab buttons; gesture state often swallows clicks.",
+      "The `type` action supports `clear:true` to replace existing text atomically in one call."
+    ]
+  };
+}
 var NativeUIBridgeServer = class {
   constructor(registry, executor, config = {}) {
     this.registry = registry;
@@ -1170,7 +1255,9 @@ var NativeUIBridgeServer = class {
       cors: true,
       ...config
     };
-    this.handlers = createServerHandlers(registry, executor);
+    this.handlers = createServerHandlers(registry, executor, {
+      appInfo: this.config.appInfo
+    });
     this.handlers.getMethods = async () => {
       const methods = WS_ROUTES.map((r) => ({
         method: r.pattern,
@@ -1974,6 +2061,20 @@ var NativeUIBridgeServer = class {
       };
     }
     const stripped = path.slice(PREFIX.length);
+    if (method === "GET" && stripped === "_help") {
+      return {
+        success: true,
+        data: buildHelpPayload(),
+        timestamp: Date.now()
+      };
+    }
+    if (method === "GET" && stripped === "_routes") {
+      return {
+        success: true,
+        data: buildRoutesPayload(),
+        timestamp: Date.now()
+      };
+    }
     let patternMatchedButWrongVerb = false;
     for (const route of WS_ROUTES) {
       const pathParams = parsePath(route.pattern, stripped);