@qontinui/ui-bridge-native 0.1.5 → 0.1.6

package/dist/react/UIBridgeNativeProvider.d.ts

@@ -0,0 +1,147 @@
+/**
+ * UI Bridge Native Provider
+ *
+ * React context provider for UI Bridge Native functionality.
+ */
+import React from 'react';
+import type { NativeUIBridgeFeatures, NativeUIBridgeConfig, RegisteredNativeElement, RegisteredNativeComponent, NativeBridgeSnapshot, BridgeEventType, BridgeEventListener } from '../core/types';
+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 CloudRelayConfig } from '../transport/CloudRelayClient';
+/**
+ * UI Bridge Native context value
+ */
+export interface UIBridgeNativeContextValue {
+    /** Feature flags */
+    features: NativeUIBridgeFeatures;
+    /** Configuration */
+    config: NativeUIBridgeConfig;
+    /** Element registry */
+    registry: NativeUIBridgeRegistry;
+    /** Action executor */
+    executor: NativeActionExecutor;
+    /** Get all registered elements */
+    getElements: () => RegisteredNativeElement[];
+    /** Get all registered components */
+    getComponents: () => RegisteredNativeComponent[];
+    /** Create a snapshot */
+    createSnapshot: () => NativeBridgeSnapshot;
+    /** Subscribe to events */
+    on: <T = unknown>(type: BridgeEventType, listener: BridgeEventListener<T>) => () => void;
+    /** Unsubscribe from events */
+    off: <T = unknown>(type: BridgeEventType, listener: BridgeEventListener<T>) => void;
+    /** Whether the provider is initialized */
+    initialized: boolean;
+    /** Server running status */
+    serverRunning: boolean;
+    /** Start the HTTP server */
+    startServer: () => Promise<void>;
+    /** Stop the HTTP server */
+    stopServer: () => void;
+    /** Get the current navigation route (if a RouteProvider is configured) */
+    getCurrentRoute: () => string | null;
+}
+/**
+ * UI Bridge Native provider props
+ */
+export interface UIBridgeNativeProviderProps {
+    /** Child components */
+    children: React.ReactNode;
+    /** Feature flags */
+    features?: NativeUIBridgeFeatures;
+    /** Configuration */
+    config?: NativeUIBridgeConfig;
+    /** Event handler */
+    onEvent?: BridgeEventListener;
+    /**
+     * A ServerAdapter instance for the HTTP server.
+     * The app is responsible for creating this using its preferred native TCP/HTTP library.
+     * @see ServerAdapter interface in server/http-server.ts
+     */
+    serverAdapter?: ServerAdapter;
+    /**
+     * Navigation provider for programmatic route navigation via UI Bridge.
+     * Pass Expo Router's push/back functions to enable `control/page/navigate`.
+     */
+    navigationProvider?: {
+        navigate: (url: string) => void;
+        back?: () => void;
+    };
+    /**
+     * Screenshot provider for native screen capture via UI Bridge.
+     * Pass a function that captures the current screen as base64 PNG.
+     */
+    screenshotProvider?: {
+        capture: () => Promise<{
+            base64: string;
+            width: number;
+            height: number;
+        }>;
+    };
+    /**
+     * Route provider for exposing the current navigation route in snapshots.
+     * Wire this to Expo Router's `usePathname()` / `useSegments()` via a module-level ref.
+     */
+    routeProvider?: RouteProvider;
+    /**
+     * Configuration for the cloud relay tunnel (enables remote device verification
+     * when USB/LAN are not available).  Omit `uiBridgeServer` — the provider wires
+     * that automatically after the server starts.
+     */
+    cloudRelayConfig?: Omit<CloudRelayConfig, 'uiBridgeServer'>;
+    /**
+     * Enable mDNS advertisement so that runners on the same LAN can discover this
+     * device automatically (requires react-native-zeroconf).
+     */
+    enableMdnsAnnounce?: boolean;
+    /**
+     * Stable device identifier used for mDNS TXT records and cloud relay
+     * registration.  Typically sourced from expo-device or a UUID stored in
+     * AsyncStorage.
+     */
+    deviceId?: string;
+}
+/**
+ * UI Bridge Native Provider
+ *
+ * Provides UI Bridge Native context to child components.
+ *
+ * @example
+ * ```tsx
+ * // app/_layout.tsx
+ * import { UIBridgeNativeProvider } from 'ui-bridge-native';
+ *
+ * export default function RootLayout() {
+ *   return (
+ *     <UIBridgeNativeProvider
+ *       features={{ server: __DEV__, debug: __DEV__ }}
+ *       config={{ serverPort: 8087 }}
+ *     >
+ *       <Stack>{children}</Stack>
+ *     </UIBridgeNativeProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function UIBridgeNativeProvider({ children, features, config, onEvent, serverAdapter, navigationProvider, screenshotProvider, routeProvider, cloudRelayConfig, enableMdnsAnnounce, deviceId, }: UIBridgeNativeProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * useUIBridgeNative hook
+ *
+ * Access the UI Bridge Native context. Throws if used outside provider.
+ */
+export declare function useUIBridgeNative(): UIBridgeNativeContextValue;
+/**
+ * useUIBridgeNativeOptional hook
+ *
+ * Access the UI Bridge Native context, returning null if outside provider.
+ */
+export declare function useUIBridgeNativeOptional(): UIBridgeNativeContextValue | null;
+/**
+ * useUIBridgeNativeRequired hook
+ *
+ * Alias for useUIBridgeNative (throws if outside provider).
+ */
+export declare const useUIBridgeNativeRequired: typeof useUIBridgeNative;
+//# sourceMappingURL=UIBridgeNativeProvider.d.ts.map

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

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

package/dist/react/index.d.ts

@@ -1,72 +1,11 @@
-export { b as ComponentActionDef, c as ComponentActionRequest, d as ComponentActionResponse, U as UIBridgeNativeContextValue, e as UIBridgeNativeProvider, f as UIBridgeNativeProviderProps, g as UIBridgeProps, h as UseUIBridgeReturn, i as UseUIComponentOptions, j as UseUIComponentReturn, k as UseUIElementOptions, l as UseUIElementReturn, m as UseUIElementWithPropsReturn, u as useUIBridge, n as useUIBridgeNative, o as useUIBridgeNativeOptional, p as useUIBridgeNativeRequired, q as useUIBridgeRequired, r as useUIComponent, s as useUIComponentAction, t as useUIElement, v as useUIElementWithProps } from '../useUIBridge-CDZbWxII.js';
-import { i as NativeElementRef } from '../types-BPNuYxDx.js';
-import { b as RegisterElementOptions } from '../registry-B8A_EoxS.js';
-import 'react/jsx-runtime';
-import 'react';
-import '../types-BCYWwyVy.js';
-import '../http-server-B7KudcYJ.js';
-import '../design-types-BHr6Q1FX.js';
-
 /**
- * useAutoRegister Hook for React Native
+ * UI Bridge Native - React
  *
- * Enables automatic registration of interactive React Native components.
- * Unlike the web version, this doesn't use MutationObserver (no DOM).
- * Instead, it provides a simple API for components to register themselves.
- *
- * For comprehensive coverage in React Native, components should:
- * 1. Use this hook at the app root to enable the registry
- * 2. Use useUIElement on interactive components (or wrap with Pressable/TouchableOpacity)
- */
-
-/**
- * Options for auto-registration in React Native
- */
-interface NativeAutoRegisterOptions {
-    /** Enable auto-registration (default: true in dev mode) */
-    enabled?: boolean;
-    /** Callback when element is registered */
-    onRegister?: (id: string) => void;
-    /** Callback when element is unregistered */
-    onUnregister?: (id: string) => void;
-}
-/**
- * Handle returned by useAutoRegister for programmatic registration
- */
-interface NativeAutoRegisterHandle {
-    /** Register an element programmatically */
-    register: (id: string, ref: React.RefObject<NativeElementRef>, options?: RegisterElementOptions) => void;
-    /** Unregister an element programmatically */
-    unregister: (id: string) => void;
-    /** Check if auto-registration is enabled */
-    isEnabled: boolean;
-}
-/**
- * Hook for enabling automatic element registration in React Native.
- *
- * Since React Native doesn't have a DOM to observe, this hook provides
- * a handle for programmatic registration. For most use cases, you should
- * use useUIElement directly on interactive components.
- *
- * @example
- * ```tsx
- * function App() {
- *   const autoRegister = useAutoRegister({ enabled: __DEV__ });
- *
- *   // Programmatic registration (rare use case)
- *   useEffect(() => {
- *     autoRegister.register('custom-element', {
- *       type: 'button',
- *       label: 'Custom Button',
- *     });
- *
- *     return () => autoRegister.unregister('custom-element');
- *   }, []);
- *
- *   return <YourApp />;
- * }
- * ```
+ * React hooks and provider for React Native.
  */
-declare function useAutoRegister(options?: NativeAutoRegisterOptions): NativeAutoRegisterHandle;
-
-export { type NativeAutoRegisterHandle, type NativeAutoRegisterOptions, useAutoRegister };
+export * from './UIBridgeNativeProvider';
+export * from './useUIElement';
+export * from './useUIComponent';
+export * from './useUIBridge';
+export * from './useAutoRegister';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/react/index.js

@@ -689,7 +689,7 @@ var DefaultNativeActionExecutor = class {
     if (!params?.text) {
       throw new Error("Type action requires text parameter");
     }
-    if (params.clearFirst) {
+    if (params.clearFirst || params.clear) {
       await this.performClear(element, props);
     }
     if (params.delay && params.delay > 0) {
@@ -1875,6 +1875,15 @@ function createServerHandlers(registry, executor, config) {
         timestamp: Date.now(),
         ...stats
       };
+      if (config?.appInfo) {
+        response.uiBridge = {
+          version: "0.3.0",
+          ...config.appInfo,
+          capabilities: ["elements", "components", "actions", "design"],
+          elementCount: stats.elements,
+          componentCount: stats.components
+        };
+      }
       return success2(response);
     }
   };
@@ -1913,6 +1922,10 @@ var WS_ROUTES = [
   { pattern: "health", handler: "health", httpMethods: ["GET"] },
   // Elements
   { pattern: "control/elements", handler: "getElements", httpMethods: ["GET"] },
+  // Flat alias — matches the runner UI Bridge's `/ui-bridge/elements` path so
+  // agents can use the same URL across runner + mobile without remembering
+  // the `control/` prefix. Delegates to the same handler.
+  { pattern: "elements", handler: "getElements", httpMethods: ["GET"] },
   { pattern: "control/element/:id", handler: "getElement", httpMethods: ["GET"] },
   { pattern: "control/element/:id/state", handler: "getElementState", httpMethods: ["GET"] },
   { pattern: "control/element/:id/action", handler: "executeAction", httpMethods: ["POST"] },
@@ -1963,6 +1976,87 @@ var WS_ROUTES = [
   // Meta / Introspection
   { pattern: "meta/methods", handler: "getMethods", httpMethods: ["GET"] }
 ];
+var HANDLER_DESCRIPTIONS = {
+  health: "Liveness probe; returns app metadata + element count",
+  getElements: "Flat list of registered UI elements",
+  getElement: "Single element by id",
+  getElementState: "Dynamic state (value, focused, checked) for one element",
+  executeAction: 'Run an action on an element (see "actions" below for names)',
+  getComponents: "Higher-level components with action schemas",
+  getComponent: "Component detail + per-action paramSchema",
+  executeComponentAction: "Invoke a component action directly (preferred over button clicks)",
+  find: "AI-powered element search by natural-language query",
+  getSnapshot: "Full snapshot: elements + route + state. Supports ?visibleOnly=true and ?currentRouteOnly=true",
+  getWorkflows: "List registered workflows",
+  runWorkflow: "Trigger a workflow by id",
+  pageRefresh: "Reload the current route",
+  pageNavigate: "Imperative router.push(url) \u2014 preferred over tapping tab buttons",
+  pageReplace: "router.replace(url)",
+  pageGoBack: "router.back()",
+  pageGoForward: "router.forward()",
+  getScreenshot: "PNG screenshot of the current screen",
+  getElementStyles: "Computed styles for an element (design review)",
+  getElementStateStyles: "Computed styles per interaction state (hover/focus/disabled)",
+  getDesignSnapshot: "Visual + style snapshot for design review",
+  getResponsiveSnapshots: "Screenshots at multiple viewport widths",
+  runDesignAudit: "Accessibility + visual audit",
+  loadStyleGuide: "Load a design system style guide",
+  getStyleGuide: "Fetch the currently loaded style guide",
+  clearStyleGuide: "Unload the style guide",
+  evaluateQuality: "Score the current UI against a quality context",
+  getQualityContexts: "List available quality evaluation contexts",
+  saveBaseline: "Save a quality baseline snapshot",
+  diffBaseline: "Diff current UI against a saved baseline",
+  getMethods: "List every handler name (legacy introspection)"
+};
+var ACTION_REFERENCE = [
+  { name: "press", aliases: ["click"], params: "PressActionParams (optional position)" },
+  { name: "longPress", params: "PressActionParams (optional position)" },
+  { name: "doubleTap", params: "none" },
+  {
+    name: "type",
+    params: "TypeActionParams { text, delay?, clear? | clearFirst? } \u2014 `clear:true` replaces content atomically"
+  },
+  { name: "clear", params: "none \u2014 empties the input" },
+  { name: "focus", params: "none" },
+  { name: "blur", params: "none" },
+  { name: "scroll", params: "ScrollActionParams { offset? {x,y}, to? }" },
+  { name: "swipe", params: "SwipeActionParams { direction, distance }" },
+  { name: "toggle", params: "none \u2014 flips boolean controls" }
+];
+function buildRoutesPayload() {
+  const entries = [];
+  for (const r of WS_ROUTES) {
+    if (!r.httpMethods) continue;
+    for (const m of r.httpMethods) {
+      entries.push({ method: m, path: `/ui-bridge/${r.pattern}` });
+    }
+  }
+  entries.push({ method: "GET", path: "/ui-bridge/_help" });
+  entries.push({ method: "GET", path: "/ui-bridge/_routes" });
+  entries.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+  return { routes: entries, count: entries.length };
+}
+function buildHelpPayload() {
+  return {
+    version: 1,
+    description: "UI Bridge Native HTTP surface. Prefix every path with /ui-bridge/.",
+    routes: WS_ROUTES.map((r) => ({
+      pattern: r.pattern,
+      httpMethods: r.httpMethods ?? [],
+      wsOnly: !r.httpMethods,
+      handler: r.handler,
+      description: HANDLER_DESCRIPTIONS[r.handler] ?? ""
+    })),
+    actions: ACTION_REFERENCE,
+    tips: [
+      "Start with `GET /ui-bridge/control/snapshot?visibleOnly=true` to see what the user actually sees.",
+      "Prefer `control/component/:id/action/:actionId` over button presses \u2014 typed paramSchema, no button-id guessing.",
+      "Use `pageNavigate` for tab switches instead of pressing tab buttons; gesture state often swallows clicks.",
+      "The `type` action supports `clear:true` to replace existing text atomically in one call."
+    ]
+  };
+}
 var NativeUIBridgeServer = class {
   constructor(registry, executor, config = {}) {
     this.registry = registry;
@@ -1979,7 +2073,9 @@ var NativeUIBridgeServer = class {
       cors: true,
       ...config
     };
-    this.handlers = createServerHandlers(registry, executor);
+    this.handlers = createServerHandlers(registry, executor, {
+      appInfo: this.config.appInfo
+    });
     this.handlers.getMethods = async () => {
       const methods = WS_ROUTES.map((r) => ({
         method: r.pattern,
@@ -2783,6 +2879,20 @@ var NativeUIBridgeServer = class {
       };
     }
     const stripped = path.slice(PREFIX.length);
+    if (method === "GET" && stripped === "_help") {
+      return {
+        success: true,
+        data: buildHelpPayload(),
+        timestamp: Date.now()
+      };
+    }
+    if (method === "GET" && stripped === "_routes") {
+      return {
+        success: true,
+        data: buildRoutesPayload(),
+        timestamp: Date.now()
+      };
+    }
     let patternMatchedButWrongVerb = false;
     for (const route of WS_ROUTES) {
       const pathParams = parsePath(route.pattern, stripped);
@@ -3447,7 +3557,8 @@ function UIBridgeNativeProvider({
     }
     const server = createNativeServer(registry, executor, {
       serverPort: config.serverPort || 8087,
-      cors: true
+      cors: true,
+      appInfo: config.appInfo
     });
     server.setAdapter(serverAdapter);
     if (navigationProvider) {
@@ -3534,7 +3645,8 @@ function UIBridgeNativeProvider({
         try {
           const bareServer = createNativeServer(registry, executor, {
             serverPort: config.serverPort || 8087,
-            cors: true
+            cors: true,
+            appInfo: config.appInfo
           });
           if (navigationProvider) bareServer.setNavigationProvider(navigationProvider);
           if (screenshotProvider) bareServer.setScreenshotProvider(screenshotProvider);