@qontinui/ui-bridge-native 0.3.0 → 0.3.1

package/dist/server/index.js

@@ -1023,7 +1023,8 @@ function createServerHandlers(registry, executor, config) {
     },
     getSnapshot: async (ctx) => {
       const visibleOnly = ctx.query?.visibleOnly === "true" || ctx.body?.visibleOnly === true;
-      const snapshot = registry.createSnapshot(void 0, { visibleOnly });
+      const currentRouteOnly = ctx.query?.currentRouteOnly === "true" || ctx.body?.currentRouteOnly === true;
+      const snapshot = registry.createSnapshot(void 0, { visibleOnly, currentRouteOnly });
       return success2(snapshot);
     },
     // Workflows
@@ -1190,6 +1191,134 @@ function createServerHandlers(registry, executor, config) {
       const failedCount = results.length - succeededCount;
       return success2({ results, succeededCount, failedCount });
     },
+    // Coord-based tap
+    //
+    // Synthesizes a press at the given screen coordinates by scanning the
+    // registered elements' layout rects for a containing match. We prefer the
+    // *topmost* match (smallest area = innermost child) since native UIs
+    // generally render parents before children, and the user's tap should
+    // logically hit the leaf-most interactive element.
+    //
+    // Coords are interpreted in the absolute (screen) space published by
+    // `measureInWindow`; we compare against `pageX/pageY` when available and
+    // fall back to the layout's relative `x/y` so this works in test fixtures
+    // that don't measure (the fallback only matches single-rooted screens but
+    // is good enough for the unit suite).
+    tapAt: async (ctx) => {
+      const body = ctx.body;
+      const x = body?.x;
+      const y = body?.y;
+      if (typeof x !== "number" || !Number.isFinite(x)) {
+        return error2('"x" must be a finite number', "INVALID_REQUEST");
+      }
+      if (typeof y !== "number" || !Number.isFinite(y)) {
+        return error2('"y" must be a finite number', "INVALID_REQUEST");
+      }
+      const action = body?.action ?? "press";
+      const allowedActions = [
+        "press",
+        "longPress",
+        "doubleTap"
+      ];
+      if (!allowedActions.includes(action)) {
+        return error2(
+          `"action" must be one of: ${allowedActions.join(", ")}`,
+          "INVALID_REQUEST"
+        );
+      }
+      const candidates = [];
+      for (const el of registry.getAllElements()) {
+        const state = el.getState();
+        const layout = state?.layout;
+        if (!layout) continue;
+        if (typeof layout.width !== "number" || typeof layout.height !== "number" || layout.width <= 0 || layout.height <= 0) {
+          continue;
+        }
+        const hasPage = typeof layout.pageX === "number" && typeof layout.pageY === "number" && Number.isFinite(layout.pageX) && Number.isFinite(layout.pageY);
+        const left = hasPage ? layout.pageX : layout.x;
+        const top = hasPage ? layout.pageY : layout.y;
+        if (x >= left && x <= left + layout.width && y >= top && y <= top + layout.height) {
+          candidates.push({
+            elementId: el.id,
+            layout,
+            area: layout.width * layout.height
+          });
+        }
+      }
+      if (candidates.length === 0) {
+        return error2(
+          `No element registered at (${x}, ${y})`,
+          "no_element_at_coords"
+        );
+      }
+      candidates.sort((a, b) => a.area - b.area);
+      const target = candidates[0];
+      const response = await executor.executeAction(target.elementId, { action });
+      if (!response.success) {
+        return error2(response.error || "Action failed", "ACTION_FAILED");
+      }
+      return success2({
+        elementId: target.elementId,
+        action,
+        layout: {
+          x: target.layout.x,
+          y: target.layout.y,
+          width: target.layout.width,
+          height: target.layout.height,
+          pageX: target.layout.pageX,
+          pageY: target.layout.pageY
+        }
+      });
+    },
+    // Observability — console error / network request ring buffers.
+    //
+    // The buffers are owned by NativeUIBridgeServer and patched onto the
+    // globals on `start()` (gated behind `features.testHooks`). When no
+    // buffer is provided (no testHooks, or a stripped-down server fixture),
+    // these handlers gracefully return empty arrays so callers can probe
+    // without 500ing.
+    getConsoleErrors: async (ctx) => {
+      const buf = config?.consoleErrorBuffer;
+      const since = ctx.query?.since !== void 0 ? Number(ctx.query.since) : void 0;
+      const limit = ctx.query?.limit !== void 0 ? Number(ctx.query.limit) : void 0;
+      if (!buf) {
+        return success2({
+          entries: [],
+          count: 0,
+          bufferSize: 0
+        });
+      }
+      const entries = buf.entries({
+        since: typeof since === "number" && Number.isFinite(since) ? since : void 0,
+        limit: typeof limit === "number" && Number.isFinite(limit) ? limit : void 0
+      });
+      return success2({
+        entries,
+        count: entries.length,
+        bufferSize: buf.size()
+      });
+    },
+    getNetworkRequests: async (ctx) => {
+      const buf = config?.networkRequestBuffer;
+      const since = ctx.query?.since !== void 0 ? Number(ctx.query.since) : void 0;
+      const limit = ctx.query?.limit !== void 0 ? Number(ctx.query.limit) : void 0;
+      if (!buf) {
+        return success2({
+          entries: [],
+          count: 0,
+          bufferSize: 0
+        });
+      }
+      const entries = buf.entries({
+        since: typeof since === "number" && Number.isFinite(since) ? since : void 0,
+        limit: typeof limit === "number" && Number.isFinite(limit) ? limit : void 0
+      });
+      return success2({
+        entries,
+        count: entries.length,
+        bufferSize: buf.size()
+      });
+    },
     // Test hooks — modal stack manipulation
     //
     // These two endpoints exist so external automation runners can drive
@@ -1291,6 +1420,266 @@ function createServerHandlers(registry, executor, config) {
   };
 }
 
+// src/server/observability.ts
+var RingBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.items = [];
+  }
+  push(entry) {
+    this.items.push(entry);
+    if (this.items.length > this.capacity) {
+      this.items.splice(0, this.items.length - this.capacity);
+    }
+  }
+  /**
+   * Return entries optionally filtered by `since` (timestamp ms) and capped
+   * at `limit`. Newest-end is preserved when `limit` would otherwise truncate.
+   */
+  entries(opts = {}) {
+    const { since, limit } = opts;
+    let filtered = this.items;
+    if (typeof since === "number") {
+      filtered = filtered.filter((e) => e.timestamp >= since);
+    }
+    if (typeof limit === "number" && limit >= 0 && filtered.length > limit) {
+      filtered = filtered.slice(filtered.length - limit);
+    }
+    return filtered.slice();
+  }
+  size() {
+    return this.items.length;
+  }
+  clear() {
+    this.items.length = 0;
+  }
+};
+function formatConsoleArgs(args) {
+  return args.map((a) => {
+    if (a instanceof Error) return a.message;
+    if (typeof a === "string") return a;
+    try {
+      return JSON.stringify(a);
+    } catch {
+      return String(a);
+    }
+  }).join(" ");
+}
+function extractStack(args) {
+  for (const a of args) {
+    if (a instanceof Error && a.stack) return a.stack;
+  }
+  return void 0;
+}
+var ConsoleErrorBuffer = class {
+  constructor(capacity = 100) {
+    this.installed = false;
+    this.buffer = new RingBuffer(capacity);
+  }
+  install() {
+    if (this.installed) return;
+    if (typeof console === "undefined") return;
+    this.originalError = console.error;
+    this.originalWarn = console.warn;
+    const buffer = this.buffer;
+    const origError = this.originalError;
+    const origWarn = this.originalWarn;
+    console.error = (...args) => {
+      try {
+        buffer.push({
+          timestamp: Date.now(),
+          level: "error",
+          message: formatConsoleArgs(args),
+          stack: extractStack(args)
+        });
+      } catch {
+      }
+      origError.apply(console, args);
+    };
+    console.warn = (...args) => {
+      try {
+        buffer.push({
+          timestamp: Date.now(),
+          level: "warn",
+          message: formatConsoleArgs(args),
+          stack: extractStack(args)
+        });
+      } catch {
+      }
+      origWarn.apply(console, args);
+    };
+    this.installed = true;
+  }
+  uninstall() {
+    if (!this.installed) return;
+    if (typeof console === "undefined") return;
+    if (this.originalError) console.error = this.originalError;
+    if (this.originalWarn) console.warn = this.originalWarn;
+    this.originalError = void 0;
+    this.originalWarn = void 0;
+    this.installed = false;
+  }
+  entries(opts = {}) {
+    return this.buffer.entries(opts);
+  }
+  size() {
+    return this.buffer.size();
+  }
+  clear() {
+    this.buffer.clear();
+  }
+  isInstalled() {
+    return this.installed;
+  }
+};
+function extractUrl(input) {
+  if (typeof input === "string") return input;
+  if (input && typeof input === "object") {
+    const obj = input;
+    if (typeof obj.url === "string") return obj.url;
+    try {
+      return String(input);
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+function extractMethod(input, init) {
+  if (init && typeof init.method === "string") return init.method.toUpperCase();
+  if (input && typeof input === "object") {
+    const obj = input;
+    if (typeof obj.method === "string") return obj.method.toUpperCase();
+  }
+  return "GET";
+}
+var NetworkRequestBuffer = class {
+  constructor(capacity = 100) {
+    this.installed = false;
+    this.buffer = new RingBuffer(capacity);
+  }
+  install() {
+    if (this.installed) return;
+    const g = globalThis;
+    if (typeof g.fetch === "function") {
+      this.originalFetch = g.fetch;
+      const buffer = this.buffer;
+      const original = this.originalFetch;
+      const patched = async (input, init) => {
+        const start = Date.now();
+        const url = extractUrl(input);
+        const method = extractMethod(input, init);
+        try {
+          const res = await original.call(globalThis, input, init);
+          buffer.push({
+            timestamp: start,
+            method,
+            url,
+            status: res.status,
+            durationMs: Date.now() - start,
+            ok: res.ok
+          });
+          return res;
+        } catch (err) {
+          buffer.push({
+            timestamp: start,
+            method,
+            url,
+            status: 0,
+            durationMs: Date.now() - start,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err)
+          });
+          throw err;
+        }
+      };
+      g.fetch = patched;
+    }
+    if (typeof g.XMLHttpRequest === "function") {
+      const Xhr = g.XMLHttpRequest;
+      this.originalXhrOpen = Xhr.prototype.open;
+      this.originalXhrSend = Xhr.prototype.send;
+      const buffer = this.buffer;
+      const origOpen = this.originalXhrOpen;
+      Xhr.prototype.open = function(method, url, ...rest) {
+        this.__uiBridgeMethod = method.toUpperCase();
+        this.__uiBridgeUrl = typeof url === "string" ? url : String(url);
+        return origOpen.call(
+          this,
+          method,
+          url,
+          ...rest
+        );
+      };
+      const origSend = this.originalXhrSend;
+      Xhr.prototype.send = function(body) {
+        const start = Date.now();
+        const method = this.__uiBridgeMethod ?? "GET";
+        const url = this.__uiBridgeUrl ?? "";
+        const finalize = (status, ok, error3) => {
+          buffer.push({
+            timestamp: start,
+            method,
+            url,
+            status,
+            durationMs: Date.now() - start,
+            ok,
+            error: error3
+          });
+        };
+        const onLoadEnd = () => {
+          this.removeEventListener("loadend", onLoadEnd);
+          this.removeEventListener("error", onError);
+          finalize(this.status, this.status >= 200 && this.status < 300);
+        };
+        const onError = () => {
+          this.removeEventListener("loadend", onLoadEnd);
+          this.removeEventListener("error", onError);
+          finalize(0, false, "XMLHttpRequest error");
+        };
+        this.addEventListener("loadend", onLoadEnd);
+        this.addEventListener("error", onError);
+        return origSend.call(
+          this,
+          body
+        );
+      };
+    }
+    this.installed = true;
+  }
+  uninstall() {
+    if (!this.installed) return;
+    const g = globalThis;
+    if (this.originalFetch) {
+      g.fetch = this.originalFetch;
+      this.originalFetch = void 0;
+    }
+    if (typeof g.XMLHttpRequest === "function") {
+      if (this.originalXhrOpen) {
+        g.XMLHttpRequest.prototype.open = this.originalXhrOpen;
+      }
+      if (this.originalXhrSend) {
+        g.XMLHttpRequest.prototype.send = this.originalXhrSend;
+      }
+    }
+    this.originalXhrOpen = void 0;
+    this.originalXhrSend = void 0;
+    this.installed = false;
+  }
+  entries(opts = {}) {
+    return this.buffer.entries(opts);
+  }
+  size() {
+    return this.buffer.size();
+  }
+  clear() {
+    this.buffer.clear();
+  }
+  isInstalled() {
+    return this.installed;
+  }
+};
+
 // src/server/ws-types.ts
 function isBatchRequest(msg) {
   return typeof msg === "object" && msg !== null && "batch" in msg && Array.isArray(msg.batch);
@@ -1341,6 +1730,10 @@ var WS_ROUTES = [
   },
   // Discovery
   { pattern: "control/find", handler: "find", httpMethods: ["POST"] },
+  // Runner-parity alias for `control/find`; the runner exposes its
+  // AI-powered element search at `/ui-bridge/ai/find`, so mobile mounts the
+  // same handler at both paths to keep agents portable across platforms.
+  { pattern: "ai/find", handler: "find", httpMethods: ["POST"] },
   { pattern: "control/snapshot", handler: "getSnapshot", httpMethods: ["GET"] },
   { pattern: "control/discover", handler: "getSnapshot" },
   // Workflows
@@ -1379,6 +1772,9 @@ var WS_ROUTES = [
   { pattern: "meta/methods", handler: "getMethods", httpMethods: ["GET"] },
   // AI helpers — mobile parity with the runner's `/ui-bridge/ai/*` family.
   { pattern: "ai/fill-form", handler: "fillForm", httpMethods: ["POST"] },
+  // Coord-based tap — synthesizes a press at the given screen coords by
+  // matching against registered elements' layout rects.
+  { pattern: "control/tap", handler: "tapAt", httpMethods: ["POST"] },
   // Test hooks — gated behind `features.testHooks`. Let external runners
   // drive the ModalDetector over HTTP so tests can flip `snapshot.modalStack`
   // without mounting React components.
@@ -1393,6 +1789,20 @@ var WS_ROUTES = [
     handler: "dismissModal",
     httpMethods: ["POST"],
     requiresTestHooks: true
+  },
+  // Observability — last-N console errors + network requests. testHooks-gated
+  // because patching `console.error` / `fetch` is invasive in production.
+  {
+    pattern: "control/console-errors",
+    handler: "getConsoleErrors",
+    httpMethods: ["GET"],
+    requiresTestHooks: true
+  },
+  {
+    pattern: "sdk/network-requests",
+    handler: "getNetworkRequests",
+    httpMethods: ["GET"],
+    requiresTestHooks: true
   }
 ];
 var HANDLER_DESCRIPTIONS = {
@@ -1428,6 +1838,9 @@ var HANDLER_DESCRIPTIONS = {
   diffBaseline: "Diff current UI against a saved baseline",
   getMethods: "List every handler name (legacy introspection)",
   fillForm: "Fill multiple inputs in one call: body { fields: [{elementId, value}] } \u2014 each field dispatches `type` + `clear:true`",
+  tapAt: "Synthesize a press at given screen coords by matching registered element layout rects: body { x, y, action? }",
+  getConsoleErrors: "TEST HOOK \u2014 last-N console.error/console.warn entries; ?since=<ms>&limit=<n>",
+  getNetworkRequests: "TEST HOOK \u2014 last-N fetch/XHR entries with status + duration; ?since=<ms>&limit=<n>",
   pushModal: "TEST HOOK \u2014 push a modal onto the snapshot.modalStack via the registry ModalDetector",
   dismissModal: "TEST HOOK \u2014 dismiss a modal by id from the snapshot.modalStack via the registry ModalDetector"
 };
@@ -1496,8 +1909,15 @@ var NativeUIBridgeServer = class {
       cors: true,
       ...config
     };
+    this.consoleErrorBuffer = new ConsoleErrorBuffer();
+    this.networkRequestBuffer = new NetworkRequestBuffer();
+    if (this.config.appInfo) {
+      this.registry.setAppInfo(this.config.appInfo);
+    }
     this.handlers = createServerHandlers(registry, executor, {
-      appInfo: this.config.appInfo
+      appInfo: this.config.appInfo,
+      consoleErrorBuffer: this.consoleErrorBuffer,
+      networkRequestBuffer: this.networkRequestBuffer
     });
     this.handlers.getMethods = async () => {
       const testHooks = this.config.testHooks === true;
@@ -1625,8 +2045,16 @@ var NativeUIBridgeServer = class {
   /**
    * Set a route provider for reporting the current navigation route.
    * When set, `control/snapshot` responses include `currentRoute` and `segments`.
+   *
+   * Also forwards the provider into the registry so the *default*
+   * `getSnapshot` handler (and any other call site of
+   * `registry.createSnapshot`) reads the route too — without this the
+   * cloud-relay/bare-server path returned `currentRoute: null` even when
+   * a `RouteTracker` was wired, because that path never installed the
+   * server-level handler override below.
    */
   setRouteProvider(provider) {
+    this.registry.setRouteProvider(provider);
     const baseGetElements = this.handlers.getElements;
     this.handlers.getElements = async (ctx) => {
       const currentRouteOnly = ctx.query?.currentRouteOnly === "true" || ctx.body?.currentRouteOnly === true;
@@ -1695,6 +2123,10 @@ var NativeUIBridgeServer = class {
       console.warn("[ui-bridge-native] See documentation for supported adapters.");
       return;
     }
+    if (this.config.testHooks === true) {
+      this.consoleErrorBuffer.install();
+      this.networkRequestBuffer.install();
+    }
     await this.adapter.start(this.config.serverPort, this.handleRequest.bind(this));
     this.running = true;
     console.log(`[ui-bridge-native] HTTP server started on port ${this.config.serverPort}`);
@@ -1708,6 +2140,8 @@ var NativeUIBridgeServer = class {
     }
     await this.adapter.stop();
     this.running = false;
+    this.consoleErrorBuffer.uninstall();
+    this.networkRequestBuffer.uninstall();
     console.log("[ui-bridge-native] HTTP server stopped");
   }
   /**
@@ -3004,7 +3438,9 @@ var WebSocketConnection = class {
   }
 };
 
+exports.ConsoleErrorBuffer = ConsoleErrorBuffer;
 exports.NativeUIBridgeServer = NativeUIBridgeServer;
+exports.NetworkRequestBuffer = NetworkRequestBuffer;
 exports.OPCODE_BINARY = OPCODE_BINARY;
 exports.OPCODE_CLOSE = OPCODE_CLOSE;
 exports.OPCODE_CONTINUATION = OPCODE_CONTINUATION;