@qontinui/ui-bridge-native 0.3.1 → 0.4.0

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

@@ -1,12 +1,3 @@
-export { b as ComponentActionDef, c as ComponentActionRequest, d as ComponentActionResponse, S as State, f as StateAnnotationRequiredElement, g as StateProps, j as ToastRecorderInput, k as TransitionTo, l as TransitionToProps, U as UIBridgeNativeContextValue, m as UIBridgeNativeProvider, n as UIBridgeNativeProviderProps, o as UIBridgeProps, r as UseUIBridgeModalOptions, s as UseUIBridgeReturn, t as UseUIBridgeToastOptions, u as UseUIComponentOptions, v as UseUIComponentReturn, w as UseUIElementOptions, x as UseUIElementReturn, y as UseUIElementWithPropsReturn, z as useToastRecorder, B as useUIBridge, E as useUIBridgeModal, F as useUIBridgeNative, G as useUIBridgeNativeOptional, H as useUIBridgeNativeRequired, I as useUIBridgeRequired, J as useUIBridgeToast, K as useUIComponent, L as useUIComponentAction, N as useUIElement, O as useUIElementWithProps } from '../StateAnnotation-BgFoVWFy.mjs';
-import { j as NativeElementRef } from '../types-CGVut7mc.mjs';
-import { b as RegisterElementOptions } from '../registry-B5JadBN9.mjs';
-import 'react/jsx-runtime';
-import 'react';
-import '../types-B0XA4vOF.mjs';
-import '../http-server--550eD1F.mjs';
-import '../design-types-BHr6Q1FX.mjs';
-
 /**
  * useAutoRegister Hook for React Native
  *
@@ -18,11 +9,12 @@ import '../design-types-BHr6Q1FX.mjs';
  * 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
  */
-interface NativeAutoRegisterOptions {
+export interface NativeAutoRegisterOptions {
     /** Enable auto-registration (default: true in dev mode) */
     enabled?: boolean;
     /** Callback when element is registered */
@@ -33,7 +25,7 @@ interface NativeAutoRegisterOptions {
 /**
  * Handle returned by useAutoRegister for programmatic registration
  */
-interface NativeAutoRegisterHandle {
+export interface NativeAutoRegisterHandle {
     /** Register an element programmatically */
     register: (id: string, ref: React.RefObject<NativeElementRef>, options?: RegisterElementOptions) => void;
     /** Unregister an element programmatically */
@@ -67,6 +59,6 @@ interface NativeAutoRegisterHandle {
  * }
  * ```
  */
-declare function useAutoRegister(options?: NativeAutoRegisterOptions): NativeAutoRegisterHandle;
-
-export { type NativeAutoRegisterHandle, type NativeAutoRegisterOptions, useAutoRegister };
+export declare function useAutoRegister(options?: NativeAutoRegisterOptions): NativeAutoRegisterHandle;
+export default useAutoRegister;
+//# sourceMappingURL=useAutoRegister.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useAutoRegister.d.ts","sourceRoot":"","sources":["../../src/react/useAutoRegister.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,QAAQ,EAAE,CACR,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,gBAAgB,CAAC,EACtC,OAAO,CAAC,EAAE,sBAAsB,KAC7B,IAAI,CAAC;IACV,6CAA6C;IAC7C,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,yBAA8B,GAAG,wBAAwB,CA+DjG;AAED,eAAe,eAAe,CAAC"}

package/dist/react/useUIBridge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * useUIBridge Hook for React Native
+ *
+ * Provides a simplified interface for common UI Bridge operations.
+ */
+import type { NativeActionRequest, NativeActionResponse, NativeFindRequest, NativeFindResponse, NativeBridgeSnapshot, RegisteredNativeElement, RegisteredNativeComponent, Workflow } from '../core/types';
+/**
+ * Component action request
+ */
+export interface ComponentActionRequest {
+    /** Action ID */
+    action: string;
+    /** Action parameters */
+    params?: Record<string, unknown>;
+}
+/**
+ * Component action response
+ */
+export interface ComponentActionResponse {
+    /** Whether the action succeeded */
+    success: boolean;
+    /** Result of the action */
+    result?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * useUIBridge return type
+ */
+export interface UseUIBridgeReturn {
+    /** Whether UI Bridge is available */
+    available: boolean;
+    /** Whether UI Bridge is initialized */
+    initialized: boolean;
+    /** All registered elements */
+    elements: RegisteredNativeElement[];
+    /** All registered components */
+    components: RegisteredNativeComponent[];
+    /** All registered workflows */
+    workflows: Workflow[];
+    /** Create a snapshot of the current state */
+    createSnapshot: () => NativeBridgeSnapshot;
+    /** Execute an action on an element */
+    executeAction: (elementId: string, request: NativeActionRequest) => Promise<NativeActionResponse>;
+    /** Execute a component action */
+    executeComponentAction: (componentId: string, request: ComponentActionRequest) => Promise<ComponentActionResponse>;
+    /** Find elements */
+    find: (request?: NativeFindRequest) => Promise<NativeFindResponse>;
+    /** Get an element by ID */
+    getElement: (id: string) => RegisteredNativeElement | undefined;
+    /** Get a component by ID */
+    getComponent: (id: string) => RegisteredNativeComponent | undefined;
+    /** Get element state by ID */
+    getElementState: (id: string) => ReturnType<RegisteredNativeElement['getState']> | null;
+    /** Register a workflow */
+    registerWorkflow: (workflow: Workflow) => void;
+    /** Unregister a workflow */
+    unregisterWorkflow: (id: string) => void;
+}
+/**
+ * useUIBridge hook
+ *
+ * Provides a simplified interface for accessing UI Bridge functionality.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { available, elements, executeAction, find } = useUIBridge();
+ *
+ *   if (!available) {
+ *     return <Text>UI Bridge not available</Text>;
+ *   }
+ *
+ *   const handlePress = async () => {
+ *     // Find all buttons
+ *     const result = await find({ types: ['button'] });
+ *     console.log('Found buttons:', result.elements);
+ *
+ *     // Execute action on specific element
+ *     await executeAction('submit-btn', { action: 'press' });
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Text>Elements: {elements.length}</Text>
+ *       <Button title="Press" onPress={handlePress} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export declare function useUIBridge(): UseUIBridgeReturn;
+/**
+ * useUIBridgeRequired hook
+ *
+ * Same as useUIBridge but throws if not available.
+ */
+export declare function useUIBridgeRequired(): UseUIBridgeReturn;
+//# sourceMappingURL=useUIBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useUIBridge.d.ts","sourceRoot":"","sources":["../../src/react/useUIBridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,EACzB,QAAQ,EACT,MAAM,eAAe,CAAC;AAGvB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gBAAgB;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,8BAA8B;IAC9B,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IACpC,gCAAgC;IAChC,UAAU,EAAE,yBAAyB,EAAE,CAAC;IACxC,+BAA+B;IAC/B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,oBAAoB,CAAC;IAC3C,sCAAsC;IACtC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAClG,iCAAiC;IACjC,sBAAsB,EAAE,CACtB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,KAC5B,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACtC,oBAAoB;IACpB,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACnE,2BAA2B;IAC3B,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,uBAAuB,GAAG,SAAS,CAAC;IAChE,4BAA4B;IAC5B,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,yBAAyB,GAAG,SAAS,CAAC;IACpE,8BAA8B;IAC9B,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,UAAU,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC;IACxF,0BAA0B;IAC1B,gBAAgB,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IAC/C,4BAA4B;IAC5B,kBAAkB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CA8H/C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,iBAAiB,CAMvD"}

package/dist/react/useUIBridgeModal.d.ts

@@ -0,0 +1,14 @@
+import type { NativeModalInfo } from '../core/types';
+export interface UseUIBridgeModalOptions {
+    id: string;
+    title?: string;
+    type?: NativeModalInfo['type'];
+    blocking?: boolean;
+    dismissible?: boolean;
+}
+/**
+ * Declarative hook: while mounted, registers a modal entry on the active
+ * stack so UI Bridge snapshots reflect that a modal is open.
+ */
+export declare function useUIBridgeModal(opts: UseUIBridgeModalOptions): void;
+//# sourceMappingURL=useUIBridgeModal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useUIBridgeModal.d.ts","sourceRoot":"","sources":["../../src/react/useUIBridgeModal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CAUpE"}

package/dist/react/useUIBridgeToast.d.ts

@@ -0,0 +1,25 @@
+import type { NativeCapturedToast } from '../core/types';
+export interface UseUIBridgeToastOptions {
+    id: string;
+    message: string;
+    level?: NativeCapturedToast['level'];
+}
+/**
+ * Declarative hook: while mounted, surfaces a toast via the snapshot enricher.
+ * Best for explicit-lifecycle toast components.
+ */
+export declare function useUIBridgeToast(opts: UseUIBridgeToastOptions): void;
+export interface ToastRecorderInput {
+    id: string;
+    message: string;
+    level?: NativeCapturedToast['level'];
+}
+/**
+ * Imperative hook: returns a `recordToast` callback for code that fires
+ * toasts outside React (catch blocks, library callbacks, etc.).
+ */
+export declare function useToastRecorder(): {
+    recordToast: (toast: ToastRecorderInput) => void;
+    dismissToast: (id: string) => void;
+};
+//# sourceMappingURL=useUIBridgeToast.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useUIBridgeToast.d.ts","sourceRoot":"","sources":["../../src/react/useUIBridgeToast.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CAUpE;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI;IAClC,WAAW,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACjD,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC,CAUA"}

package/dist/react/useUIComponent.d.ts

@@ -0,0 +1,112 @@
+/**
+ * useUIComponent Hook for React Native
+ *
+ * Register a component with UI Bridge for component-level actions.
+ */
+import type { RegisteredNativeComponent } from '../core/types';
+/**
+ * Action definition for useUIComponent
+ */
+export interface ComponentActionDef<TParams = unknown, TResult = unknown> {
+    /** Action identifier */
+    id: string;
+    /** Human-readable label */
+    label?: string;
+    /** Description */
+    description?: string;
+    /** Handler function */
+    handler: (params?: TParams) => TResult | Promise<TResult>;
+}
+/**
+ * useUIComponent options
+ */
+export interface UseUIComponentOptions {
+    /** Unique identifier for the component */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Actions available on this component */
+    actions?: ComponentActionDef[];
+    /** Child element IDs owned by this component */
+    elementIds?: string[];
+    /** Whether to automatically register on mount */
+    autoRegister?: boolean;
+}
+/**
+ * useUIComponent return value
+ */
+export interface UseUIComponentReturn {
+    /** Whether the component is registered */
+    registered: boolean;
+    /** Execute an action on this component */
+    executeAction: <TParams = unknown, TResult = unknown>(actionId: string, params?: TParams) => Promise<TResult>;
+    /** Manually register the component */
+    register: () => void;
+    /** Manually unregister the component */
+    unregister: () => void;
+    /** Update actions dynamically */
+    updateActions: (actions: ComponentActionDef[]) => void;
+    /** Add an element ID to this component */
+    addElement: (elementId: string) => void;
+    /** Remove an element ID from this component */
+    removeElement: (elementId: string) => void;
+    /** The registered component info */
+    registeredComponent: RegisteredNativeComponent | null;
+}
+/**
+ * useUIComponent hook for React Native
+ *
+ * Registers a component with UI Bridge for component-level control.
+ * Components can expose high-level actions that may orchestrate multiple element interactions.
+ *
+ * @example
+ * ```tsx
+ * function LoginForm() {
+ *   const [email, setEmail] = useState('');
+ *   const [password, setPassword] = useState('');
+ *
+ *   useUIComponent({
+ *     id: 'login-form',
+ *     name: 'Login Form',
+ *     actions: [
+ *       {
+ *         id: 'login',
+ *         label: 'Submit Login',
+ *         handler: async ({ email, password }) => {
+ *           setEmail(email);
+ *           setPassword(password);
+ *           await submitLogin();
+ *         },
+ *       },
+ *       {
+ *         id: 'clear',
+ *         label: 'Clear Form',
+ *         handler: () => {
+ *           setEmail('');
+ *           setPassword('');
+ *         },
+ *       },
+ *     ],
+ *   });
+ *
+ *   return (
+ *     <View>
+ *       <TextInput value={email} onChangeText={setEmail} />
+ *       <TextInput value={password} onChangeText={setPassword} secureTextEntry />
+ *       <Button title="Login" onPress={handleSubmit} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export declare function useUIComponent(options: UseUIComponentOptions): UseUIComponentReturn;
+/**
+ * useUIComponentAction hook
+ *
+ * Create a stable action handler that can be used with useUIComponent.
+ * Useful for memoizing action handlers.
+ */
+export declare function useUIComponentAction<TParams = unknown, TResult = unknown>(handler: (params?: TParams) => TResult | Promise<TResult>, deps: React.DependencyList): (params?: TParams) => TResult | Promise<TResult>;
+//# sourceMappingURL=useUIComponent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useUIComponent.d.ts","sourceRoot":"","sources":["../../src/react/useUIComponent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACtE,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iDAAiD;IACjD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,UAAU,EAAE,OAAO,CAAC;IACpB,0CAA0C;IAC1C,aAAa,EAAE,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAClD,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,OAAO,KACb,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,wCAAwC;IACxC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,iCAAiC;IACjC,aAAa,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,IAAI,CAAC;IACvD,0CAA0C;IAC1C,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,+CAA+C;IAC/C,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,oCAAoC;IACpC,mBAAmB,EAAE,yBAAyB,GAAG,IAAI,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CAoInF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACvE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACzD,IAAI,EAAE,KAAK,CAAC,cAAc,GACzB,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAGlD"}

package/dist/react/useUIElement.d.ts

@@ -0,0 +1,162 @@
+/**
+ * useUIElement Hook for React Native
+ *
+ * Register a native element with UI Bridge for control and observation.
+ */
+import type { NativeElementType, NativeStandardAction, NativeCustomAction, NativeElementState, NativeElementIdentifier, RegisteredNativeElement, NativeElementRef } from '../core/types';
+/**
+ * useUIElement options
+ */
+export interface UseUIElementOptions {
+    /** Unique identifier for the element */
+    id: string;
+    /** Element type (defaults to 'custom') */
+    type?: NativeElementType;
+    /** Human-readable label */
+    label?: string;
+    /** Override available actions */
+    actions?: NativeStandardAction[];
+    /** Custom actions */
+    customActions?: Record<string, NativeCustomAction>;
+    /** Whether to automatically register on mount */
+    autoRegister?: boolean;
+    /** Callback when state changes */
+    onStateChange?: (state: NativeElementState) => void;
+    /** Parent component path for tree path generation */
+    parentPath?: string;
+    /** RN style prop — will be flattened for design review */
+    style?: unknown;
+    /** State-specific style overrides for design review (pressed, focused, disabled) */
+    stateStyles?: {
+        pressed?: unknown;
+        focused?: unknown;
+        disabled?: unknown;
+    };
+    /**
+     * Handler props to auto-register with the bridge for action execution.
+     * When provided, the bridge can invoke these handlers via press/type/toggle actions
+     * without the component needing a separate useEffect + updateElementProps call.
+     *
+     * @example
+     * ```tsx
+     * const { ref, onLayout, bridgeProps } = useUIElement({
+     *   id: 'my-button',
+     *   type: 'pressable',
+     *   handlers: { onPress: handlePress },
+     * });
+     * ```
+     */
+    handlers?: Record<string, ((...args: any[]) => any) | undefined>;
+}
+/**
+ * Bridge props to spread onto the component
+ */
+export interface UIBridgeProps {
+    /** Test ID for automation */
+    testID: string;
+    /** Accessibility label */
+    accessibilityLabel?: string;
+}
+/**
+ * useUIElement return value
+ */
+export interface UseUIElementReturn {
+    /** Ref to attach to the element */
+    ref: React.RefObject<NativeElementRef>;
+    /** onLayout handler to spread onto the element - uses generic type for RN version compatibility */
+    onLayout: (event: {
+        nativeEvent: {
+            layout: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+        };
+    }) => void;
+    /** Props to spread onto the element for identification */
+    bridgeProps: UIBridgeProps;
+    /** Whether the element is registered */
+    registered: boolean;
+    /** Get current state */
+    getState: () => NativeElementState | null;
+    /** Get element identifier */
+    getIdentifier: () => NativeElementIdentifier | null;
+    /** Trigger an action on this element */
+    trigger: (action: NativeStandardAction | string, params?: Record<string, unknown>) => Promise<void>;
+    /** Manually register the element */
+    register: () => void;
+    /** Manually unregister the element */
+    unregister: () => void;
+    /** The registered element info */
+    registeredElement: RegisteredNativeElement | null;
+    /** Update style for design review (flattens and stores in registry) */
+    updateStyle: (style: unknown, stateStyles?: {
+        pressed?: unknown;
+        focused?: unknown;
+        disabled?: unknown;
+    }) => void;
+}
+/**
+ * useUIElement hook for React Native
+ *
+ * Registers a native element with UI Bridge for programmatic control.
+ *
+ * @example
+ * ```tsx
+ * function SubmitButton() {
+ *   const { ref, onLayout, bridgeProps, trigger } = useUIElement({
+ *     id: 'submit-btn',
+ *     type: 'button',
+ *     label: 'Submit Form',
+ *   });
+ *
+ *   return (
+ *     <Pressable
+ *       ref={ref}
+ *       onLayout={onLayout}
+ *       {...bridgeProps}
+ *       onPress={() => handleSubmit()}
+ *     >
+ *       <Text>Submit</Text>
+ *     </Pressable>
+ *   );
+ * }
+ * ```
+ */
+export declare function useUIElement(options: UseUIElementOptions): UseUIElementReturn;
+/**
+ * useUIElementWithProps hook
+ *
+ * Extended version that also captures component props for action execution.
+ * Useful when you need the bridge to be able to call onPress, onChangeText, etc.
+ *
+ * @example
+ * ```tsx
+ * function TextInputField({ onChangeText, value }) {
+ *   const { ref, onLayout, bridgeProps, captureProps } = useUIElementWithProps({
+ *     id: 'email-input',
+ *     type: 'input',
+ *   });
+ *
+ *   // Capture props so bridge can call onChangeText
+ *   captureProps({ onChangeText, value });
+ *
+ *   return (
+ *     <TextInput
+ *       ref={ref}
+ *       onLayout={onLayout}
+ *       {...bridgeProps}
+ *       value={value}
+ *       onChangeText={onChangeText}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export interface UseUIElementWithPropsReturn extends UseUIElementReturn {
+    /** Capture props for action execution */
+    captureProps: (props: Record<string, unknown>) => void;
+}
+export declare function useUIElementWithProps(options: UseUIElementOptions): UseUIElementWithPropsReturn;
+//# sourceMappingURL=useUIElement.d.ts.map

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

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

package/dist/server/design-handlers.d.ts

@@ -0,0 +1,47 @@
+/**
+ * UI Bridge Native Design Review Handlers
+ *
+ * HTTP handlers for the 8 design review endpoints.
+ * Maps registered element styles to the web SDK's design data format.
+ */
+import type { NativeUIBridgeRegistry } from '../core/registry';
+import type { APIResponse, HandlerContext } from './types';
+import type { ElementDesignData, StateStyles, ResponsiveSnapshot } from '../design/design-types';
+/**
+ * Design handler interface (subset of NativeServerHandlers)
+ */
+export interface NativeDesignHandlers {
+    getElementStyles: (ctx: HandlerContext) => Promise<APIResponse<ElementDesignData>>;
+    getElementStateStyles: (ctx: HandlerContext) => Promise<APIResponse<{
+        elementId: string;
+        stateStyles: StateStyles[];
+    }>>;
+    getDesignSnapshot: (ctx: HandlerContext) => Promise<APIResponse<{
+        elements: ElementDesignData[];
+        timestamp: number;
+    }>>;
+    getResponsiveSnapshots: (ctx: HandlerContext) => Promise<APIResponse<ResponsiveSnapshot[]>>;
+    runDesignAudit: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
+    loadStyleGuide: (ctx: HandlerContext) => Promise<APIResponse<{
+        loaded: boolean;
+    }>>;
+    getStyleGuide: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
+    clearStyleGuide: (ctx: HandlerContext) => Promise<APIResponse<{
+        cleared: boolean;
+    }>>;
+    evaluateQuality: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
+    getQualityContexts: (ctx: HandlerContext) => Promise<APIResponse<Array<{
+        name: string;
+        description: string;
+    }>>>;
+    saveBaseline: (ctx: HandlerContext) => Promise<APIResponse<{
+        saved: boolean;
+        elementCount: number;
+    }>>;
+    diffBaseline: (ctx: HandlerContext) => Promise<APIResponse<unknown>>;
+}
+/**
+ * Create design review handlers.
+ */
+export declare function createDesignHandlers(registry: NativeUIBridgeRegistry): NativeDesignHandlers;
+//# sourceMappingURL=design-handlers.d.ts.map

package/dist/server/design-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-handlers.d.ts","sourceRoot":"","sources":["../../src/server/design-handlers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAqDjG;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACnF,qBAAqB,EAAE,CACrB,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,WAAW,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,WAAW,EAAE,CAAA;KAAE,CAAC,CAAC,CAAC;IAC7E,iBAAiB,EAAE,CACjB,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,WAAW,CAAC;QAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAChF,sBAAsB,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;IAC5F,cAAc,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,cAAc,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;IACnF,aAAa,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,eAAe,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;IACrF,eAAe,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,kBAAkB,EAAE,CAClB,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC,CAAC;IACxE,YAAY,EAAE,CACZ,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,WAAW,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACpE,YAAY,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;CACtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,oBAAoB,CAwS3F"}

package/dist/server/handlers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * UI Bridge Native Server Handlers
+ *
+ * Request handlers for the HTTP API endpoints.
+ */
+import { type NativeUIBridgeRegistry } from '../core/registry';
+import type { NativeActionExecutor } from '../control/types';
+import type { NativeServerHandlers } from './types';
+import type { ConsoleErrorBuffer, NetworkRequestBuffer } from './observability';
+/**
+ * Create server handlers
+ */
+export declare function createServerHandlers(registry: NativeUIBridgeRegistry, executor: NativeActionExecutor, config?: {
+    appInfo?: {
+        appId: string;
+        appName: string;
+        appType: string;
+        framework?: string;
+    };
+    /** Optional console-error ring buffer powering `GET /control/console-errors`. */
+    consoleErrorBuffer?: ConsoleErrorBuffer;
+    /** Optional network-request ring buffer powering `GET /sdk/network-requests`. */
+    networkRequestBuffer?: NetworkRequestBuffer;
+}): NativeServerHandlers;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/server/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/server/handlers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,sBAAsB,EAAuB,MAAM,kBAAkB,CAAC;AAQpF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAQV,oBAAoB,EAKrB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AA+PhF;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,EAChC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,CAAC,EAAE;IACP,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C,GACA,oBAAoB,CAqvBtB"}