@qontinui/ui-bridge-native 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createContext, useRef, useState, useCallback, useEffect, useMemo, useContext } from 'react';
 import { Dimensions, StyleSheet, Platform, TouchableOpacity, Text, Modal, View, ScrollView } from 'react-native';
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -55,6 +55,13 @@ var NativeUIBridgeRegistry = class {
     this.eventListeners = /* @__PURE__ */ new Map();
     this.enrichers = {};
     this.snapshotExtras = /* @__PURE__ */ new Map();
+    /**
+     * Sticky flag: flips `true` the first time any element is registered and
+     * stays `true` even after elements are unregistered. Lets agents distinguish
+     * "this route never wired any elements" from "this route registered then
+     * unmounted".
+     */
+    this.everHadRegistrations = false;
     this.config = config;
   }
   // ============================================================================
@@ -67,6 +74,16 @@ var NativeUIBridgeRegistry = class {
   setEnrichers(e) {
     this.enrichers = { ...this.enrichers, ...e };
   }
+  /**
+   * Read-only accessor for the canonical enrichers slot. Returned object is
+   * the live reference, so callers can detect "no detector wired" via
+   * `getEnrichers().modalDetector === undefined`. Used by the test-hook HTTP
+   * handlers (`control/modal/push`, `control/modal/dismiss/:id`) which need
+   * to drive the ModalDetector directly without re-instantiating it.
+   */
+  getEnrichers() {
+    return this.enrichers;
+  }
   /**
    * Register a custom snapshot enricher. The returned object will be
    * `Object.assign`ed onto the snapshot, so use unique top-level keys to avoid
@@ -146,6 +163,7 @@ var NativeUIBridgeRegistry = class {
       stateStyles
     };
     this.elements.set(id, registered);
+    this.everHadRegistrations = true;
     this.emit("element:registered", { id, type, label });
     if (this.config.verbose) {
       console.log(`[ui-bridge-native] Registered element: ${id} (${type})`);
@@ -473,7 +491,8 @@ var NativeUIBridgeRegistry = class {
         stepCount: w.steps.length
       })),
       currentRoute: routeInfo?.currentRoute ?? null,
-      segments: routeInfo?.segments
+      segments: routeInfo?.segments,
+      registration: this.getRegistrationCoverage()
     };
     if (this.enrichers.modalDetector) {
       try {
@@ -529,6 +548,25 @@ var NativeUIBridgeRegistry = class {
       workflows: this.workflows.size
     };
   }
+  /**
+   * Compute registration coverage metadata for the current registry state.
+   *
+   * Groups currently-registered elements by `registrationRoute`, bucketing
+   * elements without a route under `'?'`. `everHadRegistrations` is sticky —
+   * once true, it stays true for the lifetime of the registry instance.
+   */
+  getRegistrationCoverage() {
+    const byRoute = {};
+    for (const element of this.elements.values()) {
+      const key = element.registrationRoute == null || element.registrationRoute === "" ? "?" : element.registrationRoute;
+      byRoute[key] = (byRoute[key] ?? 0) + 1;
+    }
+    return {
+      totalRegistered: this.elements.size,
+      everHadRegistrations: this.everHadRegistrations,
+      byRoute
+    };
+  }
   /**
    * Clear all registrations
    */
@@ -1936,6 +1974,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({
@@ -1943,9 +1995,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;
@@ -2046,15 +2138,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 = {
@@ -2155,7 +2394,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",
@@ -2188,7 +2444,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)" },
@@ -2205,10 +2464,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}` });
     }
@@ -2218,11 +2478,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,
@@ -2258,7 +2518,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
       }));
@@ -2301,7 +2562,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) => {
@@ -2327,7 +2592,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()
         };
       }
@@ -2346,7 +2611,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()
         };
       }
@@ -2367,7 +2632,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()
+        };
       }
     };
   }
@@ -2425,7 +2694,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()
         };
       }
@@ -2980,9 +3249,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 : {},
@@ -3060,17 +3331,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()
       };
     }
@@ -3081,6 +3353,9 @@ var NativeUIBridgeServer = class {
       if (!route.httpMethods) {
         continue;
       }
+      if (route.requiresTestHooks && !testHooks) {
+        continue;
+      }
       if (!route.httpMethods.includes(method)) {
         patternMatchedButWrongVerb = true;
         continue;
@@ -3374,6 +3649,27 @@ var WebSocketEventBridge = class {
     }, this.heartbeatIntervalMs);
   }
 };
+
+// src/transport/logger.ts
+function createTransportLogger() {
+  return {
+    silent: false,
+    log(message, ...args) {
+      if (!this.silent) {
+        console.log(message, ...args);
+      }
+    },
+    warn(message, ...args) {
+      console.warn(message, ...args);
+    },
+    error(message, ...args) {
+      console.error(message, ...args);
+    }
+  };
+}
+var transportLogger = createTransportLogger();
+
+// src/transport/DeviceAnnouncer.ts
 var DEFAULT_PORT = 8087;
 var RECONNECT_INITIAL_DELAY_MS = 2e3;
 var RECONNECT_MAX_DELAY_MS = 6e4;
@@ -3408,7 +3704,7 @@ var DeviceAnnouncer = class {
    */
   async startMdnsAdvertise(ZeroconfCtor) {
     if (!ZeroconfCtor) {
-      console.log(
+      transportLogger.log(
         "[DeviceAnnouncer] mDNS advertisement skipped (no Zeroconf constructor provided). Pass one to enable mDNS."
       );
       return;
@@ -3424,9 +3720,9 @@ var DeviceAnnouncer = class {
         pairing_token: this.pairingToken
       });
       this.state = { ...this.state, mdnsActive: true };
-      console.log(`[DeviceAnnouncer] mDNS: advertising "${serviceName}" on port ${port}`);
+      transportLogger.log(`[DeviceAnnouncer] mDNS: advertising "${serviceName}" on port ${port}`);
     } catch (err) {
-      console.warn("[DeviceAnnouncer] mDNS start failed:", err);
+      transportLogger.warn("[DeviceAnnouncer] mDNS start failed:", err);
     }
   }
   // ── Cloud relay ───────────────────────────────────────────────────────────
@@ -3442,7 +3738,7 @@ var DeviceAnnouncer = class {
     }
     if (this.stopped) return;
     const url = `${this.config.cloudRelayUrl}?token=${encodeURIComponent(this.config.cloudToken)}`;
-    console.log("[DeviceAnnouncer] Cloud relay: connecting to", url);
+    transportLogger.log("[DeviceAnnouncer] Cloud relay: connecting to", url);
     const ws = new WebSocket(url);
     this.cloudWs = ws;
     ws.onopen = () => {
@@ -3452,7 +3748,7 @@ var DeviceAnnouncer = class {
       }
       this.reconnectDelay = RECONNECT_INITIAL_DELAY_MS;
       this.state = { ...this.state, cloudConnected: true };
-      console.log("[DeviceAnnouncer] Cloud relay: connected");
+      transportLogger.log("[DeviceAnnouncer] Cloud relay: connected");
       ws.send(
         JSON.stringify({
           type: "device_register",
@@ -3467,7 +3763,7 @@ var DeviceAnnouncer = class {
     ws.onmessage = (event) => {
       try {
         const msg = JSON.parse(event.data);
-        console.log("[DeviceAnnouncer] Cloud relay message:", msg.type);
+        transportLogger.log("[DeviceAnnouncer] Cloud relay message:", msg.type);
       } catch {
       }
     };
@@ -3478,7 +3774,7 @@ var DeviceAnnouncer = class {
       }
     };
     ws.onerror = (err) => {
-      console.warn("[DeviceAnnouncer] Cloud relay error:", err);
+      transportLogger.warn("[DeviceAnnouncer] Cloud relay error:", err);
     };
   }
   // ── Lifecycle ─────────────────────────────────────────────────────────────
@@ -3513,7 +3809,7 @@ var DeviceAnnouncer = class {
   scheduleReconnect() {
     if (this.stopped) return;
     const delay = this.reconnectDelay;
-    console.log(`[DeviceAnnouncer] Cloud relay: reconnecting in ${delay}ms`);
+    transportLogger.log(`[DeviceAnnouncer] Cloud relay: reconnecting in ${delay}ms`);
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       if (!this.stopped) {
@@ -3575,7 +3871,7 @@ var CloudRelayClient = class {
   connect() {
     if (this.stopped) return;
     const url = `${this.config.relayUrl}?token=${encodeURIComponent(this.config.authToken)}`;
-    console.log("[CloudRelayClient] Connecting to", url);
+    transportLogger.log("[CloudRelayClient] Connecting to", url);
     const ws = new WebSocket(url);
     this.ws = ws;
     ws.onopen = () => {
@@ -3585,7 +3881,7 @@ var CloudRelayClient = class {
       }
       this._isConnected = true;
       this.reconnectDelay = INITIAL_RECONNECT_DELAY_MS;
-      console.log("[CloudRelayClient] Connected to relay");
+      transportLogger.log("[CloudRelayClient] Connected to relay");
       ws.send(
         JSON.stringify({
           type: "device_register",
@@ -3603,7 +3899,7 @@ var CloudRelayClient = class {
       }
     };
     ws.onerror = (err) => {
-      console.warn("[CloudRelayClient] WebSocket error:", err);
+      transportLogger.warn("[CloudRelayClient] WebSocket error:", err);
     };
   }
   async onMessage(raw) {
@@ -3611,12 +3907,12 @@ var CloudRelayClient = class {
     try {
       msg = JSON.parse(raw);
     } catch {
-      console.warn("[CloudRelayClient] Received non-JSON message");
+      transportLogger.warn("[CloudRelayClient] Received non-JSON message");
       return;
     }
     if (msg["type"] !== "tunnel_request") return;
     if (typeof msg["id"] !== "string" || typeof msg["method"] !== "string" || typeof msg["path"] !== "string") {
-      console.warn("[CloudRelayClient] Malformed tunnel_request \u2014 missing required fields");
+      transportLogger.warn("[CloudRelayClient] Malformed tunnel_request \u2014 missing required fields");
       return;
     }
     const req = {
@@ -3657,7 +3953,7 @@ var CloudRelayClient = class {
         body: bodyValue
       };
     } catch (err) {
-      console.error("[CloudRelayClient] Error handling tunneled request:", err);
+      transportLogger.error("[CloudRelayClient] Error handling tunneled request:", err);
       return {
         id: req.id,
         status: 500,
@@ -3672,7 +3968,7 @@ var CloudRelayClient = class {
   scheduleReconnect() {
     if (this.stopped) return;
     const delay = this.reconnectDelay;
-    console.log(`[CloudRelayClient] Reconnecting in ${delay}ms`);
+    transportLogger.log(`[CloudRelayClient] Reconnecting in ${delay}ms`);
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       if (!this.stopped) {
@@ -3715,8 +4011,14 @@ var ModalDetector = class {
     };
     this.modals.set(modal.id, next);
   }
+  /**
+   * Remove a modal from the stack. Returns `true` if a modal with that id
+   * was actually deleted, `false` if nothing matched (idempotent so repeated
+   * calls don't throw, but callers — e.g. the HTTP test-hook endpoint — can
+   * surface the miss to clients).
+   */
   dismissModal(id) {
-    this.modals.delete(id);
+    return this.modals.delete(id);
   }
   getSnapshotModalContext() {
     const active = this.getActive();
@@ -3928,7 +4230,8 @@ function UIBridgeNativeProvider({
     const server = createNativeServer(registry, executor, {
       serverPort: config.serverPort || 8087,
       cors: true,
-      appInfo: config.appInfo
+      appInfo: config.appInfo,
+      testHooks: features.testHooks === true
     });
     server.setAdapter(serverAdapter);
     if (navigationProvider) {
@@ -3982,7 +4285,9 @@ function UIBridgeNativeProvider({
     }
   }, [
     features.server,
+    features.testHooks,
     config.serverPort,
+    config.appInfo,
     registry,
     executor,
     serverAdapter,
@@ -4016,7 +4321,8 @@ function UIBridgeNativeProvider({
           const bareServer = createNativeServer(registry, executor, {
             serverPort: config.serverPort || 8087,
             cors: true,
-            appInfo: config.appInfo
+            appInfo: config.appInfo,
+            testHooks: features.testHooks === true
           });
           if (navigationProvider) bareServer.setNavigationProvider(navigationProvider);
           if (screenshotProvider) bareServer.setScreenshotProvider(screenshotProvider);
@@ -4247,7 +4553,7 @@ function useUIElement(options) {
     registeredRef.current = false;
     registeredIdRef.current = null;
     setRegistered(false);
-  }, [bridge, registered, id]);
+  }, [bridge, id]);
   const onLayout = useCallback(
     (event) => {
       const { x, y, width, height } = event.nativeEvent.layout;
@@ -4513,7 +4819,7 @@ function useUIComponent(options) {
   const registeredComponent = useMemo(() => {
     if (!bridge) return null;
     return bridge.registry.getComponent(id) || null;
-  }, [bridge, id, registeredRef.current]);
+  }, [bridge, id]);
   return {
     registered: registeredRef.current,
     executeAction,
@@ -4664,6 +4970,12 @@ function useToastRecorder() {
   const dismissToast = useCallback((id) => toastCapture.dismissToast(id), [toastCapture]);
   return { recordToast, dismissToast };
 }
+function State(props) {
+  return /* @__PURE__ */ jsx(Fragment, { children: props.children });
+}
+function TransitionTo(props) {
+  return /* @__PURE__ */ jsx(Fragment, { children: props.children });
+}
 
 // src/server/types.ts
 var UI_BRIDGE_NATIVE_ROUTES = {
@@ -4793,6 +5105,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",
@@ -5302,8 +5633,8 @@ function UIBridgeInspector({
   const bridge = useUIBridgeNativeOptional();
   const [showInspector, setShowInspector] = useState(visible);
   const [selectedElement, setSelectedElement] = useState(null);
-  const elements = useMemo(() => bridge ? bridge.getElements() : [], [bridge, showInspector]);
-  const components = useMemo(() => bridge ? bridge.getComponents() : [], [bridge, showInspector]);
+  const elements = useMemo(() => bridge ? bridge.getElements() : [], [bridge]);
+  const components = useMemo(() => bridge ? bridge.getComponents() : [], [bridge]);
   const handleToggle = useCallback(() => {
     setShowInspector((prev) => !prev);
   }, []);
@@ -5565,6 +5896,6 @@ var styles = StyleSheet.create({
   }
 });
 
-export { CloudRelayClient, DefaultNativeActionExecutor, DeviceAnnouncer, ModalDetector, NativeUIBridgeRegistry, NativeUIBridgeServer, ToastCapture, UIBridgeInspector, UIBridgeNativeProvider, UI_BRIDGE_NATIVE_ROUTES, UndoTracker, WebSocketConnection, WebSocketEventBridge, buildTreePath, buildUpgradeResponse, captureNativeResponsiveSnapshot, captureNativeStateVariations, computeAcceptKey, createDesignHandlers, createNativeActionExecutor, createNativeElementIdentifier, createNativeServer, createServerHandlers, extractHandlerNames, findAllByPattern, findElementByIdentifier, getGlobalRegistry, getNativeElementDesignData, mapNativeStyleToExtended, matchesIdentifier, parseTreePath, resetGlobalRegistry, setGlobalRegistry, useToastRecorder, useUIBridge, useUIBridgeModal, useUIBridgeNative, useUIBridgeNativeOptional, useUIBridgeNativeRequired, useUIBridgeRequired, useUIBridgeToast, useUIComponent, useUIComponentAction, useUIElement, useUIElementWithProps };
+export { CloudRelayClient, DefaultNativeActionExecutor, DeviceAnnouncer, ModalDetector, NativeUIBridgeRegistry, NativeUIBridgeServer, State, ToastCapture, TransitionTo, UIBridgeInspector, UIBridgeNativeProvider, UI_BRIDGE_NATIVE_ROUTES, UndoTracker, WebSocketConnection, WebSocketEventBridge, buildTreePath, buildUpgradeResponse, captureNativeResponsiveSnapshot, captureNativeStateVariations, computeAcceptKey, createDesignHandlers, createNativeActionExecutor, createNativeElementIdentifier, createNativeServer, createServerHandlers, extractHandlerNames, findAllByPattern, findElementByIdentifier, getGlobalRegistry, getNativeElementDesignData, mapNativeStyleToExtended, matchesIdentifier, parseTreePath, resetGlobalRegistry, setGlobalRegistry, useToastRecorder, useUIBridge, useUIBridgeModal, useUIBridgeNative, useUIBridgeNativeOptional, useUIBridgeNativeRequired, useUIBridgeRequired, useUIBridgeToast, useUIComponent, useUIComponentAction, useUIElement, useUIElementWithProps };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map