@qontinui/ui-bridge-native 0.1.4 → 0.1.6

package/dist/react/index.mjs

@@ -1,6 +1,6 @@
 import { createContext, useRef, useState, useCallback, useEffect, useMemo, useContext } from 'react';
+import { StyleSheet, Platform } from 'react-native';
 import { jsx } from 'react/jsx-runtime';
-import { StyleSheet } from 'react-native';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -687,7 +687,7 @@ var DefaultNativeActionExecutor = class {
     if (!params?.text) {
       throw new Error("Type action requires text parameter");
     }
-    if (params.clearFirst) {
+    if (params.clearFirst || params.clear) {
       await this.performClear(element, props);
     }
     if (params.delay && params.delay > 0) {
@@ -1873,6 +1873,15 @@ function createServerHandlers(registry, executor, config) {
         timestamp: Date.now(),
         ...stats
       };
+      if (config?.appInfo) {
+        response.uiBridge = {
+          version: "0.3.0",
+          ...config.appInfo,
+          capabilities: ["elements", "components", "actions", "design"],
+          elementCount: stats.elements,
+          componentCount: stats.components
+        };
+      }
       return success2(response);
     }
   };
@@ -1911,6 +1920,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"] },
@@ -1961,6 +1974,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;
@@ -1977,7 +2071,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,
@@ -2781,6 +2877,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);
@@ -3081,8 +3191,6 @@ var WebSocketEventBridge = class {
     }, this.heartbeatIntervalMs);
   }
 };
-
-// src/transport/DeviceAnnouncer.ts
 var DEFAULT_PORT = 8087;
 var RECONNECT_INITIAL_DELAY_MS = 2e3;
 var RECONNECT_MAX_DELAY_MS = 6e4;
@@ -3103,15 +3211,27 @@ var DeviceAnnouncer = class {
   }
   // ── mDNS ──────────────────────────────────────────────────────────────────
   /**
-   * Start mDNS advertisement using react-native-zeroconf.
+   * Start mDNS advertisement.
+   *
+   * The consumer must pass the `Zeroconf` constructor (from `react-native-zeroconf`)
+   * explicitly; otherwise this is a no-op.
    *
-   * If the package is not installed the call is a no-op and a warning is logged.
+   * Rationale: Metro's `require()` throws an uncatchable module-load error if the
+   * bundle doesn't include the named package. That error escapes async try/catch
+   * boundaries and crashes the app. We avoid it by never calling `require()`
+   * ourselves — the consumer imports the package when they know it's installed.
+   *
+   * @param ZeroconfCtor - constructor from `import Zeroconf from 'react-native-zeroconf'`
    */
-  async startMdnsAdvertise() {
+  async startMdnsAdvertise(ZeroconfCtor) {
+    if (!ZeroconfCtor) {
+      console.log(
+        "[DeviceAnnouncer] mDNS advertisement skipped (no Zeroconf constructor provided). Pass one to enable mDNS."
+      );
+      return;
+    }
     try {
-      const ZeroconfModule = __require("react-native-zeroconf");
-      const Zeroconf = ZeroconfModule.default ?? ZeroconfModule;
-      this.zeroconf = new Zeroconf();
+      this.zeroconf = new ZeroconfCtor();
       const port = this.config.port ?? DEFAULT_PORT;
       const serviceName = `UIBridge-${this.config.deviceId.slice(0, 8)}`;
       this.zeroconf.publishService("_uibridge", "_tcp.", "local.", serviceName, port, {
@@ -3122,10 +3242,8 @@ var DeviceAnnouncer = class {
       });
       this.state = { ...this.state, mdnsActive: true };
       console.log(`[DeviceAnnouncer] mDNS: advertising "${serviceName}" on port ${port}`);
-    } catch (_err) {
-      console.warn(
-        "[DeviceAnnouncer] react-native-zeroconf not available \u2014 mDNS advertisement skipped. Install it with: npx expo install react-native-zeroconf"
-      );
+    } catch (err) {
+      console.warn("[DeviceAnnouncer] mDNS start failed:", err);
     }
   }
   // ── Cloud relay ───────────────────────────────────────────────────────────
@@ -3230,12 +3348,7 @@ function generateHex(bytes) {
   return Array.from(arr).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function getPlatform() {
-  try {
-    const { Platform } = __require("react-native");
-    return Platform.OS ?? "unknown";
-  } catch {
-    return "unknown";
-  }
+  return Platform?.OS ?? "unknown";
 }
 
 // src/transport/CloudRelayClient.ts
@@ -3442,7 +3555,8 @@ function UIBridgeNativeProvider({
     }
     const server = createNativeServer(registry, executor, {
       serverPort: config.serverPort || 8087,
-      cors: true
+      cors: true,
+      appInfo: config.appInfo
     });
     server.setAdapter(serverAdapter);
     if (navigationProvider) {
@@ -3529,7 +3643,8 @@ function UIBridgeNativeProvider({
         try {
           const bareServer = createNativeServer(registry, executor, {
             serverPort: config.serverPort || 8087,
-            cors: true
+            cors: true,
+            appInfo: config.appInfo
           });
           if (navigationProvider) bareServer.setNavigationProvider(navigationProvider);
           if (screenshotProvider) bareServer.setScreenshotProvider(screenshotProvider);