@qontinui/ui-bridge-native 0.1.5 → 0.2.0

package/dist/{registry-DhbGbl9c.d.mts → registry-Cahd8Gn2.d.mts}

@@ -1,4 +1,4 @@
-import { a as BridgeEventListener, i as NativeElementRef, k as NativeElementType, o as NativeStandardAction, g as NativeCustomAction, r as RegisteredNativeElement, j as NativeElementState, R as RegisteredNativeComponent, s as Workflow, b as BridgeEventType, e as NativeBridgeSnapshot } from './types-BPNuYxDx.mjs';
+import { a as BridgeEventListener, r as NativeSnapshotEnrichers, q as NativeSnapshotEnricher, j as NativeElementRef, l as NativeElementType, v as NativeStandardAction, h as NativeCustomAction, y as RegisteredNativeElement, k as NativeElementState, R as RegisteredNativeComponent, z as Workflow, b as BridgeEventType, e as NativeBridgeSnapshot } from './types-Oz13YLZq.mjs';
 
 /**
  * Native Element and Component Registry
@@ -67,7 +67,22 @@ declare class NativeUIBridgeRegistry {
     private workflows;
     private eventListeners;
     private config;
+    private enrichers;
+    private snapshotExtras;
     constructor(config?: NativeRegistryConfig);
+    /**
+     * Register/replace canonical enrichers (modal/toast/undo). HMR-safe — calling
+     * with a partial set merges into existing slots instead of clobbering them.
+     */
+    setEnrichers(e: Partial<NativeSnapshotEnrichers>): void;
+    /**
+     * 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: string, fn: NativeSnapshotEnricher): () => void;
+    /** Remove a custom snapshot enricher by name */
+    unregisterSnapshotEnricher(name: string): void;
     /**
      * Register a native element
      */

package/dist/{registry-B8A_EoxS.d.ts → registry-z-3WJsxp.d.ts}

@@ -1,4 +1,4 @@
-import { a as BridgeEventListener, i as NativeElementRef, k as NativeElementType, o as NativeStandardAction, g as NativeCustomAction, r as RegisteredNativeElement, j as NativeElementState, R as RegisteredNativeComponent, s as Workflow, b as BridgeEventType, e as NativeBridgeSnapshot } from './types-BPNuYxDx.js';
+import { a as BridgeEventListener, r as NativeSnapshotEnrichers, q as NativeSnapshotEnricher, j as NativeElementRef, l as NativeElementType, v as NativeStandardAction, h as NativeCustomAction, y as RegisteredNativeElement, k as NativeElementState, R as RegisteredNativeComponent, z as Workflow, b as BridgeEventType, e as NativeBridgeSnapshot } from './types-Oz13YLZq.js';
 
 /**
  * Native Element and Component Registry
@@ -67,7 +67,22 @@ declare class NativeUIBridgeRegistry {
     private workflows;
     private eventListeners;
     private config;
+    private enrichers;
+    private snapshotExtras;
     constructor(config?: NativeRegistryConfig);
+    /**
+     * Register/replace canonical enrichers (modal/toast/undo). HMR-safe — calling
+     * with a partial set merges into existing slots instead of clobbering them.
+     */
+    setEnrichers(e: Partial<NativeSnapshotEnrichers>): void;
+    /**
+     * 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: string, fn: NativeSnapshotEnricher): () => void;
+    /** Remove a custom snapshot enricher by name */
+    unregisterSnapshotEnricher(name: string): void;
     /**
      * Register a native element
      */

package/dist/server/index.d.mts

@@ -1,9 +1,9 @@
-import { h as NativeServerHandlers, b as HandlerContext, A as APIResponse } from '../http-server-D7uVANBU.mjs';
-export { H as HTTPRequest, a as HTTPResponse, c as HandlerFunction, J as JsonRpcBatchRequest, d as JsonRpcBatchResponse, r as JsonRpcClientMessage, e as JsonRpcEvent, f as JsonRpcRequest, g as JsonRpcResponse, s as JsonRpcServerMessage, t as JsonRpcSubscribe, u as JsonRpcUnsubscribe, N as NativeServerConfig, i as NativeUIBridgeServer, j as NavigationProvider, R as RequestHandler, k as RouteDefinition, l as RouteProvider, S as ScreenshotProvider, m as ServerAdapter, U as UI_BRIDGE_NATIVE_ROUTES, W as WebSocketConnection, n as WebSocketEventBridge, o as WebSocketMessageHandler, p as WebSocketServerAdapter, q as createNativeServer, v as isBatchRequest, w as isSubscribe, x as isUnsubscribe } from '../http-server-D7uVANBU.mjs';
-import { a as NativeUIBridgeRegistry } from '../registry-DhbGbl9c.mjs';
-import { N as NativeActionExecutor } from '../types-Bcj7ji97.mjs';
+import { h as NativeServerHandlers, b as HandlerContext, A as APIResponse } from '../http-server-DCdR8WlL.mjs';
+export { H as HTTPRequest, a as HTTPResponse, c as HandlerFunction, J as JsonRpcBatchRequest, d as JsonRpcBatchResponse, r as JsonRpcClientMessage, e as JsonRpcEvent, f as JsonRpcRequest, g as JsonRpcResponse, s as JsonRpcServerMessage, t as JsonRpcSubscribe, u as JsonRpcUnsubscribe, N as NativeServerConfig, i as NativeUIBridgeServer, j as NavigationProvider, R as RequestHandler, k as RouteDefinition, l as RouteProvider, S as ScreenshotProvider, m as ServerAdapter, U as UI_BRIDGE_NATIVE_ROUTES, W as WebSocketConnection, n as WebSocketEventBridge, o as WebSocketMessageHandler, p as WebSocketServerAdapter, q as createNativeServer, v as isBatchRequest, w as isSubscribe, x as isUnsubscribe } from '../http-server-DCdR8WlL.mjs';
+import { a as NativeUIBridgeRegistry } from '../registry-Cahd8Gn2.mjs';
+import { N as NativeActionExecutor } from '../types-DAfCeWXc.mjs';
 import { E as ElementDesignData, S as StateStyles, R as ResponsiveSnapshot } from '../design-types-BHr6Q1FX.mjs';
-import '../types-BPNuYxDx.mjs';
+import '../types-Oz13YLZq.mjs';
 
 /**
  * UI Bridge Native Server Handlers

package/dist/server/index.d.ts

@@ -1,9 +1,9 @@
-import { h as NativeServerHandlers, b as HandlerContext, A as APIResponse } from '../http-server-B7KudcYJ.js';
-export { H as HTTPRequest, a as HTTPResponse, c as HandlerFunction, J as JsonRpcBatchRequest, d as JsonRpcBatchResponse, r as JsonRpcClientMessage, e as JsonRpcEvent, f as JsonRpcRequest, g as JsonRpcResponse, s as JsonRpcServerMessage, t as JsonRpcSubscribe, u as JsonRpcUnsubscribe, N as NativeServerConfig, i as NativeUIBridgeServer, j as NavigationProvider, R as RequestHandler, k as RouteDefinition, l as RouteProvider, S as ScreenshotProvider, m as ServerAdapter, U as UI_BRIDGE_NATIVE_ROUTES, W as WebSocketConnection, n as WebSocketEventBridge, o as WebSocketMessageHandler, p as WebSocketServerAdapter, q as createNativeServer, v as isBatchRequest, w as isSubscribe, x as isUnsubscribe } from '../http-server-B7KudcYJ.js';
-import { a as NativeUIBridgeRegistry } from '../registry-B8A_EoxS.js';
-import { N as NativeActionExecutor } from '../types-BCYWwyVy.js';
+import { h as NativeServerHandlers, b as HandlerContext, A as APIResponse } from '../http-server-Dj3grQW4.js';
+export { H as HTTPRequest, a as HTTPResponse, c as HandlerFunction, J as JsonRpcBatchRequest, d as JsonRpcBatchResponse, r as JsonRpcClientMessage, e as JsonRpcEvent, f as JsonRpcRequest, g as JsonRpcResponse, s as JsonRpcServerMessage, t as JsonRpcSubscribe, u as JsonRpcUnsubscribe, N as NativeServerConfig, i as NativeUIBridgeServer, j as NavigationProvider, R as RequestHandler, k as RouteDefinition, l as RouteProvider, S as ScreenshotProvider, m as ServerAdapter, U as UI_BRIDGE_NATIVE_ROUTES, W as WebSocketConnection, n as WebSocketEventBridge, o as WebSocketMessageHandler, p as WebSocketServerAdapter, q as createNativeServer, v as isBatchRequest, w as isSubscribe, x as isUnsubscribe } from '../http-server-Dj3grQW4.js';
+import { a as NativeUIBridgeRegistry } from '../registry-z-3WJsxp.js';
+import { N as NativeActionExecutor } from '../types-ajakyp-l.js';
 import { E as ElementDesignData, S as StateStyles, R as ResponsiveSnapshot } from '../design-types-BHr6Q1FX.js';
-import '../types-BPNuYxDx.js';
+import '../types-Oz13YLZq.js';
 
 /**
  * UI Bridge Native Server Handlers

package/dist/server/index.js

@@ -1104,6 +1104,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"] },
@@ -1154,6 +1158,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;
@@ -1170,7 +1255,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,
@@ -1974,6 +2061,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);