@qontinui/ui-bridge-native 0.1.6 → 0.2.0

package/dist/react/{useAutoRegister.d.ts → index.d.mts}

@@ -1,3 +1,12 @@
+export { b as ComponentActionDef, c as ComponentActionRequest, d as ComponentActionResponse, h as ToastRecorderInput, U as UIBridgeNativeContextValue, i as UIBridgeNativeProvider, j as UIBridgeNativeProviderProps, k as UIBridgeProps, n as UseUIBridgeModalOptions, o as UseUIBridgeReturn, p as UseUIBridgeToastOptions, q as UseUIComponentOptions, r as UseUIComponentReturn, s as UseUIElementOptions, t as UseUIElementReturn, u as UseUIElementWithPropsReturn, v as useToastRecorder, w as useUIBridge, x as useUIBridgeModal, y as useUIBridgeNative, z as useUIBridgeNativeOptional, B as useUIBridgeNativeRequired, E as useUIBridgeRequired, F as useUIBridgeToast, G as useUIComponent, H as useUIComponentAction, I as useUIElement, J as useUIElementWithProps } from '../useUIBridgeToast-GmT1TzUe.mjs';
+import { j as NativeElementRef } from '../types-Oz13YLZq.mjs';
+import { b as RegisterElementOptions } from '../registry-Cahd8Gn2.mjs';
+import 'react/jsx-runtime';
+import 'react';
+import '../types-DAfCeWXc.mjs';
+import '../http-server-DCdR8WlL.mjs';
+import '../design-types-BHr6Q1FX.mjs';
+
 /**
  * useAutoRegister Hook for React Native
  *
@@ -9,12 +18,11 @@
  * 1. Use this hook at the app root to enable the registry
  * 2. Use useUIElement on interactive components (or wrap with Pressable/TouchableOpacity)
  */
-import type { NativeElementRef } from '../core/types';
-import type { RegisterElementOptions } from '../core/registry';
+
 /**
  * Options for auto-registration in React Native
  */
-export interface NativeAutoRegisterOptions {
+interface NativeAutoRegisterOptions {
     /** Enable auto-registration (default: true in dev mode) */
     enabled?: boolean;
     /** Callback when element is registered */
@@ -25,7 +33,7 @@ export interface NativeAutoRegisterOptions {
 /**
  * Handle returned by useAutoRegister for programmatic registration
  */
-export interface NativeAutoRegisterHandle {
+interface NativeAutoRegisterHandle {
     /** Register an element programmatically */
     register: (id: string, ref: React.RefObject<NativeElementRef>, options?: RegisterElementOptions) => void;
     /** Unregister an element programmatically */
@@ -59,6 +67,6 @@ export interface NativeAutoRegisterHandle {
  * }
  * ```
  */
-export declare function useAutoRegister(options?: NativeAutoRegisterOptions): NativeAutoRegisterHandle;
-export default useAutoRegister;
-//# sourceMappingURL=useAutoRegister.d.ts.map
+declare function useAutoRegister(options?: NativeAutoRegisterOptions): NativeAutoRegisterHandle;
+
+export { type NativeAutoRegisterHandle, type NativeAutoRegisterOptions, useAutoRegister };

package/dist/react/index.d.ts

@@ -1,11 +1,72 @@
+export { b as ComponentActionDef, c as ComponentActionRequest, d as ComponentActionResponse, h as ToastRecorderInput, U as UIBridgeNativeContextValue, i as UIBridgeNativeProvider, j as UIBridgeNativeProviderProps, k as UIBridgeProps, n as UseUIBridgeModalOptions, o as UseUIBridgeReturn, p as UseUIBridgeToastOptions, q as UseUIComponentOptions, r as UseUIComponentReturn, s as UseUIElementOptions, t as UseUIElementReturn, u as UseUIElementWithPropsReturn, v as useToastRecorder, w as useUIBridge, x as useUIBridgeModal, y as useUIBridgeNative, z as useUIBridgeNativeOptional, B as useUIBridgeNativeRequired, E as useUIBridgeRequired, F as useUIBridgeToast, G as useUIComponent, H as useUIComponentAction, I as useUIElement, J as useUIElementWithProps } from '../useUIBridgeToast-D32KXyL1.js';
+import { j as NativeElementRef } from '../types-Oz13YLZq.js';
+import { b as RegisterElementOptions } from '../registry-z-3WJsxp.js';
+import 'react/jsx-runtime';
+import 'react';
+import '../types-ajakyp-l.js';
+import '../http-server-Dj3grQW4.js';
+import '../design-types-BHr6Q1FX.js';
+
 /**
- * UI Bridge Native - React
+ * useAutoRegister Hook for React Native
  *
- * React hooks and provider for React Native.
+ * 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 />;
+ * }
+ * ```
  */
-export * from './UIBridgeNativeProvider';
-export * from './useUIElement';
-export * from './useUIComponent';
-export * from './useUIBridge';
-export * from './useAutoRegister';
-//# sourceMappingURL=index.d.ts.map
+declare function useAutoRegister(options?: NativeAutoRegisterOptions): NativeAutoRegisterHandle;
+
+export { type NativeAutoRegisterHandle, type NativeAutoRegisterOptions, useAutoRegister };

package/dist/react/index.js

@@ -55,9 +55,34 @@ 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();
     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 };
+  }
+  /**
+   * 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
   // ============================================================================
   /**
@@ -420,7 +445,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);
@@ -452,6 +477,49 @@ var NativeUIBridgeRegistry = class {
       currentRoute: routeInfo?.currentRoute ?? null,
       segments: routeInfo?.segments
     };
+    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
@@ -545,6 +613,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
@@ -558,11 +643,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
         };
       }
@@ -570,33 +667,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
       };
@@ -3514,6 +3645,186 @@ 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);
+  }
+  dismissModal(id) {
+    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 = react.createContext(null);
 function UIBridgeNativeProvider({
   children,
@@ -3530,6 +3841,9 @@ function UIBridgeNativeProvider({
 }) {
   const registryRef = react.useRef(null);
   const executorRef = react.useRef(null);
+  const modalDetectorRef = react.useRef(null);
+  const toastCaptureRef = react.useRef(null);
+  const undoTrackerRef = react.useRef(null);
   const [serverRunning, setServerRunning] = react.useState(false);
   if (!registryRef.current) {
     registryRef.current = new NativeUIBridgeRegistry({
@@ -3543,6 +3857,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 = react.useRef(null);
   const eventBridgeRef = react.useRef(null);
   const announcerRef = react.useRef(null);
@@ -3731,6 +4051,22 @@ function UIBridgeNativeProvider({
       lastRoute = current;
     });
   }, [routeProvider, registry]);
+  react.useEffect(() => {
+    registry.setEnrichers({ modalDetector, toastCapture, undoTracker });
+  }, [registry, modalDetector, toastCapture, undoTracker]);
+  react.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 = react.useCallback(
     (type, listener) => registry.on(type, listener),
     [registry]
@@ -3745,6 +4081,9 @@ function UIBridgeNativeProvider({
       config,
       registry,
       executor,
+      modalDetector,
+      toastCapture,
+      undoTracker,
       getElements,
       getComponents,
       createSnapshot,
@@ -3761,6 +4100,9 @@ function UIBridgeNativeProvider({
       config,
       registry,
       executor,
+      modalDetector,
+      toastCapture,
+      undoTracker,
       getElements,
       getComponents,
       createSnapshot,
@@ -4278,14 +4620,48 @@ function useAutoRegister(options = {}) {
     isEnabled: enabled && !!bridge?.registry
   };
 }
+function useUIBridgeModal(opts) {
+  const { modalDetector } = useUIBridgeNative();
+  const { id, title, type, blocking, dismissible } = opts;
+  react.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;
+  react.useEffect(() => {
+    toastCapture.recordToast({ id, message, level });
+    return () => {
+      toastCapture.dismissToast(id);
+    };
+  }, [toastCapture, id, message, level]);
+}
+function useToastRecorder() {
+  const { toastCapture } = useUIBridgeNative();
+  const recordToast = react.useCallback(
+    (toast) => {
+      toastCapture.recordToast(toast);
+    },
+    [toastCapture]
+  );
+  const dismissToast = react.useCallback((id) => toastCapture.dismissToast(id), [toastCapture]);
+  return { recordToast, dismissToast };
+}
 
 exports.UIBridgeNativeProvider = UIBridgeNativeProvider;
 exports.useAutoRegister = useAutoRegister;
+exports.useToastRecorder = useToastRecorder;
 exports.useUIBridge = useUIBridge;
+exports.useUIBridgeModal = useUIBridgeModal;
 exports.useUIBridgeNative = useUIBridgeNative;
 exports.useUIBridgeNativeOptional = useUIBridgeNativeOptional;
 exports.useUIBridgeNativeRequired = useUIBridgeNativeRequired;
 exports.useUIBridgeRequired = useUIBridgeRequired;
+exports.useUIBridgeToast = useUIBridgeToast;
 exports.useUIComponent = useUIComponent;
 exports.useUIComponentAction = useUIComponentAction;
 exports.useUIElement = useUIElement;