@qontinui/ui-bridge-native 0.4.0 → 0.6.1

package/dist/react/UIBridgeNativeProvider.d.ts

@@ -8,7 +8,7 @@ import type { NativeUIBridgeFeatures, NativeUIBridgeConfig, RegisteredNativeElem
 import { NativeUIBridgeRegistry } from '../core/registry';
 import type { NativeActionExecutor } from '../control/types';
 import { type ServerAdapter } from '../server/http-server';
-import type { RouteProvider } from '../server/types';
+import type { RouteProvider, KeepAwakeProvider } from '../server/types';
 import { type CloudRelayConfig } from '../transport/CloudRelayClient';
 import { ModalDetector } from '../modal/modal-detector';
 import { ToastCapture } from '../toast/toast-capture';
@@ -89,6 +89,13 @@ export interface UIBridgeNativeProviderProps {
             height: number;
         }>;
     };
+    /**
+     * Keep-awake provider for native screen-wake control via UI Bridge.
+     * Pass expo-keep-awake's activateKeepAwakeAsync/deactivateKeepAwake (wrapped
+     * to the request/release shape) so an external runner never loses the device
+     * to a screen lock. The SDK never imports expo-keep-awake directly.
+     */
+    keepAwakeProvider?: KeepAwakeProvider;
     /**
      * Route provider for exposing the current navigation route in snapshots.
      * Wire this to Expo Router's `usePathname()` / `useSegments()` via a module-level ref.
@@ -134,7 +141,7 @@ export interface UIBridgeNativeProviderProps {
  * }
  * ```
  */
-export declare function UIBridgeNativeProvider({ children, features, config, onEvent, serverAdapter, navigationProvider, screenshotProvider, routeProvider, cloudRelayConfig, enableMdnsAnnounce, deviceId, }: UIBridgeNativeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function UIBridgeNativeProvider({ children, features, config, onEvent, serverAdapter, navigationProvider, screenshotProvider, keepAwakeProvider, routeProvider, cloudRelayConfig, enableMdnsAnnounce, deviceId, }: UIBridgeNativeProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
  * useUIBridgeNative hook
  *

package/dist/react/UIBridgeNativeProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UIBridgeNativeProvider.d.ts","sourceRoot":"","sources":["../../src/react/UIBridgeNativeProvider.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"UIBridgeNativeProvider.d.ts","sourceRoot":"","sources":["../../src/react/UIBridgeNativeProvider.tsx"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -256,7 +256,18 @@ var NativeUIBridgeRegistry = class {
     return Array.from(this.elements.values());
   }
   /**
-   * Get all registered elements that are visible and have a layout
+   * Get all registered elements that are visible AND have a measured layout.
+   *
+   * This is the *strict* visibility filter: requires `state.visible === true`
+   * AND `state.layout !== null`. Use this when you need both signals
+   * (e.g. coord-based tap, where you need an actual rect to hit-test against).
+   *
+   * Callers driving an LLM agent typically want
+   * {@link getMountedVisibleElements} instead — that variant accepts
+   * elements that *should* be on screen (visible:true) but whose first
+   * `onLayout` has not yet fired. Without it, a snapshot taken in the gap
+   * between mount and the first layout pass returns 0 elements on a fully
+   * populated screen.
    */
   getVisibleElements() {
     return this.getAllElements().filter((e) => {
@@ -264,6 +275,26 @@ var NativeUIBridgeRegistry = class {
       return state.visible && state.layout !== null;
     });
   }
+  /**
+   * Get all registered elements marked as visible (regardless of layout).
+   *
+   * Looser than {@link getVisibleElements}: includes elements whose
+   * `onLayout` callback has not yet fired (so `layout === null`). React
+   * Native's `onLayout` is async — there's a one-tick window after mount
+   * where elements are in the tree, the user *sees* them, but the
+   * registry hasn't received their measurements yet. Excluding those
+   * elements makes `getSnapshot?visibleOnly=true` return 0 on a populated
+   * screen, which is a worse failure mode than including a few elements
+   * we can't yet locate spatially.
+   *
+   * Used by `createSnapshot`'s `visibleOnly` filter and by the
+   * `getSnapshot` / `getElements` handlers. Each emitted element carries a
+   * `visibility` discriminator (`"visible"` / `"likely-visible"`) so
+   * agents that *do* require a known rect can branch downstream.
+   */
+  getMountedVisibleElements() {
+    return this.getAllElements().filter((e) => e.getState().visible);
+  }
   /**
    * Get elements registered on a specific route (for page-scoped filtering)
    */
@@ -538,7 +569,7 @@ var NativeUIBridgeRegistry = class {
       }
       return { currentRoute: null, segments: void 0 };
     })();
-    let elements = options?.visibleOnly ? this.getVisibleElements() : this.getAllElements();
+    let elements = options?.visibleOnly ? this.getMountedVisibleElements() : this.getAllElements();
     if (options?.currentRouteOnly && resolvedRoute.currentRoute) {
       const currentRoute = resolvedRoute.currentRoute;
       elements = elements.filter((e) => e.registrationRoute === currentRoute);
@@ -547,16 +578,19 @@ var NativeUIBridgeRegistry = class {
       timestamp: Date.now(),
       elements: elements.map((e) => {
         const handlers = extractHandlerNames(e.props);
+        const state = e.getState();
+        const visibility = !state.visible ? "hidden" : state.layout !== null ? "visible" : "likely-visible";
         return {
           id: e.id,
           type: e.type,
           label: e.label,
           identifier: e.getIdentifier(),
-          state: e.getState(),
+          state,
           actions: e.actions,
           customActions: e.customActions ? Object.keys(e.customActions) : void 0,
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
-          registrationRoute: e.registrationRoute
+          registrationRoute: e.registrationRoute,
+          visibility
         };
       }),
       components: this.getAllComponents().map((c) => ({
@@ -1898,22 +1932,25 @@ function createServerHandlers(registry, executor, config) {
     getElements: async (ctx) => {
       const visibleOnly = ctx.query?.visibleOnly === "true" || ctx.body?.visibleOnly === true;
       const forRoute = ctx.query?.route || ctx.body?.route;
-      let allElements = visibleOnly ? registry.getVisibleElements() : registry.getAllElements();
+      let allElements = visibleOnly ? registry.getMountedVisibleElements() : registry.getAllElements();
       if (forRoute) {
         allElements = allElements.filter((e) => e.registrationRoute === forRoute);
       }
       const elements = allElements.map((e) => {
         const handlers = extractHandlerNames(e.props);
+        const state = e.getState();
+        const visibility = !state.visible ? "hidden" : state.layout !== null ? "visible" : "likely-visible";
         return {
           id: e.id,
           type: e.type,
           label: e.label,
           identifier: e.getIdentifier(),
-          state: e.getState(),
+          state,
           actions: e.actions,
           customActions: e.customActions ? Object.keys(e.customActions) : void 0,
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
-          registrationRoute: e.registrationRoute
+          registrationRoute: e.registrationRoute,
+          visibility
         };
       });
       return success2({ elements });
@@ -2168,6 +2205,45 @@ function createServerHandlers(registry, executor, config) {
         "NOT_SUPPORTED"
       );
     },
+    // Keep-awake (stub — apps should override via setKeepAwakeProvider, which
+    // the provider wires when a keepAwakeProvider prop is supplied)
+    keepAwake: async () => {
+      return error2(
+        "keep-awake not configured. Provide a keepAwakeProvider to UIBridgeNativeProvider.",
+        "NOT_SUPPORTED"
+      );
+    },
+    // AI helpers — runner-only endpoints that have no React Native analog.
+    //
+    // The mobile bridge mounts explicit NOT_SUPPORTED stubs at the runner's
+    // cheatsheet paths so callers (and the /manual-test skill in particular)
+    // get a structured envelope explaining the gap rather than a confusing
+    // HTTP 404. Each error message names an in-tree mobile replacement so
+    // operators aren't left guessing what to use instead.
+    aiForms: async () => {
+      return error2(
+        'ai/forms (form discovery) is runner-only; mobile React Native has no DOM to walk. Use GET /ui-bridge/control/snapshot and filter for type === "input" instead.',
+        "NOT_SUPPORTED"
+      );
+    },
+    aiIdleStatus: async () => {
+      return error2(
+        'ai/idle-status (page-idle signal) is runner-only; mobile React Native has no DOM-mutation / network-idle signals. Use the registry event stream (WS subscribe to "element:registered"/"element:stateChanged") or poll /control/snapshot for stability.',
+        "NOT_SUPPORTED"
+      );
+    },
+    aiChangeBufferEnable: async () => {
+      return error2(
+        'ai/change-buffer (DOM mutation diff buffer) is runner-only; mobile React Native has no DOM. Use the WS event bridge (subscribe to "element:registered"/"element:unregistered"/"element:stateChanged") for change notifications.',
+        "NOT_SUPPORTED"
+      );
+    },
+    aiWaitForElement: async () => {
+      return error2(
+        'POST /ai/wait-for-element is runner-only on mobile. Use the WS "waitForElement" JSON-RPC method or "waitForCondition" instead \u2014 same semantics, no HTTP polling overhead.',
+        "NOT_SUPPORTED"
+      );
+    },
     // Meta / Introspection (stub — server constructor overrides with real route table)
     getMethods: async () => {
       return error2("Methods introspection not configured", "NOT_SUPPORTED");
@@ -2823,6 +2899,24 @@ var WS_ROUTES = [
   { 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"] },
+  // AI helpers — NOT_SUPPORTED stubs. These endpoints exist on the runner-side
+  // UI Bridge surface (and the /manual-test skill's cheatsheet documents them
+  // as if they're universally available). Mobile React Native has no DOM, so
+  // the mobile bridge mounts explicit stubs so callers get a structured
+  // NOT_SUPPORTED envelope (with a hint pointing at the mobile-native
+  // replacement) instead of a confusing HTTP 404.
+  { pattern: "ai/forms", handler: "aiForms", httpMethods: ["GET"] },
+  { pattern: "ai/idle-status", handler: "aiIdleStatus", httpMethods: ["GET"] },
+  {
+    pattern: "ai/change-buffer/enable",
+    handler: "aiChangeBufferEnable",
+    httpMethods: ["POST"]
+  },
+  {
+    pattern: "ai/wait-for-element",
+    handler: "aiWaitForElement",
+    httpMethods: ["POST"]
+  },
   // Coord-based tap — synthesizes a press at the given screen coords by
   // matching against registered elements' layout rects.
   { pattern: "control/tap", handler: "tapAt", httpMethods: ["POST"] },
@@ -2841,6 +2935,12 @@ var WS_ROUTES = [
     httpMethods: ["POST"],
     requiresTestHooks: true
   },
+  {
+    pattern: "control/keep-awake",
+    handler: "keepAwake",
+    httpMethods: ["POST"],
+    requiresTestHooks: true
+  },
   // Observability — last-N console errors + network requests. testHooks-gated
   // because patching `console.error` / `fetch` is invasive in production.
   {
@@ -2889,11 +2989,16 @@ var HANDLER_DESCRIPTIONS = {
   diffBaseline: "Diff current UI against a saved baseline",
   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`",
+  aiForms: 'STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Use /control/snapshot + filter type==="input" instead.',
+  aiIdleStatus: "STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Subscribe to registry events over WS for change signals.",
+  aiChangeBufferEnable: "STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Use WS event subscriptions for change notifications.",
+  aiWaitForElement: "STUB \u2014 runner-only; mobile returns NOT_SUPPORTED. Use the WS waitForElement / waitForCondition JSON-RPC methods.",
   tapAt: "Synthesize a press at given screen coords by matching registered element layout rects: body { x, y, action? }",
   getConsoleErrors: "TEST HOOK \u2014 last-N console.error/console.warn entries; ?since=<ms>&limit=<n>",
   getNetworkRequests: "TEST HOOK \u2014 last-N fetch/XHR entries with status + duration; ?since=<ms>&limit=<n>",
   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"
+  dismissModal: "TEST HOOK \u2014 dismiss a modal by id from the snapshot.modalStack via the registry ModalDetector",
+  keepAwake: "TEST HOOK \u2014 keep the device screen awake via the injected keepAwakeProvider: body { enabled: boolean, durationMs?: number }"
 };
 var ACTION_REFERENCE = [
   { name: "press", aliases: ["click"], params: "PressActionParams (optional position)" },
@@ -3161,6 +3266,35 @@ var NativeUIBridgeServer = class {
       }
     };
   }
+  /**
+   * Set a keep-awake provider for native screen-wake control.
+   * This enables `control/keep-awake` and arms the auto-arm hook in
+   * handleRequest (every request keeps the screen alive for 60s).
+   */
+  setKeepAwakeProvider(provider) {
+    this.keepAwakeProvider = provider;
+    this.handlers.keepAwake = async (ctx) => {
+      const { enabled, durationMs } = ctx.body ?? {};
+      if (typeof enabled !== "boolean") {
+        return {
+          success: false,
+          error: "enabled must be boolean",
+          code: "INVALID_REQUEST",
+          timestamp: Date.now()
+        };
+      }
+      if (enabled) {
+        provider.request("ui-bridge", typeof durationMs === "number" ? durationMs : void 0);
+      } else {
+        provider.release("ui-bridge");
+      }
+      return {
+        success: true,
+        data: { enabled, durationMs: typeof durationMs === "number" ? durationMs : null },
+        timestamp: Date.now()
+      };
+    };
+  }
   /**
    * Start the HTTP server
    */
@@ -3753,6 +3887,12 @@ var NativeUIBridgeServer = class {
     if (request.method === "OPTIONS") {
       return { status: 204, headers, body: "" };
     }
+    if (this.config.testHooks === true && this.keepAwakeProvider) {
+      try {
+        this.keepAwakeProvider.request("auto-arm", 6e4);
+      } catch {
+      }
+    }
     try {
       const response = await this.routeRequest(request);
       return {
@@ -4653,6 +4793,7 @@ function UIBridgeNativeProvider({
   serverAdapter,
   navigationProvider,
   screenshotProvider,
+  keepAwakeProvider,
   routeProvider,
   cloudRelayConfig,
   enableMdnsAnnounce,
@@ -4707,6 +4848,9 @@ function UIBridgeNativeProvider({
     if (screenshotProvider) {
       server.setScreenshotProvider(screenshotProvider);
     }
+    if (keepAwakeProvider) {
+      server.setKeepAwakeProvider(keepAwakeProvider);
+    }
     if (routeProvider) {
       server.setRouteProvider(routeProvider);
     }
@@ -4760,6 +4904,7 @@ function UIBridgeNativeProvider({
     serverAdapter,
     navigationProvider,
     screenshotProvider,
+    keepAwakeProvider,
     routeProvider
   ]);
   const stopServer = react.useCallback(() => {
@@ -4793,6 +4938,7 @@ function UIBridgeNativeProvider({
           });
           if (navigationProvider) bareServer.setNavigationProvider(navigationProvider);
           if (screenshotProvider) bareServer.setScreenshotProvider(screenshotProvider);
+          if (keepAwakeProvider) bareServer.setKeepAwakeProvider(keepAwakeProvider);
           if (routeProvider) bareServer.setRouteProvider(routeProvider);
           serverRef.current = bareServer;
         } catch (err) {
@@ -4967,6 +5113,24 @@ function flattenStateStyles(stateStyles) {
   if (stateStyles.disabled != null) result.disabled = flattenStyle(stateStyles.disabled);
   return Object.keys(result).length > 0 ? result : void 0;
 }
+var warnedDeadButtonIds = /* @__PURE__ */ new Set();
+function scheduleDeadButtonWarning(bridge, id, type) {
+  if (type !== "button" && type !== "pressable") return;
+  if (warnedDeadButtonIds.has(id)) return;
+  if (!bridge) return;
+  setTimeout(() => {
+    if (warnedDeadButtonIds.has(id)) return;
+    const element = bridge.registry.getElement(id);
+    if (!element) return;
+    const props = element.props ?? {};
+    const hasPress = typeof props.onPress === "function" || typeof props.onPressIn === "function" || typeof props.onResponderRelease === "function";
+    if (hasPress) return;
+    warnedDeadButtonIds.add(id);
+    console.warn(
+      `[UI Bridge] Registered \`${type}\` element "${id}" without an \`onPress\` handler \u2014 UI Bridge \`press\` actions on this element will fail with "No press handler found on element". Use \`useUIElementWithProps\` and \`captureProps({onPress})\` instead.`
+    );
+  }, 0);
+}
 function useUIElement(options) {
   const bridge = useUIBridgeNativeOptional();
   const ref = react.useRef(null);
@@ -5013,6 +5177,7 @@ function useUIElement(options) {
     registeredRef.current = true;
     registeredIdRef.current = id;
     setRegistered(true);
+    scheduleDeadButtonWarning(bridge, id, type);
   }, [bridge, id, type, label, actions, customActions, treePath, style, stateStylesProp]);
   const unregister = react.useCallback(() => {
     if (!bridge || !registeredRef.current) return;
@@ -5072,30 +5237,42 @@ function useUIElement(options) {
     const node = ref.current;
     if (!node || typeof node.measureInWindow !== "function") return;
     let cancelled = false;
-    node.measureInWindow((pageX, pageY, w, h) => {
-      if (cancelled) return;
-      if (w <= 0 || h <= 0) return;
-      const newLayout = {
-        x: pageX,
-        y: pageY,
-        width: w,
-        height: h,
-        pageX,
-        pageY
-      };
-      setLayout(newLayout);
-      const newState = {
-        mounted: true,
-        visible: true,
-        enabled: true,
-        focused: false,
-        layout: newLayout
-      };
-      bridge.registry.updateElementState(id, newState);
-      onStateChangeRef.current?.(newState);
-    });
+    let pendingTimer = null;
+    const backoffMs = [50, 200, 500, 1e3, 2500];
+    let attempt = 0;
+    const tryMeasure = () => {
+      if (cancelled || !node.measureInWindow) return;
+      node.measureInWindow((pageX, pageY, w, h) => {
+        if (cancelled) return;
+        if (w > 0 && h > 0) {
+          const newLayout = {
+            x: pageX,
+            y: pageY,
+            width: w,
+            height: h,
+            pageX,
+            pageY
+          };
+          setLayout(newLayout);
+          const newState = {
+            mounted: true,
+            visible: true,
+            enabled: true,
+            focused: false,
+            layout: newLayout
+          };
+          bridge.registry.updateElementState(id, newState);
+          onStateChangeRef.current?.(newState);
+          return;
+        }
+        if (attempt >= backoffMs.length) return;
+        pendingTimer = setTimeout(tryMeasure, backoffMs[attempt++]);
+      });
+    };
+    tryMeasure();
     return () => {
       cancelled = true;
+      if (pendingTimer != null) clearTimeout(pendingTimer);
     };
   }, [bridge, registered, id]);
   const registeredHandlerKeysRef = react.useRef([]);