@qontinui/ui-bridge-native 0.1.6 → 0.2.1

package/dist/index.mjs

@@ -53,9 +53,51 @@ var NativeUIBridgeRegistry = class {
     this.components = /* @__PURE__ */ new Map();
     this.workflows = /* @__PURE__ */ new Map();
     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;
   }
   // ============================================================================
+  // Snapshot Enricher Slots
+  // ============================================================================
+  /**
+   * Register/replace canonical enrichers (modal/toast/undo). HMR-safe — calling
+   * with a partial set merges into existing slots instead of clobbering them.
+   */
+  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
+   * clobbering canonical fields. Returns a disposer.
+   */
+  registerSnapshotEnricher(name, fn) {
+    this.snapshotExtras.set(name, fn);
+    return () => this.unregisterSnapshotEnricher(name);
+  }
+  /** Remove a custom snapshot enricher by name */
+  unregisterSnapshotEnricher(name) {
+    this.snapshotExtras.delete(name);
+  }
+  // ============================================================================
   // Element Management
   // ============================================================================
   /**
@@ -121,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})`);
@@ -418,7 +461,7 @@ var NativeUIBridgeRegistry = class {
       const currentRoute = routeInfo.currentRoute;
       elements = elements.filter((e) => e.registrationRoute === currentRoute);
     }
-    return {
+    const snapshot = {
       timestamp: Date.now(),
       elements: elements.map((e) => {
         const handlers = extractHandlerNames(e.props);
@@ -448,8 +491,52 @@ 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 {
+        snapshot.modalStack = this.enrichers.modalDetector.getSnapshotModalContext();
+      } catch (error3) {
+        if (this.config.verbose) {
+          console.warn(`[ui-bridge-native] modalDetector enricher threw:`, error3);
+        }
+      }
+    }
+    if (this.enrichers.toastCapture) {
+      try {
+        snapshot.toasts = this.enrichers.toastCapture.getSnapshotToastContext();
+      } catch (error3) {
+        if (this.config.verbose) {
+          console.warn(`[ui-bridge-native] toastCapture enricher threw:`, error3);
+        }
+      }
+    }
+    if (this.enrichers.undoTracker) {
+      try {
+        snapshot.undoRedo = this.enrichers.undoTracker.getSnapshotUndoContext();
+      } catch (error3) {
+        if (this.config.verbose) {
+          console.warn(`[ui-bridge-native] undoTracker enricher threw:`, error3);
+        }
+      }
+    }
+    if (this.snapshotExtras.size > 0) {
+      const ctx = { elements, currentRoute: routeInfo?.currentRoute ?? null };
+      for (const [name, fn] of this.snapshotExtras) {
+        try {
+          const extra = fn(ctx);
+          if (extra && typeof extra === "object") {
+            Object.assign(snapshot, extra);
+          }
+        } catch (error3) {
+          if (this.config.verbose) {
+            console.warn(`[ui-bridge-native] snapshot enricher "${name}" threw:`, error3);
+          }
+        }
+      }
+    }
+    return snapshot;
   }
   /**
    * Get registry statistics
@@ -461,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
    */
@@ -595,6 +701,23 @@ function sleep(ms) {
 var DefaultNativeActionExecutor = class {
   constructor(registry) {
     this.registry = registry;
+    this.actionListeners = /* @__PURE__ */ new Set();
+  }
+  onActionExecuted(listener) {
+    this.actionListeners.add(listener);
+    return () => {
+      this.actionListeners.delete(listener);
+    };
+  }
+  /** Notify listeners out-of-band; isolate each invocation so one bad listener can't poison the rest. */
+  emitActionEvent(event) {
+    for (const listener of this.actionListeners) {
+      try {
+        listener(event);
+      } catch (error3) {
+        console.warn(`[ui-bridge-native] Action listener error:`, error3);
+      }
+    }
   }
   /**
    * Execute an action on an element
@@ -608,11 +731,23 @@ var DefaultNativeActionExecutor = class {
         registered = findElementByIdentifier(elementId) ?? void 0;
       }
       if (!registered) {
+        const failTime = Date.now();
+        const errorMsg = `Element not found: ${elementId}`;
+        this.emitActionEvent({
+          elementId,
+          action: request.action,
+          params: request.params,
+          success: false,
+          error: errorMsg,
+          timestamp: failTime,
+          requestId: request.requestId,
+          durationMs: failTime - startTime
+        });
         return {
           success: false,
-          error: `Element not found: ${elementId}`,
-          durationMs: Date.now() - startTime,
-          timestamp: Date.now(),
+          error: errorMsg,
+          durationMs: failTime - startTime,
+          timestamp: failTime,
           requestId: request.requestId
         };
       }
@@ -620,33 +755,67 @@ var DefaultNativeActionExecutor = class {
         const waitResult = await this.waitForElementInternal(registered.id, request.waitOptions);
         waitDurationMs = waitResult.waitedMs;
         if (!waitResult.met) {
+          const failTime = Date.now();
+          const errorMsg = waitResult.error || "Wait condition not met";
+          this.emitActionEvent({
+            elementId,
+            action: request.action,
+            params: request.params,
+            success: false,
+            error: errorMsg,
+            timestamp: failTime,
+            requestId: request.requestId,
+            durationMs: failTime - startTime
+          });
           return {
             success: false,
-            error: waitResult.error || "Wait condition not met",
-            durationMs: Date.now() - startTime,
-            timestamp: Date.now(),
+            error: errorMsg,
+            durationMs: failTime - startTime,
+            timestamp: failTime,
             requestId: request.requestId,
             waitDurationMs
           };
         }
       }
       const result = await this.performAction(registered, request.action, request.params);
+      const successTime = Date.now();
+      this.emitActionEvent({
+        elementId,
+        action: request.action,
+        params: request.params,
+        success: true,
+        timestamp: successTime,
+        requestId: request.requestId,
+        durationMs: successTime - startTime
+      });
       return {
         success: true,
         elementState: registered.getState(),
         result,
-        durationMs: Date.now() - startTime,
-        timestamp: Date.now(),
+        durationMs: successTime - startTime,
+        timestamp: successTime,
         requestId: request.requestId,
         waitDurationMs
       };
     } catch (error3) {
+      const failTime = Date.now();
+      const errorMsg = error3 instanceof Error ? error3.message : String(error3);
+      this.emitActionEvent({
+        elementId,
+        action: request.action,
+        params: request.params,
+        success: false,
+        error: errorMsg,
+        timestamp: failTime,
+        requestId: request.requestId,
+        durationMs: failTime - startTime
+      });
       return {
         success: false,
-        error: error3 instanceof Error ? error3.message : String(error3),
+        error: errorMsg,
         stack: error3 instanceof Error ? error3.stack : void 0,
-        durationMs: Date.now() - startTime,
-        timestamp: Date.now(),
+        durationMs: failTime - startTime,
+        timestamp: failTime,
         requestId: request.requestId,
         waitDurationMs
       };
@@ -1805,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({
@@ -1812,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;
@@ -1915,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 = {
@@ -2024,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",
@@ -2057,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)" },
@@ -2074,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}` });
     }
@@ -2087,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,
@@ -2127,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
       }));
@@ -2170,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) => {
@@ -2196,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()
         };
       }
@@ -2215,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()
         };
       }
@@ -2236,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()
+        };
       }
     };
   }
@@ -2294,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()
         };
       }
@@ -2849,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 : {},
@@ -2929,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()
       };
     }
@@ -2950,6 +3353,9 @@ var NativeUIBridgeServer = class {
       if (!route.httpMethods) {
         continue;
       }
+      if (route.requiresTestHooks && !testHooks) {
+        continue;
+      }
       if (!route.httpMethods.includes(method)) {
         patternMatchedButWrongVerb = true;
         continue;
@@ -3243,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;
@@ -3277,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;
@@ -3293,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 ───────────────────────────────────────────────────────────
@@ -3311,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 = () => {
@@ -3321,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",
@@ -3336,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 {
       }
     };
@@ -3347,7 +3774,7 @@ var DeviceAnnouncer = class {
       }
     };
     ws.onerror = (err) => {
-      console.warn("[DeviceAnnouncer] Cloud relay error:", err);
+      transportLogger.warn("[DeviceAnnouncer] Cloud relay error:", err);
     };
   }
   // ── Lifecycle ─────────────────────────────────────────────────────────────
@@ -3382,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) {
@@ -3444,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 = () => {
@@ -3454,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",
@@ -3472,7 +3899,7 @@ var CloudRelayClient = class {
       }
     };
     ws.onerror = (err) => {
-      console.warn("[CloudRelayClient] WebSocket error:", err);
+      transportLogger.warn("[CloudRelayClient] WebSocket error:", err);
     };
   }
   async onMessage(raw) {
@@ -3480,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 = {
@@ -3526,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,
@@ -3541,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) {
@@ -3564,6 +3991,192 @@ function parseQueryParams(path) {
   }
   return result;
 }
+
+// src/modal/modal-detector.ts
+var ModalDetector = class {
+  constructor() {
+    /** Map preserves O(1) idempotent replace by id; ordering comes from detectedAt. */
+    this.modals = /* @__PURE__ */ new Map();
+  }
+  pushModal(modal) {
+    const existing = this.modals.get(modal.id);
+    const detectedAt = existing ? existing.detectedAt : Date.now();
+    const next = {
+      id: modal.id,
+      title: modal.title,
+      type: modal.type ?? "modal",
+      blocking: modal.blocking ?? true,
+      dismissible: modal.dismissible ?? true,
+      detectedAt
+    };
+    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) {
+    return this.modals.delete(id);
+  }
+  getSnapshotModalContext() {
+    const active = this.getActive();
+    const ctx = {
+      modals: active,
+      hasBlockingModal: active.some((m) => m.blocking),
+      count: active.length
+    };
+    if (active.length > 0) {
+      ctx.topModal = active[active.length - 1];
+    }
+    return ctx;
+  }
+  getActive() {
+    return Array.from(this.modals.values()).sort((a, b) => a.detectedAt - b.detectedAt);
+  }
+  clear() {
+    this.modals.clear();
+  }
+};
+
+// src/toast/toast-capture.ts
+var DEFAULT_MAX_RECENT = 50;
+var ToastCapture = class {
+  constructor(config = {}) {
+    this.active = /* @__PURE__ */ new Map();
+    this.recent = [];
+    this.totalCaptured = 0;
+    this.maxRecent = config.maxRecent ?? DEFAULT_MAX_RECENT;
+  }
+  recordToast(toast) {
+    if (this.active.has(toast.id)) {
+      return;
+    }
+    const appearedAt = toast.appearedAt ?? Date.now();
+    const entry = {
+      id: toast.id,
+      message: toast.message,
+      level: toast.level ?? "info",
+      appearedAt,
+      visible: true,
+      durationMs: 0
+    };
+    this.active.set(toast.id, entry);
+    this.totalCaptured += 1;
+  }
+  dismissToast(id) {
+    const entry = this.active.get(id);
+    if (!entry) {
+      return;
+    }
+    this.active.delete(id);
+    const dismissedAt = Date.now();
+    const dismissed = {
+      ...entry,
+      dismissedAt,
+      visible: false,
+      durationMs: dismissedAt - entry.appearedAt
+    };
+    this.recent.push(dismissed);
+    if (this.recent.length > this.maxRecent) {
+      this.recent.shift();
+    }
+  }
+  getSnapshotToastContext() {
+    const now = Date.now();
+    const active = Array.from(this.active.values()).map((entry) => ({
+      ...entry,
+      durationMs: now - entry.appearedAt
+    }));
+    return {
+      active,
+      recent: [...this.recent],
+      totalCaptured: this.totalCaptured
+    };
+  }
+  clear() {
+    this.active.clear();
+    this.recent = [];
+    this.totalCaptured = 0;
+  }
+};
+
+// src/undo/undo-tracker.ts
+var DEFAULT_MAX_HISTORY = 50;
+function buildSummary(ctx) {
+  if (!ctx.canUndo && !ctx.canRedo) {
+    return "no undo available";
+  }
+  const parts = [];
+  if (ctx.canUndo) {
+    parts.push(`undo: '${ctx.undoDescription ?? "available"}'`);
+  }
+  if (ctx.canRedo) {
+    parts.push(`redo: '${ctx.redoDescription ?? "available"}'`);
+  }
+  return parts.join(" / ");
+}
+var UndoTracker = class {
+  constructor(config = {}) {
+    this.actions = [];
+    this.declaredState = null;
+    this.maxHistory = config.maxHistory ?? DEFAULT_MAX_HISTORY;
+  }
+  recordAction(record) {
+    this.actions.push(record);
+    if (this.actions.length > this.maxHistory) {
+      this.actions = this.actions.slice(-this.maxHistory);
+    }
+  }
+  setDeclaredState(state) {
+    this.declaredState = state;
+  }
+  getActionHistory() {
+    return this.actions.slice();
+  }
+  getSnapshotUndoContext() {
+    const declared = this.declaredState;
+    if (declared) {
+      const summary2 = buildSummary({
+        canUndo: declared.canUndo,
+        canRedo: declared.canRedo,
+        undoDescription: declared.undoDescription,
+        redoDescription: declared.redoDescription
+      });
+      return {
+        canUndo: declared.canUndo,
+        canRedo: declared.canRedo,
+        undoDescription: declared.undoDescription,
+        redoDescription: declared.redoDescription,
+        undoDepth: declared.undoDepth,
+        redoDepth: declared.redoDepth,
+        summary: summary2
+      };
+    }
+    const canUndo = this.actions.some((a) => a.reversible !== false);
+    const canRedo = false;
+    const lastReversible = [...this.actions].reverse().find((a) => a.reversible !== false);
+    const undoDescription = lastReversible?.description;
+    const summary = buildSummary({ canUndo, canRedo, undoDescription });
+    return {
+      canUndo,
+      canRedo,
+      undoDescription,
+      summary
+    };
+  }
+  executeUndo() {
+    return { ok: false, reason: "Not implemented in native" };
+  }
+  executeRedo() {
+    return { ok: false, reason: "Not implemented in native" };
+  }
+  clear() {
+    this.actions = [];
+    this.declaredState = null;
+  }
+};
 var UIBridgeNativeContext = createContext(null);
 function UIBridgeNativeProvider({
   children,
@@ -3580,6 +4193,9 @@ function UIBridgeNativeProvider({
 }) {
   const registryRef = useRef(null);
   const executorRef = useRef(null);
+  const modalDetectorRef = useRef(null);
+  const toastCaptureRef = useRef(null);
+  const undoTrackerRef = useRef(null);
   const [serverRunning, setServerRunning] = useState(false);
   if (!registryRef.current) {
     registryRef.current = new NativeUIBridgeRegistry({
@@ -3593,6 +4209,12 @@ function UIBridgeNativeProvider({
     executorRef.current = createNativeActionExecutor(registry);
   }
   const executor = executorRef.current;
+  if (!modalDetectorRef.current) modalDetectorRef.current = new ModalDetector();
+  if (!toastCaptureRef.current) toastCaptureRef.current = new ToastCapture();
+  if (!undoTrackerRef.current) undoTrackerRef.current = new UndoTracker();
+  const modalDetector = modalDetectorRef.current;
+  const toastCapture = toastCaptureRef.current;
+  const undoTracker = undoTrackerRef.current;
   const serverRef = useRef(null);
   const eventBridgeRef = useRef(null);
   const announcerRef = useRef(null);
@@ -3608,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) {
@@ -3662,7 +4285,9 @@ function UIBridgeNativeProvider({
     }
   }, [
     features.server,
+    features.testHooks,
     config.serverPort,
+    config.appInfo,
     registry,
     executor,
     serverAdapter,
@@ -3696,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);
@@ -3781,6 +4407,22 @@ function UIBridgeNativeProvider({
       lastRoute = current;
     });
   }, [routeProvider, registry]);
+  useEffect(() => {
+    registry.setEnrichers({ modalDetector, toastCapture, undoTracker });
+  }, [registry, modalDetector, toastCapture, undoTracker]);
+  useEffect(() => {
+    const unsubscribe = executor.onActionExecuted((event) => {
+      if (!event.success) return;
+      undoTracker.recordAction({
+        id: event.requestId ?? `action-${event.timestamp}`,
+        type: event.action,
+        targetId: event.elementId,
+        timestamp: event.timestamp,
+        reversible: true
+      });
+    });
+    return unsubscribe;
+  }, [executor, undoTracker]);
   const on = useCallback(
     (type, listener) => registry.on(type, listener),
     [registry]
@@ -3795,6 +4437,9 @@ function UIBridgeNativeProvider({
       config,
       registry,
       executor,
+      modalDetector,
+      toastCapture,
+      undoTracker,
       getElements,
       getComponents,
       createSnapshot,
@@ -3811,6 +4456,9 @@ function UIBridgeNativeProvider({
       config,
       registry,
       executor,
+      modalDetector,
+      toastCapture,
+      undoTracker,
       getElements,
       getComponents,
       createSnapshot,
@@ -3905,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;
@@ -4171,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,
@@ -4291,6 +4939,37 @@ function useUIBridgeRequired() {
   }
   return result;
 }
+function useUIBridgeModal(opts) {
+  const { modalDetector } = useUIBridgeNative();
+  const { id, title, type, blocking, dismissible } = opts;
+  useEffect(() => {
+    modalDetector.pushModal({ id, title, type, blocking, dismissible });
+    return () => {
+      modalDetector.dismissModal(id);
+    };
+  }, [modalDetector, id, title, type, blocking, dismissible]);
+}
+function useUIBridgeToast(opts) {
+  const { toastCapture } = useUIBridgeNative();
+  const { id, message, level } = opts;
+  useEffect(() => {
+    toastCapture.recordToast({ id, message, level });
+    return () => {
+      toastCapture.dismissToast(id);
+    };
+  }, [toastCapture, id, message, level]);
+}
+function useToastRecorder() {
+  const { toastCapture } = useUIBridgeNative();
+  const recordToast = useCallback(
+    (toast) => {
+      toastCapture.recordToast(toast);
+    },
+    [toastCapture]
+  );
+  const dismissToast = useCallback((id) => toastCapture.dismissToast(id), [toastCapture]);
+  return { recordToast, dismissToast };
+}
 
 // src/server/types.ts
 var UI_BRIDGE_NATIVE_ROUTES = {
@@ -4420,6 +5099,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",
@@ -4929,8 +5627,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);
   }, []);
@@ -5192,6 +5890,6 @@ var styles = StyleSheet.create({
   }
 });
 
-export { CloudRelayClient, DefaultNativeActionExecutor, DeviceAnnouncer, NativeUIBridgeRegistry, NativeUIBridgeServer, UIBridgeInspector, UIBridgeNativeProvider, UI_BRIDGE_NATIVE_ROUTES, WebSocketConnection, WebSocketEventBridge, buildTreePath, buildUpgradeResponse, captureNativeResponsiveSnapshot, captureNativeStateVariations, computeAcceptKey, createDesignHandlers, createNativeActionExecutor, createNativeElementIdentifier, createNativeServer, createServerHandlers, extractHandlerNames, findAllByPattern, findElementByIdentifier, getGlobalRegistry, getNativeElementDesignData, mapNativeStyleToExtended, matchesIdentifier, parseTreePath, resetGlobalRegistry, setGlobalRegistry, useUIBridge, useUIBridgeNative, useUIBridgeNativeOptional, useUIBridgeNativeRequired, useUIBridgeRequired, useUIComponent, useUIComponentAction, useUIElement, useUIElementWithProps };
+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 };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map