@qontinui/ui-bridge-native 0.6.9 → 0.6.11

package/dist/index.js

@@ -11,6 +11,179 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/core/vision-fields.ts
+var INTERACTIVE_HANDLER_NAMES = /* @__PURE__ */ new Set([
+  "onPress",
+  "onPressIn",
+  "onPressOut",
+  "onLongPress",
+  "onChangeText",
+  "onValueChange",
+  "onChange",
+  "onSubmitEditing",
+  "onClick",
+  "onTouchStart",
+  "onTouchEnd"
+]);
+var INTERACTIVE_TYPES = /* @__PURE__ */ new Set([
+  "button",
+  "input",
+  "switch",
+  "checkbox",
+  "radio",
+  "touchable",
+  "pressable",
+  "listItem"
+]);
+function roleForType(type) {
+  switch (type) {
+    case "button":
+    case "touchable":
+    case "pressable":
+      return "button";
+    case "input":
+      return "textbox";
+    case "text":
+      return "text";
+    case "switch":
+      return "switch";
+    case "checkbox":
+      return "checkbox";
+    case "radio":
+      return "radio";
+    case "image":
+      return "img";
+    case "list":
+      return "list";
+    case "listItem":
+      return "listitem";
+    case "modal":
+      return "dialog";
+    case "scroll":
+    case "view":
+    case "custom":
+    default:
+      return void 0;
+  }
+}
+function deriveInteractable(type, handlerNames) {
+  if (INTERACTIVE_TYPES.has(type)) return true;
+  if (handlerNames) {
+    for (const name of handlerNames) {
+      if (INTERACTIVE_HANDLER_NAMES.has(name)) return true;
+    }
+  }
+  return false;
+}
+function deriveText(state, label) {
+  const candidates = [state.value, state.textContent, label];
+  for (const c of candidates) {
+    if (typeof c === "string") {
+      const trimmed = c.trim();
+      if (trimmed.length > 0) return trimmed;
+    }
+  }
+  return void 0;
+}
+var NAMED_COLORS = {
+  black: { r: 0, g: 0, b: 0 },
+  white: { r: 255, g: 255, b: 255 },
+  red: { r: 255, g: 0, b: 0 },
+  green: { r: 0, g: 128, b: 0 },
+  blue: { r: 0, g: 0, b: 255 },
+  gray: { r: 128, g: 128, b: 128 },
+  grey: { r: 128, g: 128, b: 128 },
+  silver: { r: 192, g: 192, b: 192 },
+  transparent: { r: 0, g: 0, b: 0 },
+  orange: { r: 255, g: 165, b: 0 },
+  yellow: { r: 255, g: 255, b: 0 },
+  purple: { r: 128, g: 0, b: 128 },
+  navy: { r: 0, g: 0, b: 128 }
+};
+var clamp255 = (n) => Math.max(0, Math.min(255, Math.round(n)));
+function parseColorToRgb(input) {
+  if (typeof input !== "string") return void 0;
+  const raw = input.trim().toLowerCase();
+  if (raw.length === 0) return void 0;
+  if (Object.prototype.hasOwnProperty.call(NAMED_COLORS, raw)) {
+    return NAMED_COLORS[raw];
+  }
+  if (raw.startsWith("#")) {
+    const hex = raw.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      const r = parseInt(hex[0] + hex[0], 16);
+      const g = parseInt(hex[1] + hex[1], 16);
+      const b = parseInt(hex[2] + hex[2], 16);
+      if ([r, g, b].every((v) => Number.isFinite(v))) return { r, g, b };
+      return void 0;
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      const r = parseInt(hex.slice(0, 2), 16);
+      const g = parseInt(hex.slice(2, 4), 16);
+      const b = parseInt(hex.slice(4, 6), 16);
+      if ([r, g, b].every((v) => Number.isFinite(v))) return { r, g, b };
+      return void 0;
+    }
+    return void 0;
+  }
+  const rgbMatch = raw.match(/^rgba?\(([^)]+)\)$/);
+  if (rgbMatch) {
+    const parts = rgbMatch[1].split(",").map((p) => p.trim());
+    if (parts.length < 3) return void 0;
+    const channel = (p) => {
+      if (p.endsWith("%")) {
+        const pct = parseFloat(p.slice(0, -1));
+        if (!Number.isFinite(pct)) return void 0;
+        return clamp255(pct / 100 * 255);
+      }
+      const n = parseFloat(p);
+      if (!Number.isFinite(n)) return void 0;
+      return clamp255(n);
+    };
+    const r = channel(parts[0]);
+    const g = channel(parts[1]);
+    const b = channel(parts[2]);
+    if (r === void 0 || g === void 0 || b === void 0) return void 0;
+    return { r, g, b };
+  }
+  return void 0;
+}
+function parseFontSizePx(input) {
+  if (typeof input === "number") {
+    return Number.isFinite(input) && input > 0 ? input : void 0;
+  }
+  if (typeof input === "string") {
+    const m = input.trim().match(/^(-?\d*\.?\d+)/);
+    if (m) {
+      const n = parseFloat(m[1]);
+      return Number.isFinite(n) && n > 0 ? n : void 0;
+    }
+  }
+  return void 0;
+}
+function projectVisionFields(args) {
+  const { type, label, handlerNames, state, flatStyle } = args;
+  const fields = {
+    interactable: deriveInteractable(type, handlerNames)
+  };
+  const text = deriveText(state, label);
+  if (text !== void 0) fields.text = text;
+  const role = roleForType(type);
+  if (role !== void 0) fields.role = role;
+  if (flatStyle) {
+    const fg = parseColorToRgb(flatStyle.color);
+    if (fg !== void 0) fields.fg_color = fg;
+    const bg = parseColorToRgb(flatStyle.backgroundColor);
+    if (bg !== void 0) fields.bg_color = bg;
+    const size = parseFontSizePx(flatStyle.fontSize);
+    if (size !== void 0) fields.font_size_px = size;
+    if (typeof flatStyle.fontFamily === "string" && flatStyle.fontFamily.trim().length > 0) {
+      fields.font_family = flatStyle.fontFamily;
+    }
+  }
+  return fields;
+}
+
 // src/core/registry.ts
 function extractHandlerNames(props) {
   if (!props) return [];
@@ -20,6 +193,25 @@ function matchesCurrentRoute(registrationRoute, currentRoute) {
   if (registrationRoute == null || registrationRoute === "") return true;
   return registrationRoute === currentRoute;
 }
+function projectBbox(state, visibility, pixelRatio = 1) {
+  if (visibility !== "visible") return void 0;
+  const layout = state.layout;
+  if (!layout) return void 0;
+  const ratio = pixelRatio > 0 && Number.isFinite(pixelRatio) ? pixelRatio : 1;
+  const toPx = (v) => Math.max(0, Math.round(v * ratio));
+  const hasPage = typeof layout.pageX === "number" && typeof layout.pageY === "number" && Number.isFinite(layout.pageX) && Number.isFinite(layout.pageY);
+  const originX = hasPage ? layout.pageX : layout.x;
+  const originY = hasPage ? layout.pageY : layout.y;
+  if (typeof originX !== "number" || typeof originY !== "number" || typeof layout.width !== "number" || typeof layout.height !== "number" || !Number.isFinite(originX) || !Number.isFinite(originY) || !Number.isFinite(layout.width) || !Number.isFinite(layout.height)) {
+    return void 0;
+  }
+  return {
+    x: toPx(originX),
+    y: toPx(originY),
+    w: toPx(layout.width),
+    h: toPx(layout.height)
+  };
+}
 function inferActions(type) {
   const baseActions = ["focus", "blur"];
   switch (type) {
@@ -84,6 +276,15 @@ var NativeUIBridgeRegistry = class {
      * already installs.
      */
     this.routeProvider = null;
+    /**
+     * Device pixel ratio used to project `state.layout` (logical dp) into the
+     * physical-pixel `bbox` emitted on each snapshot element. Defaults to `1`
+     * (dp ≈ px) so callers/tests that never inject a ratio still get a usable
+     * box; the React provider wires the real `PixelRatio.get()` via
+     * {@link setPixelRatio}. Read from a non-React core module on purpose — see
+     * the `projectBbox` doc comment for why we don't import `react-native` here.
+     */
+    this.pixelRatio = 1;
     /**
      * Sticky flag: flips `true` the first time any element is registered and
      * stays `true` even after elements are unregistered. Lets agents distinguish
@@ -121,6 +322,21 @@ var NativeUIBridgeRegistry = class {
   getRouteProvider() {
     return this.routeProvider;
   }
+  /**
+   * Set the device pixel ratio used to project per-element `bbox` geometry
+   * into physical pixels. The React provider passes `PixelRatio.get()` here
+   * once at startup. Ignores non-finite / non-positive values (keeps the
+   * previous ratio) so a bad call can't zero out every bbox.
+   */
+  setPixelRatio(ratio) {
+    if (typeof ratio === "number" && Number.isFinite(ratio) && ratio > 0) {
+      this.pixelRatio = ratio;
+    }
+  }
+  /** Read-only accessor for the device pixel ratio used for bbox projection. */
+  getPixelRatio() {
+    return this.pixelRatio;
+  }
   // ============================================================================
   // Snapshot Enricher Slots
   // ============================================================================
@@ -660,6 +876,18 @@ var NativeUIBridgeRegistry = class {
         const handlers = extractHandlerNames(e.props);
         const state = e.getState();
         const visibility = !state.visible ? "hidden" : state.layout !== null ? "visible" : "likely-visible";
+        const bbox = projectBbox(state, visibility, this.pixelRatio);
+        const vision = projectVisionFields({
+          type: e.type,
+          label: e.label,
+          // Real interactivity signal: the names of props that are actually
+          // functions (onPress/onChangeText/...). NOT `e.actions`, which
+          // `inferActions` synthesizes press/click onto for every element —
+          // using it would mark plain text/view nodes interactable.
+          handlerNames: handlers,
+          state,
+          flatStyle: e.flatStyle
+        });
         return {
           id: e.id,
           type: e.type,
@@ -670,7 +898,9 @@ var NativeUIBridgeRegistry = class {
           customActions: e.customActions ? Object.keys(e.customActions) : void 0,
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
           registrationRoute: e.registrationRoute,
-          visibility
+          visibility,
+          ...bbox ? { bbox } : {},
+          ...vision
         };
       }),
       components: this.getAllComponents().map((c) => ({
@@ -987,9 +1217,10 @@ var DefaultNativeActionExecutor = class {
         requestId: request.requestId,
         durationMs: successTime - startTime
       });
+      const fresh = this.registry.getElement(registered.id) ?? registered;
       return {
         success: true,
-        elementState: registered.getState(),
+        elementState: fresh.getState(),
         result,
         durationMs: successTime - startTime,
         timestamp: successTime,
@@ -1895,7 +2126,7 @@ function createDesignHandlers(registry, viewportProvider) {
 var GRID_SIZE = 20;
 var NAV_TYPES = /* @__PURE__ */ new Set(["button", "heading", "badge", "status-message"]);
 var SKIP_TEXT_TYPES = /* @__PURE__ */ new Set(["button", "link", "tab", "menuitem"]);
-var INTERACTIVE_TYPES = /* @__PURE__ */ new Set([
+var INTERACTIVE_TYPES2 = /* @__PURE__ */ new Set([
   "button",
   "input",
   "switch",
@@ -2092,7 +2323,7 @@ function diagnosePageHealth(elements, viewport) {
   let interactiveTotal = 0;
   let interactiveDisabled = 0;
   for (const el of elements) {
-    if (!INTERACTIVE_TYPES.has(el.type)) continue;
+    if (!INTERACTIVE_TYPES2.has(el.type)) continue;
     interactiveTotal++;
     if (el.state.enabled === false) interactiveDisabled++;
   }
@@ -2160,6 +2391,13 @@ function matchElementsByText(registry, text, opts) {
   scored.sort((a, b) => a.rank - b.rank);
   return scored.map((s) => s.element);
 }
+function resolveElementState(element) {
+  const state = element.getState();
+  if (element.type === "input" && state.value === void 0 && typeof element.props?.value === "string") {
+    return { ...state, value: element.props.value };
+  }
+  return state;
+}
 async function executeWorkflowStep(step, registry, executor) {
   const startTime = Date.now();
   try {
@@ -2368,6 +2606,16 @@ function createServerHandlers(registry, executor, config) {
         const handlers = extractHandlerNames(e.props);
         const state = e.getState();
         const visibility = !state.visible ? "hidden" : state.layout !== null ? "visible" : "likely-visible";
+        const bbox = projectBbox(state, visibility, registry.getPixelRatio());
+        const vision = projectVisionFields({
+          type: e.type,
+          label: e.label,
+          // Real handler names (onPress/...), NOT inferred actions which
+          // synthesize press/click onto every element. See projectVisionFields.
+          handlerNames: handlers,
+          state,
+          flatStyle: e.flatStyle
+        });
         return {
           id: e.id,
           type: e.type,
@@ -2378,7 +2626,9 @@ function createServerHandlers(registry, executor, config) {
           customActions: e.customActions ? Object.keys(e.customActions) : void 0,
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
           registrationRoute: e.registrationRoute,
-          visibility
+          visibility,
+          ...bbox ? { bbox } : {},
+          ...vision
         };
       });
       return success2({ elements });
@@ -2396,7 +2646,7 @@ function createServerHandlers(registry, executor, config) {
           type: element.type,
           label: element.label,
           identifier: element.getIdentifier(),
-          state: element.getState(),
+          state: resolveElementState(element),
           actions: element.actions,
           customActions: element.customActions ? Object.keys(element.customActions) : void 0,
           registeredHandlers: handlers.length > 0 ? handlers : void 0,
@@ -2410,18 +2660,19 @@ function createServerHandlers(registry, executor, config) {
       if (!element) {
         return error2(`Element not found: ${id}`, "ELEMENT_NOT_FOUND");
       }
-      return success2({ state: element.getState() });
+      return success2({ state: resolveElementState(element) });
     },
     executeAction: async (ctx) => {
-      const { id } = ctx.params;
-      const body = ctx.body;
-      if (!body?.action) {
+      const rawBody = ctx.body ?? {};
+      const envelope = rawBody.request && typeof rawBody.request === "object" ? rawBody.request : rawBody;
+      const id = ctx.params.id ?? rawBody.id ?? "";
+      if (!envelope?.action) {
         return error2("Action is required", "INVALID_REQUEST");
       }
       const response = await executor.executeAction(id, {
-        action: body.action,
-        params: body.params,
-        waitOptions: body.waitOptions
+        action: envelope.action,
+        params: envelope.params,
+        waitOptions: envelope.waitOptions
       });
       if (!response.success) {
         return error2(response.error || "Action failed", "ACTION_FAILED");
@@ -3060,7 +3311,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.3.0",
+          version: "0.6.11",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,
@@ -3652,6 +3903,14 @@ var NativeUIBridgeServer = class {
       };
     };
   }
+  /**
+   * Whether the console/network capture should be installed. The dedicated
+   * `observability` flag wins when set; otherwise falls back to `testHooks`
+   * so consumers predating the flag keep their exact behavior.
+   */
+  observabilityEnabled() {
+    return this.config.observability ?? this.config.testHooks === true;
+  }
   /**
    * Set the server adapter
    */
@@ -3865,7 +4124,7 @@ var NativeUIBridgeServer = class {
       console.warn("[ui-bridge-native] See documentation for supported adapters.");
       return;
     }
-    if (this.config.testHooks === true) {
+    if (this.observabilityEnabled()) {
       this.consoleErrorBuffer.install();
       this.networkRequestBuffer.install();
     }
@@ -5367,6 +5626,7 @@ function UIBridgeNativeProvider({
       verbose: config.verbose,
       onEvent
     });
+    registryRef.current.setPixelRatio(reactNative.PixelRatio.get());
     setGlobalRegistry(registryRef.current);
   }
   const registry = registryRef.current;
@@ -5397,6 +5657,10 @@ function UIBridgeNativeProvider({
       cors: true,
       appInfo: config.appInfo,
       testHooks: features.testHooks === true,
+      // Dedicated console/network-capture flag; the server defaults it to
+      // the `testHooks` value when undefined, so passing it through verbatim
+      // keeps existing consumers unchanged.
+      observability: features.observability,
       // Injected device-viewport getter for POST /control/page-health. The
       // server doesn't import `react-native` itself — the require/import
       // pattern there crashed the host RN app in 0.6.3/0.6.4 (Metro/Hermes
@@ -5464,6 +5728,7 @@ function UIBridgeNativeProvider({
   }, [
     features.server,
     features.testHooks,
+    features.observability,
     config.serverPort,
     config.appInfo,
     registry,
@@ -5502,6 +5767,7 @@ function UIBridgeNativeProvider({
             cors: true,
             appInfo: config.appInfo,
             testHooks: features.testHooks === true,
+            observability: features.observability,
             viewportProvider: () => {
               const win = reactNative.Dimensions.get("window");
               return { width: win.width, height: win.height };
@@ -5705,12 +5971,41 @@ function scheduleDeadButtonWarning(bridge, id, type) {
 }
 function useUIElement(options) {
   const bridge = useUIBridgeNativeOptional();
-  const ref = react.useRef(null);
   const [registered, setRegistered] = react.useState(false);
   const [_layout, setLayout] = react.useState(null);
   const propsRef = react.useRef({});
   const registeredRef = react.useRef(false);
   const registeredIdRef = react.useRef(null);
+  const bridgeRef = react.useRef(bridge);
+  bridgeRef.current = bridge;
+  const nodeRef = react.useRef(null);
+  const refInterceptorRef = react.useRef(null);
+  if (refInterceptorRef.current === null) {
+    refInterceptorRef.current = {
+      get current() {
+        return nodeRef.current;
+      },
+      set current(node) {
+        const prev = nodeRef.current;
+        nodeRef.current = node;
+        const liveBridge = bridgeRef.current;
+        const registeredId = registeredIdRef.current;
+        if (!liveBridge || !registeredRef.current || registeredId === null) return;
+        if (node == null && prev != null) {
+          const state = liveBridge.registry.getElement(registeredId)?.getState();
+          if (state && state.visible !== false) {
+            liveBridge.registry.updateElementState(registeredId, { visible: false });
+          }
+        } else if (node != null && prev == null) {
+          const state = liveBridge.registry.getElement(registeredId)?.getState();
+          if (state && state.visible !== true) {
+            liveBridge.registry.updateElementState(registeredId, { visible: true });
+          }
+        }
+      }
+    };
+  }
+  const ref = refInterceptorRef.current;
   const {
     id,
     type = "custom",
@@ -5754,7 +6049,7 @@ function useUIElement(options) {
     }
     setRegistered(true);
     scheduleDeadButtonWarning(bridge, id, type);
-  }, [bridge, id, type, label, actions, customActions, treePath, style, stateStylesProp, valueProp]);
+  }, [bridge, id, type, label, actions, customActions, treePath, style, stateStylesProp, valueProp, ref]);
   const unregister = react.useCallback(() => {
     if (!bridge || !registeredRef.current) return;
     bridge.registry.unregisterElement(registeredIdRef.current ?? id);
@@ -5790,7 +6085,8 @@ function useUIElement(options) {
         writeLayout({ x, y, width, height, pageX: x, pageY: y });
       }
     },
-    [bridge, id]
+    // `ref` is the once-per-hook interceptor object — identity-stable.
+    [bridge, id, ref]
   );
   const registerRef = react.useRef(register);
   const unregisterRef = react.useRef(unregister);
@@ -5811,7 +6107,14 @@ function useUIElement(options) {
   react.useEffect(() => {
     if (!bridge || !registered) return;
     const node = ref.current;
-    if (!node || typeof node.measureInWindow !== "function") return;
+    if (!node) {
+      const seeded = bridge.registry.getElement(id)?.getState();
+      if (seeded && seeded.visible !== false) {
+        bridge.registry.updateElementState(id, { visible: false });
+      }
+      return;
+    }
+    if (typeof node.measureInWindow !== "function") return;
     let cancelled = false;
     let pendingTimer = null;
     const backoffMs = [50, 200, 500, 1e3, 2500];
@@ -5850,7 +6153,7 @@ function useUIElement(options) {
       cancelled = true;
       if (pendingTimer != null) clearTimeout(pendingTimer);
     };
-  }, [bridge, registered, id]);
+  }, [bridge, registered, id, ref]);
   const registeredHandlerKeysRef = react.useRef([]);
   react.useEffect(() => {
     if (!bridge || !registered || !handlersProp) return;
@@ -6632,6 +6935,46 @@ function decodeTextPayload(payload) {
   return new TextDecoder().decode(payload);
 }
 
+// src/server/bind-retry.ts
+function isAddrInUseError(err) {
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
+  const code = err?.code;
+  return message.includes("EADDRINUSE") || message.toLowerCase().includes("address already in use") || code === "EADDRINUSE";
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function bindWithRetry(attempt, options = {}) {
+  const {
+    minTotalMs = 3e4,
+    initialDelayMs = 500,
+    maxDelayMs = 5e3,
+    backoffFactor = 2,
+    logger = console,
+    sleep: sleep2 = defaultSleep,
+    now = Date.now
+  } = options;
+  const startedAt = now();
+  let delay = initialDelayMs;
+  let attemptIndex = 0;
+  for (; ; ) {
+    try {
+      await attempt(attemptIndex);
+      return;
+    } catch (err) {
+      const elapsed = now() - startedAt;
+      const budgetExhausted = elapsed + delay >= minTotalMs;
+      if (!isAddrInUseError(err) || budgetExhausted) {
+        throw err;
+      }
+      logger.warn(
+        `[ui-bridge-native] bind failed with EADDRINUSE (attempt ${attemptIndex + 1}); retrying in ${delay}ms (elapsed ${elapsed}ms / budget ${minTotalMs === Infinity ? "\u221E" : minTotalMs}ms)`
+      );
+      await sleep2(delay);
+      delay = Math.min(delay * backoffFactor, maxDelayMs);
+      attemptIndex += 1;
+    }
+  }
+}
+
 // src/server/ws-connection.ts
 var WebSocketConnection = class {
   constructor(id, socket, onMessage, onClose) {
@@ -7213,6 +7556,7 @@ exports.UI_BRIDGE_NATIVE_ROUTES = UI_BRIDGE_NATIVE_ROUTES;
 exports.UndoTracker = UndoTracker;
 exports.WebSocketConnection = WebSocketConnection;
 exports.WebSocketEventBridge = WebSocketEventBridge;
+exports.bindWithRetry = bindWithRetry;
 exports.buildTreePath = buildTreePath;
 exports.buildUpgradeResponse = buildUpgradeResponse;
 exports.captureNativeResponsiveSnapshot = captureNativeResponsiveSnapshot;
@@ -7223,15 +7567,22 @@ exports.createNativeActionExecutor = createNativeActionExecutor;
 exports.createNativeElementIdentifier = createNativeElementIdentifier;
 exports.createNativeServer = createNativeServer;
 exports.createServerHandlers = createServerHandlers;
+exports.deriveInteractable = deriveInteractable;
+exports.deriveText = deriveText;
 exports.extractHandlerNames = extractHandlerNames;
 exports.findAllByPattern = findAllByPattern;
 exports.findElementByIdentifier = findElementByIdentifier;
 exports.getGlobalRegistry = getGlobalRegistry;
 exports.getNativeElementDesignData = getNativeElementDesignData;
+exports.isAddrInUseError = isAddrInUseError;
 exports.mapNativeStyleToExtended = mapNativeStyleToExtended;
 exports.matchesIdentifier = matchesIdentifier;
+exports.parseColorToRgb = parseColorToRgb;
+exports.parseFontSizePx = parseFontSizePx;
 exports.parseTreePath = parseTreePath;
+exports.projectVisionFields = projectVisionFields;
 exports.resetGlobalRegistry = resetGlobalRegistry;
+exports.roleForType = roleForType;
 exports.setGlobalRegistry = setGlobalRegistry;
 exports.useToastRecorder = useToastRecorder;
 exports.useUIBridge = useUIBridge;