@qontinui/ui-bridge-native 0.1.6 → 0.2.1

package/dist/{core/types.d.ts → types-BwdPNpII.d.mts}

@@ -5,7 +5,7 @@
  * Adapted from ui-bridge for React Native environments.
  */
 type AnyNativeElement = any;
-export interface WaitOptions {
+interface WaitOptions {
     /** Wait for element to be visible */
     visible?: boolean;
     /** Wait for element to be enabled */
@@ -19,22 +19,22 @@ export interface WaitOptions {
     /** Polling interval in milliseconds */
     interval?: number;
 }
-export type ActionHandler<TParams = unknown, TResult = unknown> = (params?: TParams) => TResult | Promise<TResult>;
-export interface CustomAction<TParams = unknown, TResult = unknown> {
+type ActionHandler<TParams = unknown, TResult = unknown> = (params?: TParams) => TResult | Promise<TResult>;
+interface CustomAction<TParams = unknown, TResult = unknown> {
     id: string;
     label?: string;
     description?: string;
     handler: ActionHandler<TParams, TResult>;
 }
-export interface ComponentAction<TParams = unknown, TResult = unknown> {
+interface ComponentAction<TParams = unknown, TResult = unknown> {
     id: string;
     label?: string;
     description?: string;
     paramSchema?: Record<string, unknown>;
     handler: ActionHandler<TParams, TResult>;
 }
-export type WorkflowStepType = 'element-action' | 'component-action' | 'wait' | 'assert' | 'navigate' | 'branch' | 'loop' | 'extract' | 'log' | 'custom';
-export interface WorkflowStep {
+type WorkflowStepType = 'element-action' | 'component-action' | 'wait' | 'assert' | 'navigate' | 'branch' | 'loop' | 'extract' | 'log' | 'custom';
+interface WorkflowStep {
     id: string;
     type: WorkflowStepType;
     target?: string;
@@ -43,29 +43,29 @@ export interface WorkflowStep {
     waitOptions?: WaitOptions;
     handler?: () => unknown | Promise<unknown>;
 }
-export interface Workflow {
+interface Workflow {
     id: string;
     name: string;
     description?: string;
     steps: WorkflowStep[];
     defaultParams?: Record<string, unknown>;
 }
-export type BridgeEventType = 'element:registered' | 'element:unregistered' | 'element:stateChanged' | 'component:registered' | 'component:unregistered' | 'action:started' | 'action:completed' | 'action:failed' | 'workflow:started' | 'workflow:stepCompleted' | 'workflow:completed' | 'workflow:failed' | 'render:snapshot' | 'error';
-export interface BridgeEvent<T = unknown> {
+type BridgeEventType = 'element:registered' | 'element:unregistered' | 'element:stateChanged' | 'component:registered' | 'component:unregistered' | 'action:started' | 'action:completed' | 'action:failed' | 'workflow:started' | 'workflow:stepCompleted' | 'workflow:completed' | 'workflow:failed' | 'render:snapshot' | 'error';
+interface BridgeEvent<T = unknown> {
     type: BridgeEventType;
     timestamp: number;
     data: T;
 }
-export type BridgeEventListener<T = unknown> = (event: BridgeEvent<T>) => void;
+type BridgeEventListener<T = unknown> = (event: BridgeEvent<T>) => void;
 /**
  * React Native element reference type.
  * Uses a generic type to avoid conflicts between different react-native versions.
  */
-export type NativeElementRef = AnyNativeElement | null;
+type NativeElementRef = AnyNativeElement | null;
 /**
  * Element identification for React Native (replaces XPath/CSS selectors)
  */
-export interface NativeElementIdentifier {
+interface NativeElementIdentifier {
     /** Explicit UI Bridge identifier */
     uiId?: string;
     /** React Native testID prop */
@@ -82,7 +82,7 @@ export interface NativeElementIdentifier {
 /**
  * Layout information from onLayout callback
  */
-export interface NativeLayout {
+interface NativeLayout {
     /** X position relative to parent */
     x: number;
     /** Y position relative to parent */
@@ -99,7 +99,7 @@ export interface NativeLayout {
 /**
  * Current state of a native UI element
  */
-export interface NativeElementState {
+interface NativeElementState {
     /** Whether the element is mounted in the tree */
     mounted: boolean;
     /** Whether the element is visible on screen */
@@ -130,15 +130,15 @@ export interface NativeElementState {
 /**
  * Types of native UI elements that can be registered
  */
-export type NativeElementType = 'button' | 'input' | 'text' | 'view' | 'scroll' | 'list' | 'listItem' | 'switch' | 'checkbox' | 'radio' | 'image' | 'touchable' | 'pressable' | 'modal' | 'custom';
+type NativeElementType = 'button' | 'input' | 'text' | 'view' | 'scroll' | 'list' | 'listItem' | 'switch' | 'checkbox' | 'radio' | 'image' | 'touchable' | 'pressable' | 'modal' | 'custom';
 /**
  * Standard actions available on native elements
  */
-export type NativeStandardAction = 'press' | 'click' | 'longPress' | 'doubleTap' | 'type' | 'clear' | 'focus' | 'blur' | 'scroll' | 'swipe' | 'toggle';
+type NativeStandardAction = 'press' | 'click' | 'longPress' | 'doubleTap' | 'type' | 'clear' | 'focus' | 'blur' | 'scroll' | 'swipe' | 'toggle';
 /**
  * Custom action definition for native elements
  */
-export interface NativeCustomAction<TParams = unknown, TResult = unknown> {
+interface NativeCustomAction<TParams = unknown, TResult = unknown> {
     /** Action identifier */
     id: string;
     /** Human-readable label */
@@ -151,7 +151,7 @@ export interface NativeCustomAction<TParams = unknown, TResult = unknown> {
 /**
  * A native UI element registered with the bridge
  */
-export interface RegisteredNativeElement {
+interface RegisteredNativeElement {
     /** Unique identifier for this element */
     id: string;
     /** Reference to the native element */
@@ -188,7 +188,7 @@ export interface RegisteredNativeElement {
 /**
  * Component action definition for native components
  */
-export interface NativeComponentAction<TParams = unknown, TResult = unknown> {
+interface NativeComponentAction<TParams = unknown, TResult = unknown> {
     /** Action identifier */
     id: string;
     /** Human-readable label */
@@ -203,7 +203,7 @@ export interface NativeComponentAction<TParams = unknown, TResult = unknown> {
 /**
  * A native component registered with the bridge (higher-level than elements)
  */
-export interface RegisteredNativeComponent {
+interface RegisteredNativeComponent {
     /** Unique identifier for this component */
     id: string;
     /** Human-readable name */
@@ -222,7 +222,7 @@ export interface RegisteredNativeComponent {
 /**
  * Action request for native elements
  */
-export interface NativeActionRequest {
+interface NativeActionRequest {
     /** Action to execute */
     action: NativeStandardAction | string;
     /** Action parameters */
@@ -247,7 +247,7 @@ export interface NativeActionRequest {
 /**
  * Response from a native action execution
  */
-export interface NativeActionResponse {
+interface NativeActionResponse {
     /** Whether the action succeeded */
     success: boolean;
     /** Element state after the action */
@@ -267,10 +267,28 @@ export interface NativeActionResponse {
     /** Time spent waiting for conditions */
     waitDurationMs?: number;
 }
+/**
+ * Registration coverage metadata. Lets automation agents detect routes that
+ * have interactive controls but never registered any of them with the bridge,
+ * without having to read source code.
+ *
+ * - `totalRegistered`: number of elements currently in the registry.
+ * - `everHadRegistrations`: sticks `true` once any element is registered, even
+ *   after every element has been unregistered. A route that registered then
+ *   unmounted should NOT be reported as "never wired".
+ * - `byRoute`: count of currently-registered elements grouped by
+ *   `registrationRoute`. Elements registered without a route are bucketed
+ *   under `'?'`, which is itself a useful diagnostic signal.
+ */
+interface NativeRegistrationCoverage {
+    totalRegistered: number;
+    everHadRegistrations: boolean;
+    byRoute: Record<string, number>;
+}
 /**
  * Snapshot of the entire native UI bridge state
  */
-export interface NativeBridgeSnapshot {
+interface NativeBridgeSnapshot {
     /** Timestamp of the snapshot */
     timestamp: number;
     /** All registered elements */
@@ -306,20 +324,144 @@ export interface NativeBridgeSnapshot {
     currentRoute?: string | null;
     /** Current route segments (if a RouteProvider is configured) */
     segments?: string[];
+    /** Modal/sheet/drawer context (populated when a modalDetector enricher is registered) */
+    modalStack?: NativeSnapshotModalContext;
+    /** Toast/snackbar context (populated when a toastCapture enricher is registered) */
+    toasts?: NativeSnapshotToastContext;
+    /** Undo/redo context (populated when an undoTracker enricher is registered) */
+    undoRedo?: NativeSnapshotUndoContext;
+    /**
+     * Registration coverage metadata so agents can detect routes that have
+     * interactive controls but did not register them with the bridge.
+     */
+    registration?: NativeRegistrationCoverage;
+}
+/** A single detected modal-like surface (modal, sheet, drawer, popover, alert) */
+interface NativeModalInfo {
+    id: string;
+    title?: string;
+    type: 'modal' | 'sheet' | 'drawer' | 'popover' | 'alertdialog' | 'dialog';
+    /** Whether the modal blocks interaction with the underlying UI */
+    blocking: boolean;
+    /** Whether it can be dismissed by the user (backdrop tap, swipe, esc, etc.) */
+    dismissible: boolean;
+    detectedAt: number;
+}
+/**
+ * Modal context attached to a snapshot. Field names match the web SDK's
+ * `SnapshotModalContext` so external agents can write transport-agnostic checks
+ * like `snapshot.modalStack?.hasBlockingModal`.
+ */
+interface NativeSnapshotModalContext {
+    modals: NativeModalInfo[];
+    topModal?: NativeModalInfo;
+    hasBlockingModal: boolean;
+    count: number;
+}
+/** A captured toast/snackbar */
+interface NativeCapturedToast {
+    id: string;
+    message: string;
+    level: 'info' | 'success' | 'warning' | 'error' | 'loading' | 'unknown';
+    appearedAt: number;
+    dismissedAt?: number;
+    visible: boolean;
+    /** Total duration in ms (lifetime so far if still visible, total if dismissed) */
+    durationMs: number;
+}
+/** Toast context attached to a snapshot */
+interface NativeSnapshotToastContext {
+    /** Toasts currently on screen */
+    active: NativeCapturedToast[];
+    /** Recently-dismissed toasts retained by the capture buffer (most recent first) */
+    recent: NativeCapturedToast[];
+    /** Total number of toasts ever captured by this tracker */
+    totalCaptured: number;
 }
+/**
+ * Undo/redo context attached to a snapshot. Mirrors the web SDK's
+ * `SnapshotUndoContext` minus DOM-only fields — RN has no `document.execCommand`
+ * or selectors, so the native variant relies entirely on developer declaration.
+ */
+interface NativeSnapshotUndoContext {
+    /** Whether undo appears to be available */
+    canUndo: boolean;
+    /** Whether redo appears to be available */
+    canRedo: boolean;
+    /** Description of what undo would reverse */
+    undoDescription?: string;
+    /** Description of what redo would restore */
+    redoDescription?: string;
+    /** Undo stack depth (if known) */
+    undoDepth?: number;
+    /** Redo stack depth (if known) */
+    redoDepth?: number;
+    /** Human-readable summary for AI */
+    summary: string;
+}
+/**
+ * Modal-stack tracker contract. Surfaced in NativeSnapshotEnrichers so the
+ * test-hook HTTP endpoints (`control/modal/push`, `control/modal/dismiss/:id`)
+ * can drive the same instance the snapshot reads from. Any duck-typed
+ * implementation that satisfies this shape can fill the slot — production
+ * uses the `ModalDetector` class.
+ */
+interface NativeModalDetectorLike {
+    getSnapshotModalContext(): NativeSnapshotModalContext;
+    pushModal(modal: {
+        id: string;
+        title?: string;
+        type?: NativeModalInfo['type'];
+        blocking?: boolean;
+        dismissible?: boolean;
+    }): void;
+    dismissModal(id: string): boolean | void;
+    getActive(): NativeModalInfo[];
+}
+/**
+ * Canonical enricher slot. Each tracker exposes a `getSnapshot*Context()` method
+ * that the registry calls during `createSnapshot`. NavigationTracker is intentionally
+ * NOT here — route info already flows through `currentRoute` / `segments`.
+ */
+interface NativeSnapshotEnrichers {
+    modalDetector?: NativeModalDetectorLike;
+    toastCapture?: {
+        getSnapshotToastContext(): NativeSnapshotToastContext;
+    };
+    undoTracker?: {
+        getSnapshotUndoContext(): NativeSnapshotUndoContext;
+    };
+}
+/**
+ * Pluggable snapshot enricher: receives base context and returns extra fields
+ * that get `Object.assign`ed onto the snapshot. Used for ad-hoc/custom trackers
+ * (e.g. runner sidebar tabs) without growing the canonical enricher set.
+ */
+type NativeSnapshotEnricher = (ctx: {
+    elements: RegisteredNativeElement[];
+    currentRoute: string | null;
+}) => Record<string, unknown>;
 /**
  * UI Bridge Native feature flags
  */
-export interface NativeUIBridgeFeatures {
+interface NativeUIBridgeFeatures {
     /** Enable HTTP control server */
     server?: boolean;
     /** Enable debug tools (inspector overlay) */
     debug?: boolean;
+    /**
+     * Enable test-only HTTP endpoints that let external runners drive
+     * registry-internal state (currently `control/modal/push` and
+     * `control/modal/dismiss/:id`). Default `false` so production builds
+     * cannot have their modal stack manipulated remotely; set to `true`
+     * (typically gated on `__DEV__`) when running automated tests.
+     */
+    testHooks?: boolean;
 }
 /**
  * UI Bridge Native configuration
  */
-export interface NativeUIBridgeConfig {
+interface NativeUIBridgeConfig {
     /** Port for HTTP server */
     serverPort?: number;
     /** Enable verbose logging */
@@ -337,7 +479,7 @@ export interface NativeUIBridgeConfig {
 /**
  * Find request for discovering native elements
  */
-export interface NativeFindRequest {
+interface NativeFindRequest {
     /** Filter by element type */
     types?: NativeElementType[];
     /** Filter by testID pattern (supports wildcards) */
@@ -352,7 +494,7 @@ export interface NativeFindRequest {
 /**
  * Discovered native element
  */
-export interface DiscoveredNativeElement {
+interface DiscoveredNativeElement {
     /** Element ID */
     id: string;
     /** Element type */
@@ -369,7 +511,7 @@ export interface DiscoveredNativeElement {
 /**
  * Find response
  */
-export interface NativeFindResponse {
+interface NativeFindResponse {
     /** Discovered elements */
     elements: DiscoveredNativeElement[];
     /** Total count */
@@ -379,5 +521,5 @@ export interface NativeFindResponse {
     /** Timestamp */
     timestamp: number;
 }
-export {};
-//# sourceMappingURL=types.d.ts.map
+
+export type { ActionHandler as A, BridgeEvent as B, ComponentAction as C, DiscoveredNativeElement as D, Workflow as E, WorkflowStep as F, WorkflowStepType as G, NativeModalDetectorLike as H, NativeActionRequest as N, RegisteredNativeComponent as R, WaitOptions as W, BridgeEventListener as a, BridgeEventType as b, CustomAction as c, NativeActionResponse as d, NativeBridgeSnapshot as e, NativeCapturedToast as f, NativeComponentAction as g, NativeCustomAction as h, NativeElementIdentifier as i, NativeElementRef as j, NativeElementState as k, NativeElementType as l, NativeFindRequest as m, NativeFindResponse as n, NativeLayout as o, NativeModalInfo as p, NativeRegistrationCoverage as q, NativeSnapshotEnricher as r, NativeSnapshotEnrichers as s, NativeSnapshotModalContext as t, NativeSnapshotToastContext as u, NativeSnapshotUndoContext as v, NativeStandardAction as w, NativeUIBridgeConfig as x, NativeUIBridgeFeatures as y, RegisteredNativeElement as z };