@qontinui/ui-bridge-native 0.2.0 → 0.2.1

package/dist/server/index.mjs

@@ -133,6 +133,25 @@ var UI_BRIDGE_NATIVE_ROUTES = {
     path: "/ui-bridge/design/style-guide",
     description: "Clear loaded style guide"
   },
+  // AI helpers
+  AI_FILL_FORM: {
+    method: "POST",
+    path: "/ui-bridge/ai/fill-form",
+    description: "Fill multiple input elements in a single call"
+  },
+  // Test hooks — drive ModalDetector state from outside the React tree
+  // (gated by `features.testHooks`). Mirrors `pushModal` / `dismissModal`
+  // calls that components normally make in-process.
+  PUSH_MODAL: {
+    method: "POST",
+    path: "/ui-bridge/control/modal/push",
+    description: "Push a modal onto the modal stack (testHooks)"
+  },
+  DISMISS_MODAL: {
+    method: "POST",
+    path: "/ui-bridge/control/modal/dismiss/:id",
+    description: "Dismiss a modal by id (testHooks)"
+  },
   // Health
   HEALTH: {
     method: "GET",
@@ -935,6 +954,20 @@ function createServerHandlers(registry, executor, config) {
       return success2(response);
     },
     // Discovery
+    //
+    // Native parity with the runner's `POST /ui-bridge/ai/find`. The runner
+    // matches a free-text `query` against label > text > value > aria-label >
+    // placeholder > name. We replicate that here against the native registry's
+    // analogues:
+    //   1. `label` (the registered display label)
+    //   2. identifier fields: `testId`, `accessibilityLabel`, `treePath`, `uiId`
+    //   3. registered handler names (e.g. `onPress`, `onChangeText`)
+    //
+    // Match is case-insensitive substring. Empty/missing query falls back to
+    // the structured filters (types/visibleOnly/etc.) so callers that don't
+    // pass `query` still get the legacy behaviour. Once we've narrowed by
+    // query the response is shaped through the executor's NativeFindResponse
+    // envelope so the wire format stays stable.
     find: async (ctx) => {
       const body = ctx.body;
       const response = await executor.find({
@@ -942,9 +975,49 @@ function createServerHandlers(registry, executor, config) {
         testIdPattern: body?.testIdPattern,
         accessibilityLabelPattern: body?.accessibilityLabelPattern,
         visibleOnly: body?.visibleOnly,
-        limit: body?.limit
+        // When `query` is supplied we apply our own limit *after* ranking so
+        // the highest-priority matches survive the cap; defer slicing to us
+        // by widening here.
+        limit: body?.query && body.query.length > 0 ? void 0 : body?.limit
+      });
+      const rawQuery = typeof body?.query === "string" ? body.query.trim() : "";
+      if (rawQuery.length === 0) {
+        return success2(response);
+      }
+      const needle = rawQuery.toLowerCase();
+      const containsNeedle = (value) => typeof value === "string" && value.toLowerCase().includes(needle);
+      const scored = [];
+      for (const el of response.elements) {
+        let priorityRank = Number.POSITIVE_INFINITY;
+        if (containsNeedle(el.label)) {
+          priorityRank = Math.min(priorityRank, 0);
+        }
+        const ident = el.identifier;
+        if (ident) {
+          if (containsNeedle(ident.testId)) priorityRank = Math.min(priorityRank, 1);
+          if (containsNeedle(ident.accessibilityLabel)) priorityRank = Math.min(priorityRank, 1);
+          if (containsNeedle(ident.treePath)) priorityRank = Math.min(priorityRank, 1);
+          if (containsNeedle(ident.uiId)) priorityRank = Math.min(priorityRank, 1);
+        }
+        if (priorityRank === Number.POSITIVE_INFINITY) {
+          const registered = registry.getElement(el.id);
+          const handlers = extractHandlerNames(registered?.props);
+          if (handlers.some((h) => h.toLowerCase().includes(needle))) {
+            priorityRank = 2;
+          }
+        }
+        if (priorityRank !== Number.POSITIVE_INFINITY) {
+          scored.push({ priorityRank, element: el });
+        }
+      }
+      scored.sort((a, b) => a.priorityRank - b.priorityRank);
+      const limit = body?.limit && body.limit > 0 ? body.limit : void 0;
+      const filtered = limit ? scored.slice(0, limit) : scored;
+      return success2({
+        ...response,
+        elements: filtered.map((s) => s.element),
+        total: filtered.length
       });
-      return success2(response);
     },
     getSnapshot: async (ctx) => {
       const visibleOnly = ctx.query?.visibleOnly === "true" || ctx.body?.visibleOnly === true;
@@ -1045,15 +1118,162 @@ function createServerHandlers(registry, executor, config) {
     getMethods: async () => {
       return error2("Methods introspection not configured", "NOT_SUPPORTED");
     },
+    // AI helpers
+    //
+    // Mobile-side parity with the runner's `POST /ui-bridge/ai/fill-form`.
+    // Each entry in `fields` is dispatched through the existing executor as a
+    // `type` action with `clear: true` so the input value is replaced
+    // atomically (the closest native equivalent to the web bridge's
+    // "setValue" semantics — there is no `setValue` action on native).
+    //
+    // Failures do not short-circuit: every field is attempted, and the
+    // response carries per-field success/error plus aggregate counts.
+    fillForm: async (ctx) => {
+      const body = ctx.body;
+      const rawFields = body?.fields;
+      if (!Array.isArray(rawFields)) {
+        return error2('Request body must include "fields" array', "INVALID_REQUEST");
+      }
+      const results = [];
+      for (let i = 0; i < rawFields.length; i++) {
+        const field = rawFields[i];
+        if (!field || typeof field !== "object") {
+          results.push({
+            elementId: "",
+            success: false,
+            error: `fields[${i}] must be an object with "elementId" and "value"`
+          });
+          continue;
+        }
+        const { elementId, value } = field;
+        if (typeof elementId !== "string" || elementId.length === 0) {
+          results.push({
+            elementId: typeof elementId === "string" ? elementId : "",
+            success: false,
+            error: `fields[${i}] is missing a non-empty "elementId"`
+          });
+          continue;
+        }
+        if (typeof value !== "string") {
+          results.push({
+            elementId,
+            success: false,
+            error: `fields[${i}] is missing a string "value"`
+          });
+          continue;
+        }
+        try {
+          const response = await executor.executeAction(elementId, {
+            action: "type",
+            params: { text: value, clear: true }
+          });
+          if (response.success) {
+            results.push({ elementId, success: true });
+          } else {
+            results.push({
+              elementId,
+              success: false,
+              error: response.error ?? "Action failed"
+            });
+          }
+        } catch (err) {
+          results.push({
+            elementId,
+            success: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+      const succeededCount = results.filter((r) => r.success).length;
+      const failedCount = results.length - succeededCount;
+      return success2({ results, succeededCount, failedCount });
+    },
+    // Test hooks — modal stack manipulation
+    //
+    // These two endpoints exist so external automation runners can drive
+    // ModalDetector state via HTTP, mirroring the in-tree `pushModal` /
+    // `dismissModal` calls that components normally make. They're gated by
+    // `features.testHooks` at the route layer (see http-server.ts); the
+    // handlers themselves still defend against a missing modalDetector
+    // because the bare server path used by CloudRelayClient may run before
+    // enrichers are wired.
+    pushModal: async (ctx) => {
+      const detector = registry.getEnrichers().modalDetector;
+      if (!detector) {
+        return error2(
+          "modal detector not registered",
+          "ENRICHER_UNAVAILABLE"
+        );
+      }
+      const body = ctx.body;
+      const id = body?.id;
+      if (typeof id !== "string" || id.length === 0) {
+        return error2(
+          'pushModal requires a non-empty "id"',
+          "INVALID_REQUEST"
+        );
+      }
+      const allowedTypes = ["modal", "sheet", "drawer", "popover", "alertdialog", "dialog"];
+      const requestedType = body?.type;
+      if (requestedType !== void 0 && (typeof requestedType !== "string" || !allowedTypes.includes(requestedType))) {
+        return error2(
+          `pushModal "type" must be one of: ${allowedTypes.join(", ")}`,
+          "INVALID_REQUEST"
+        );
+      }
+      detector.pushModal({
+        id,
+        title: body?.title,
+        // requestedType is narrowed by the allowedTypes guard above; the cast
+        // converts the validated string to the NativeModalInfo['type'] union.
+        type: requestedType,
+        blocking: body?.blocking,
+        dismissible: body?.dismissible
+      });
+      const stored = detector.getActive().find((m) => m.id === id);
+      return success2({
+        pushed: true,
+        id,
+        title: stored?.title,
+        type: stored?.type,
+        blocking: stored?.blocking,
+        dismissible: stored?.dismissible,
+        pushedAt: stored?.detectedAt ?? Date.now()
+      });
+    },
+    dismissModal: async (ctx) => {
+      const detector = registry.getEnrichers().modalDetector;
+      if (!detector) {
+        return error2(
+          "modal detector not registered",
+          "ENRICHER_UNAVAILABLE"
+        );
+      }
+      const { id } = ctx.params;
+      if (typeof id !== "string" || id.length === 0) {
+        return error2(
+          "dismissModal requires a modal id in the path",
+          "INVALID_REQUEST"
+        );
+      }
+      const wasPresent = detector.getActive().some((m) => m.id === id);
+      if (!wasPresent) {
+        return error2(`modal not found: ${id}`, "MODAL_NOT_FOUND");
+      }
+      detector.dismissModal(id);
+      return success2({ dismissed: id });
+    },
     // Design Review
     ...designHandlers,
     // Health
     health: async () => {
       const stats = registry.getStats();
+      const registration = registry.getRegistrationCoverage();
       const response = {
         status: "healthy",
         timestamp: Date.now(),
-        ...stats
+        ...stats,
+        registration
       };
       if (config?.appInfo) {
         response.uiBridge = {
@@ -1154,7 +1374,24 @@ var WS_ROUTES = [
   { pattern: "design/evaluate/baseline", handler: "saveBaseline", httpMethods: ["POST"] },
   { pattern: "design/evaluate/diff", handler: "diffBaseline", httpMethods: ["POST"] },
   // Meta / Introspection
-  { pattern: "meta/methods", handler: "getMethods", httpMethods: ["GET"] }
+  { pattern: "meta/methods", handler: "getMethods", httpMethods: ["GET"] },
+  // AI helpers — mobile parity with the runner's `/ui-bridge/ai/*` family.
+  { pattern: "ai/fill-form", handler: "fillForm", httpMethods: ["POST"] },
+  // Test hooks — gated behind `features.testHooks`. Let external runners
+  // drive the ModalDetector over HTTP so tests can flip `snapshot.modalStack`
+  // without mounting React components.
+  {
+    pattern: "control/modal/push",
+    handler: "pushModal",
+    httpMethods: ["POST"],
+    requiresTestHooks: true
+  },
+  {
+    pattern: "control/modal/dismiss/:id",
+    handler: "dismissModal",
+    httpMethods: ["POST"],
+    requiresTestHooks: true
+  }
 ];
 var HANDLER_DESCRIPTIONS = {
   health: "Liveness probe; returns app metadata + element count",
@@ -1187,7 +1424,10 @@ var HANDLER_DESCRIPTIONS = {
   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)"
+  getMethods: "List every handler name (legacy introspection)",
+  fillForm: "Fill multiple inputs in one call: body { fields: [{elementId, value}] } \u2014 each field dispatches `type` + `clear:true`",
+  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"
 };
 var ACTION_REFERENCE = [
   { name: "press", aliases: ["click"], params: "PressActionParams (optional position)" },
@@ -1204,10 +1444,11 @@ var ACTION_REFERENCE = [
   { name: "swipe", params: "SwipeActionParams { direction, distance }" },
   { name: "toggle", params: "none \u2014 flips boolean controls" }
 ];
-function buildRoutesPayload() {
+function buildRoutesPayload(testHooks) {
   const entries = [];
   for (const r of WS_ROUTES) {
     if (!r.httpMethods) continue;
+    if (r.requiresTestHooks && !testHooks) continue;
     for (const m of r.httpMethods) {
       entries.push({ method: m, path: `/ui-bridge/${r.pattern}` });
     }
@@ -1217,11 +1458,11 @@ function buildRoutesPayload() {
   entries.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
   return { routes: entries, count: entries.length };
 }
-function buildHelpPayload() {
+function buildHelpPayload(testHooks) {
   return {
     version: 1,
     description: "UI Bridge Native HTTP surface. Prefix every path with /ui-bridge/.",
-    routes: WS_ROUTES.map((r) => ({
+    routes: WS_ROUTES.filter((r) => !r.requiresTestHooks || testHooks).map((r) => ({
       pattern: r.pattern,
       httpMethods: r.httpMethods ?? [],
       wsOnly: !r.httpMethods,
@@ -1257,7 +1498,8 @@ var NativeUIBridgeServer = class {
       appInfo: this.config.appInfo
     });
     this.handlers.getMethods = async () => {
-      const methods = WS_ROUTES.map((r) => ({
+      const testHooks = this.config.testHooks === true;
+      const methods = WS_ROUTES.filter((r) => !r.requiresTestHooks || testHooks).map((r) => ({
         method: r.pattern,
         httpMethods: r.httpMethods ? [...r.httpMethods] : void 0
       }));
@@ -1300,7 +1542,11 @@ var NativeUIBridgeServer = class {
           timestamp: Date.now()
         };
       } catch (e) {
-        return { success: false, error: `Navigation failed: ${e.message}`, timestamp: Date.now() };
+        return {
+          success: false,
+          error: `Navigation failed: ${e instanceof Error ? e.message : String(e)}`,
+          timestamp: Date.now()
+        };
       }
     };
     this.handlers.pageReplace = async (ctx) => {
@@ -1326,7 +1572,7 @@ var NativeUIBridgeServer = class {
       } catch (e) {
         return {
           success: false,
-          error: `Replace navigation failed: ${e.message}`,
+          error: `Replace navigation failed: ${e instanceof Error ? e.message : String(e)}`,
           timestamp: Date.now()
         };
       }
@@ -1345,7 +1591,7 @@ var NativeUIBridgeServer = class {
       } catch (e) {
         return {
           success: false,
-          error: `Back navigation failed: ${e.message}`,
+          error: `Back navigation failed: ${e instanceof Error ? e.message : String(e)}`,
           timestamp: Date.now()
         };
       }
@@ -1366,7 +1612,11 @@ var NativeUIBridgeServer = class {
           timestamp: Date.now()
         };
       } catch (e) {
-        return { success: false, error: `Refresh failed: ${e.message}`, timestamp: Date.now() };
+        return {
+          success: false,
+          error: `Refresh failed: ${e instanceof Error ? e.message : String(e)}`,
+          timestamp: Date.now()
+        };
       }
     };
   }
@@ -1424,7 +1674,7 @@ var NativeUIBridgeServer = class {
       } catch (e) {
         return {
           success: false,
-          error: `Screenshot capture failed: ${e.message}`,
+          error: `Screenshot capture failed: ${e instanceof Error ? e.message : String(e)}`,
           timestamp: Date.now()
         };
       }
@@ -1979,9 +2229,11 @@ var NativeUIBridgeServer = class {
    *   "control/component/my-comp/action/submit"          → handlers.executeComponentAction
    */
   async routeMethodToHandler(method, params) {
+    const testHooks = this.config.testHooks === true;
     for (const route of WS_ROUTES) {
       const pathParams = parsePath(route.pattern, method);
       if (!pathParams) continue;
+      if (route.requiresTestHooks && !testHooks) continue;
       const ctx = {
         params: pathParams,
         query: params.query && typeof params.query === "object" ? params.query : {},
@@ -2059,17 +2311,18 @@ var NativeUIBridgeServer = class {
       };
     }
     const stripped = path.slice(PREFIX.length);
+    const testHooks = this.config.testHooks === true;
     if (method === "GET" && stripped === "_help") {
       return {
         success: true,
-        data: buildHelpPayload(),
+        data: buildHelpPayload(testHooks),
         timestamp: Date.now()
       };
     }
     if (method === "GET" && stripped === "_routes") {
       return {
         success: true,
-        data: buildRoutesPayload(),
+        data: buildRoutesPayload(testHooks),
         timestamp: Date.now()
       };
     }
@@ -2080,6 +2333,9 @@ var NativeUIBridgeServer = class {
       if (!route.httpMethods) {
         continue;
       }
+      if (route.requiresTestHooks && !testHooks) {
+        continue;
+      }
       if (!route.httpMethods.includes(method)) {
         patternMatchedButWrongVerb = true;
         continue;