@reactiive/ennio 0.0.2 → 0.0.4-beta.0

package/README.md

@@ -14,11 +14,16 @@ UITouch that half-fires recognizers — the gesture goes through the same
 path a finger would.
 
 ```bash
-npm install @reactiive/ennio @reactiive/ennio-expo-plugin react-native-nitro-modules
-npx ennio test e2e/01-auth-flow.yaml      # one flow
-npx ennio test e2e/                       # every *.yaml in the directory
+bun add @reactiive/ennio react-native-nitro-modules
+bun add -d @reactiive/ennio-expo-plugin
+
+bunx ennio test e2e/01-auth-flow.yaml      # one flow
+bunx ennio test e2e/                       # every *.yaml in the directory
 ```
 
+(Or use the equivalent `npm install` / `yarn add` — `ennio-expo-plugin`
+is a build-time config plugin, so it belongs in `devDependencies`.)
+
 ## Requirements
 
 - Expo app on React Native ≥ 0.81 (New Architecture, Fabric)
@@ -54,3 +59,10 @@ example flows live in the [monorepo README](https://github.com/enzomanuelmangano
 ## License
 
 MIT
+
+## Trademarks
+
+Maestro is a trademark of mobile.dev. Ennio is an independent
+project, not affiliated with mobile.dev. References to "Maestro"
+describe only the YAML flow format that Ennio consumes; no Maestro
+source code is bundled or redistributed.

package/cpp/EnnioControlSocket.cpp

@@ -0,0 +1,274 @@
+// EnnioControlSocket.cpp
+//
+// Unix domain socket transport that bypasses Hermes Inspector / CDP for
+// pure UIKit operations. Sole reason for existing: CDP `Runtime.evaluate`
+// queues on the JS thread, so any handler — even one that touches no JS
+// state — waits for whatever React work is in flight. Tab swaps on iOS 26
+// expose this: native UIKit cost is ~8 ms but CDP wait is ~2 s after a
+// destination-tab first-render kicks off on the JS thread.
+//
+// The socket lives in the app sandbox tmp dir at a stable filename so
+// the CLI can discover it via `simctl get_app_container ... data`. Wire
+// format = newline-delimited JSON. Server reuses the request/response
+// shapes from `Protocol.hpp` so commands here look identical to CDP
+// dispatch. Only a whitelisted subset of handlers is wired — anything
+// that needs JS thread state (`waitForCommit`, `evalScript`, shadow-tree
+// mutations) stays CDP-only.
+//
+// Pure C++ on purpose — uses POSIX sockets + `getenv("TMPDIR")` so the
+// file compiles outside an ObjC++ TU. The whitelisted handlers call into
+// `EnnioRuntimeHelper` which is the ObjC++ wrapper around UIKit; that
+// indirection keeps the socket server portable and lets it be built into
+// the `cpp/` source group of the pod.
+
+#include "EnnioControlSocket.h"
+
+#include "EnnioRuntimeHelper.h"
+#include "Protocol.hpp"
+
+#include <atomic>
+#include <cerrno>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <pthread.h>
+#include <sstream>
+#include <string>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/un.h>
+#include <unistd.h>
+
+namespace ennio {
+
+std::atomic<bool> EnnioControlSocket::g_started{false};
+
+static std::string g_socketPath;
+
+static std::string computeSocketPath() {
+    // sockaddr_un.sun_path is 104 bytes on macOS. The simulator app's
+    // sandbox $TMPDIR is ~140 chars (`.../Containers/Data/Application/
+    // <UUID>/tmp/`), too long for bind(). Use the host's `/tmp` — the
+    // simulator process is just a macOS process so /tmp is shared with
+    // the host, and the CLI runs on the host too.
+    //
+    // Single fixed name: one test run drives one app at a time. If you
+    // ever run multiple Ennio test runs concurrently they'll fight for
+    // this socket — same constraint as today's Hermes Inspector port.
+    return "/tmp/ennio-control.sock";
+}
+
+std::string EnnioControlSocket::socketPath() {
+    if (g_socketPath.empty()) g_socketPath = computeSocketPath();
+    return g_socketPath;
+}
+
+// Handle one request. Single big switch keeps the wire surface explicit
+// and audit-able. Adding a new handler is a deliberate act — no
+// auto-registration.
+static Response dispatchRequest(const Request& req) {
+    Response r;
+    r.id = req.id;
+    r.success = false;
+
+    if (req.type == "tapTabByName") {
+        r.success = EnnioRuntimeHelper::getInstance().tapTabByName(
+            json::parseString(req.payload, "name"));
+    } else if (req.type == "isAlertPresent") {
+        // Pure UIKit query — walks UIWindowScene roots looking for a
+        // presented UIAlertController. Safe off the JS thread.
+        const bool present = EnnioRuntimeHelper::getInstance().isAlertPresent();
+        r.success = true;
+        r.data = present ? "true" : "false";
+    } else if (req.type == "getViewWindowFrame") {
+        // Hot-loop op: `writer.layoutCenter` polls this up to 30 times
+        // per id-based tap, checking for a stable frame. Going via CDP
+        // queues every poll on the JS thread; routing here drops each
+        // poll from ~30-200 ms (JS-queue contention) to ~3 ms (socket
+        // round-trip + UIKit query). UIKit `convertRect:toView:nil` is
+        // safe off the JS thread.
+        auto frame = EnnioRuntimeHelper::getInstance().getViewWindowFrame(
+            json::parseString(req.payload, "testID"));
+        std::ostringstream oss;
+        oss << "{\"x\":" << std::get<0>(frame) << ",\"y\":" << std::get<1>(frame)
+            << ",\"width\":" << std::get<2>(frame) << ",\"height\":" << std::get<3>(frame) << "}";
+        r.data = oss.str();
+        r.success = std::get<2>(frame) > 0 && std::get<3>(frame) > 0;
+    } else if (req.type == "scrollTo") {
+        // Walks up to the enclosing UIScrollView and sets contentOffset
+        // to bring the element into view. Pure UIKit on main thread —
+        // no JS state needed.
+        r.success = EnnioRuntimeHelper::getInstance().scrollTo(
+            json::parseString(req.payload, "scrollViewTestID"),
+            json::parseString(req.payload, "elementTestID"));
+    } else if (req.type == "setSearchBarText") {
+        // RNScreens' UISearchBar (headerSearchBarOptions) is native
+        // UIKit, not a React-managed view. testID can't reach its
+        // inner UITextField and idb HID keystrokes don't reliably
+        // deliver on iOS 26 simulator. Assigns .text and fires
+        // textDidChange on the delegate so onChangeText fires.
+        r.success = EnnioRuntimeHelper::getInstance().setSearchBarText(
+            json::parseString(req.payload, "text"));
+    } else if (req.type == "focusSearchBar") {
+        // RNScreens UISearchBar isn't in the React view tree —
+        // testID lookups + accessibility-text HID taps miss the
+        // placeholder. Calls becomeFirstResponder on the bar's text
+        // field so later inputText routes via appendSearchBarText.
+        r.success = EnnioRuntimeHelper::getInstance().focusSearchBar(
+            json::parseString(req.payload, "placeholder"));
+    } else if (req.type == "appendSearchBarText") {
+        // inputText semantics — append to current search bar text.
+        r.success = EnnioRuntimeHelper::getInstance().appendSearchBarText(
+            json::parseString(req.payload, "text"));
+    } else if (req.type == "eraseSearchBarText") {
+        // eraseText / clearText semantics on UISearchBar. Pass a
+        // very large count (e.g. INT_MAX from the CLI) to clear.
+        std::string countStr = json::parseString(req.payload, "count");
+        int count = 0;
+        try { count = std::stoi(countStr); } catch (...) { count = 0; }
+        r.success = EnnioRuntimeHelper::getInstance().eraseSearchBarText(count);
+    } else if (req.type == "selectSegmentByLabel") {
+        // UISegmentedControl segment selection by visible label.
+        // Sidesteps the slow text-tap retry loop that the shadow-tree
+        // walk hits on RNCSegmentedControl labels.
+        r.success = EnnioRuntimeHelper::getInstance().selectSegmentByLabel(
+            json::parseString(req.payload, "label"));
+    } else if (req.type == "selectPickerValueByLabel") {
+        // Wheel-style UIPickerView selection. HID swipes against the
+        // spinner are flaky (touch begin/end timing inconsistent on
+        // iOS 26 simulator); this op walks every visible UIPickerView,
+        // matches a row by label, and fires the delegate's
+        // didSelectRow so RNCPicker emits onValueChange.
+        r.success = EnnioRuntimeHelper::getInstance().selectPickerValueByLabel(
+            json::parseString(req.payload, "label"));
+    } else if (req.type == "ping") {
+        r.success = true;
+        r.data = "\"pong\"";
+    } else {
+        r.error = "unknown_type";
+    }
+    return r;
+}
+
+// Read until newline. Returns false on EOF/error.
+static bool readLine(int fd, std::string& out) {
+    out.clear();
+    char buf[1];
+    while (true) {
+        ssize_t n = ::read(fd, buf, 1);
+        if (n <= 0) return false;
+        if (buf[0] == '\n') return true;
+        out.push_back(buf[0]);
+        if (out.size() > (1u << 20)) return false; // 1 MiB ceiling
+    }
+}
+
+static bool writeLine(int fd, const std::string& line) {
+    std::string framed = line;
+    framed.push_back('\n');
+    const char* p = framed.data();
+    size_t left = framed.size();
+    while (left > 0) {
+        ssize_t n = ::write(fd, p, left);
+        if (n <= 0) return false;
+        p += n;
+        left -= static_cast<size_t>(n);
+    }
+    return true;
+}
+
+static void serveClient(int fd) {
+    std::string line;
+    while (readLine(fd, line)) {
+        Request req;
+        req.id = json::parseString(line, "id");
+        req.type = json::parseString(line, "type");
+        // payload is itself a JSON object at the "payload" key. The CLI
+        // inlines fields; we keep the whole line for downstream
+        // parseString lookups — same loose convention as CDP path.
+        req.payload = line;
+        Response resp = dispatchRequest(req);
+        if (!writeLine(fd, resp.toJSON())) break;
+    }
+    ::close(fd);
+}
+
+static void* acceptLoop(void* arg) {
+    int srv = static_cast<int>(reinterpret_cast<intptr_t>(arg));
+    ::pthread_setname_np("ennio-control-socket");
+    while (true) {
+        int cfd = ::accept(srv, nullptr, nullptr);
+        if (cfd < 0) {
+            if (errno == EINTR) continue;
+            break;
+        }
+        // One client at a time. Sequential serves keep UIKit dispatch
+        // ordering predictable and side-step multi-writer races on the
+        // dispatch table. CLI uses a single persistent connection so
+        // there's no real concurrency pressure.
+        serveClient(cfd);
+    }
+    ::close(srv);
+    return nullptr;
+}
+
+void EnnioControlSocket::start() {
+    bool expected = false;
+    if (!g_started.compare_exchange_strong(expected, true)) return;
+
+    const std::string path = socketPath();
+
+    // Unlink stale sock from a crashed previous run. Best-effort.
+    ::unlink(path.c_str());
+
+    int srv = ::socket(AF_UNIX, SOCK_STREAM, 0);
+    if (srv < 0) {
+        std::fprintf(stderr, "[Ennio][socket] socket() failed: %s\n", std::strerror(errno));
+        g_started.store(false);
+        return;
+    }
+
+    sockaddr_un addr{};
+    addr.sun_family = AF_UNIX;
+    if (path.size() >= sizeof(addr.sun_path)) {
+        std::fprintf(stderr, "[Ennio][socket] path too long (%zu): %s\n", path.size(), path.c_str());
+        ::close(srv);
+        g_started.store(false);
+        return;
+    }
+    std::strncpy(addr.sun_path, path.c_str(), sizeof(addr.sun_path) - 1);
+
+    if (::bind(srv, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)) < 0) {
+        std::fprintf(stderr, "[Ennio][socket] bind(%s) failed: %s\n", path.c_str(), std::strerror(errno));
+        ::close(srv);
+        g_started.store(false);
+        return;
+    }
+
+    // 0600 — owner-only. Same user as the simulator process / CLI on a
+    // dev box. Other local users on a shared CI box cannot connect.
+    ::chmod(path.c_str(), 0600);
+
+    if (::listen(srv, 4) < 0) {
+        std::fprintf(stderr, "[Ennio][socket] listen() failed: %s\n", std::strerror(errno));
+        ::close(srv);
+        ::unlink(path.c_str());
+        g_started.store(false);
+        return;
+    }
+
+    std::fprintf(stderr, "[Ennio][socket] listening on %s\n", path.c_str());
+
+    pthread_t t;
+    if (::pthread_create(&t, nullptr, &acceptLoop,
+                         reinterpret_cast<void*>(static_cast<intptr_t>(srv))) != 0) {
+        std::fprintf(stderr, "[Ennio][socket] pthread_create failed\n");
+        ::close(srv);
+        ::unlink(path.c_str());
+        g_started.store(false);
+        return;
+    }
+    ::pthread_detach(t);
+}
+
+} // namespace ennio

package/cpp/EnnioControlSocket.h

@@ -0,0 +1,41 @@
+// EnnioControlSocket.h
+//
+// Unix domain socket transport that bypasses Hermes Inspector / CDP for
+// pure UIKit operations. Sole reason for existing: CDP `Runtime.evaluate`
+// queues on the JS thread, so any handler — even one that touches no JS
+// state — waits for whatever React work is in flight. Tab swaps on iOS 26
+// expose this: native UIKit cost is ~8 ms but CDP wait is ~2 s after a
+// destination-tab first-render kicks off on the JS thread.
+//
+// The socket lives in the app sandbox tmp dir at a stable filename so
+// the CLI can discover it via `simctl get_app_container ... data`. Wire
+// format = newline-delimited JSON. Server reuses the request/response
+// shapes from `Protocol.cpp` so commands here look identical to CDP
+// dispatch. Only a whitelisted subset of handlers is wired — anything
+// that needs JS thread state (`waitForCommit`, `evalScript`, shadow-tree
+// mutations) stays CDP-only.
+
+#pragma once
+
+#include <atomic>
+#include <string>
+
+namespace ennio {
+
+class EnnioControlSocket {
+public:
+    // Returns the absolute filesystem path the server listens on, or
+    // empty string if not started.
+    static std::string socketPath();
+
+    // Idempotent. Binds the socket, spawns an accept thread, and starts
+    // serving. Safe to call from `+load` or later. Fails quietly if the
+    // socket is already in use (e.g. orphaned from a crashed previous
+    // run — unlink + retry).
+    static void start();
+
+private:
+    static std::atomic<bool> g_started;
+};
+
+} // namespace ennio

package/dist/cli.js

@@ -10534,11 +10534,152 @@ function selectorToJson(selector) {
   return JSON.stringify(out);
 }
 
+// src/cli/socket-client.ts
+var import_node_net = require("node:net");
+var REQUEST_TIMEOUT_MS = 6e3;
+var EnnioSocketClient = class {
+  constructor() {
+    this.socket = null;
+    this.buf = "";
+    this.pending = /* @__PURE__ */ new Map();
+    this.idSeq = 0;
+    this.socketPath = null;
+    this.connecting = null;
+  }
+  /**
+   * Discover + connect. Idempotent. Returns true if connected, false if
+   * the socket isn't reachable (caller should fall back to CDP).
+   *
+   * Path convention matches `EnnioControlSocket::computeSocketPath()`:
+   * `/tmp/ennio-<bundleId>.sock` on the host. The simulator shares
+   * `/tmp` with the host filesystem, so the same path is reachable from
+   * both sides. We use `/tmp` rather than the app sandbox tmp because
+   * sockaddr_un.sun_path is 104 bytes on macOS and the sandbox path
+   * exceeds that limit.
+   */
+  async connect(bundleId, _udid) {
+    if (this.socket && !this.socket.destroyed) return true;
+    if (this.connecting) return this.connecting;
+    this.connecting = this.doConnect(bundleId).finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+  async doConnect(_bundleId) {
+    this.socketPath = `/tmp/ennio-control.sock`;
+    return new Promise((resolve4) => {
+      const s = (0, import_node_net.createConnection)(this.socketPath);
+      const onError = () => {
+        s.destroy();
+        resolve4(false);
+      };
+      s.once("error", onError);
+      s.once("connect", () => {
+        s.off("error", onError);
+        s.on("data", (chunk) => this.onData(chunk));
+        s.on("error", (e) => this.onSocketError(e));
+        s.on("close", () => this.onClose());
+        this.socket = s;
+        resolve4(true);
+      });
+    });
+  }
+  onData(chunk) {
+    this.buf += chunk.toString("utf8");
+    let nl;
+    while ((nl = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, nl);
+      this.buf = this.buf.slice(nl + 1);
+      if (!line) continue;
+      try {
+        const resp = JSON.parse(line);
+        const p = this.pending.get(resp.id);
+        if (p) {
+          this.pending.delete(resp.id);
+          p.resolve(resp);
+        }
+      } catch {
+      }
+    }
+  }
+  onSocketError(e) {
+    for (const [, p] of this.pending) p.reject(e);
+    this.pending.clear();
+  }
+  onClose() {
+    this.socket = null;
+    const err = new Error("socket closed");
+    for (const [, p] of this.pending) p.reject(err);
+    this.pending.clear();
+  }
+  /**
+   * Send a request, await response. Throws if not connected.
+   */
+  async send(type2, payload = {}) {
+    if (!this.socket || this.socket.destroyed) {
+      throw new Error("socket not connected");
+    }
+    const id = `s${++this.idSeq}`;
+    const line = JSON.stringify({
+      id,
+      type: type2,
+      ...payload
+    }) + "\n";
+    return new Promise((resolve4, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`socket request timeout: ${type2}`));
+      }, REQUEST_TIMEOUT_MS);
+      this.pending.set(id, {
+        resolve: (r) => {
+          clearTimeout(timer);
+          resolve4(r);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        }
+      });
+      this.socket.write(line, (err) => {
+        if (err) {
+          clearTimeout(timer);
+          this.pending.delete(id);
+          reject(err);
+        }
+      });
+    });
+  }
+  isConnected() {
+    return !!this.socket && !this.socket.destroyed;
+  }
+  close() {
+    if (this.socket) this.socket.destroy();
+    this.socket = null;
+  }
+};
+
 // src/cli/client.ts
 var METRO_BASE = process.env.ENNIO_METRO_URL || "http://localhost:8081";
-var REQUEST_TIMEOUT_MS = 3e4;
+var REQUEST_TIMEOUT_MS2 = 3e4;
 var RECONNECT_TIMEOUT_MS = 6e3;
 var POLL_INTERVAL_MS = 15;
+var SOCKET_FAST_OPS = /* @__PURE__ */ new Set([
+  "tapTabByName",
+  "isAlertPresent",
+  // `writer.layoutCenter` polls getViewWindowFrame up to 30 times
+  // per id-tap, plus an occasional scrollTo when the element is
+  // off-screen. Routing both through the socket bypasses the
+  // JS-thread queue that previously paced each iteration.
+  "getViewWindowFrame",
+  "scrollTo",
+  "selectPickerValueByLabel",
+  "selectSegmentByLabel",
+  "setSearchBarText",
+  "appendSearchBarText",
+  "eraseSearchBarText",
+  "focusSearchBar",
+  "ping"
+]);
 var EnnioClient = class {
   constructor() {
     this.ws = null;
@@ -10546,6 +10687,7 @@ var EnnioClient = class {
     this.rpcId = 0;
     this.tokenSeq = 0;
     this.debuggerUrl = null;
+    this.socketClient = null;
   }
   /**
    * Discover Metro Inspector pages, pick the JS context. Bridgeless
@@ -10625,6 +10767,7 @@ var EnnioClient = class {
       this.ws.close();
       this.ws = null;
     }
+    this.disconnectSocket();
   }
   async reconnect(maxWaitMs = RECONNECT_TIMEOUT_MS) {
     this.disconnect();
@@ -10657,7 +10800,7 @@ var EnnioClient = class {
           this.pending.delete(id);
           reject(new Error(`CDP timeout: ${method}`));
         }
-      }, REQUEST_TIMEOUT_MS);
+      }, REQUEST_TIMEOUT_MS2);
       this.pending.set(id, {
         resolve: (r) => {
           clearTimeout(timer);
@@ -10695,7 +10838,57 @@ var EnnioClient = class {
    * Two-phase: post via `__ennioDispatch`, then poll the result slot
    * until the in-app worker writes a response or the timeout expires.
    */
+  /**
+   * Discover + connect the Unix-domain control socket for this app.
+   * Idempotent. Safe to call after every launchApp / clearState — the
+   * underlying client retries discovery and re-opens the socket against
+   * the new app process.
+   */
+  async ensureSocketConnected(bundleId, udid) {
+    if (!this.socketClient) this.socketClient = new EnnioSocketClient();
+    const ok = await this.socketClient.connect(bundleId, udid);
+    if (process.env.ENNIO_DEBUG_SOCKET) {
+      process.stderr.write(`[socket] ensureSocketConnected(${bundleId}) -> ${ok}
+`);
+    }
+    return ok;
+  }
+  /**
+   * Tear down the socket alongside the CDP WebSocket. Called from
+   * `disconnect()` so launchApp / clearState restart cleanly.
+   */
+  disconnectSocket() {
+    if (this.socketClient) {
+      this.socketClient.close();
+      this.socketClient = null;
+    }
+  }
   async send(type2, payload = {}) {
+    if (SOCKET_FAST_OPS.has(type2) && this.socketClient?.isConnected()) {
+      if (process.env.ENNIO_DEBUG_SOCKET) {
+        process.stderr.write(`[socket] route ${type2}
+`);
+      }
+      try {
+        const t0 = Date.now();
+        const r = await this.socketClient.send(type2, payload);
+        if (process.env.ENNIO_DEBUG_SOCKET) {
+          process.stderr.write(`[socket] ${type2} done in ${Date.now() - t0}ms
+`);
+        }
+        return r;
+      } catch {
+        if (process.env.ENNIO_DEBUG_SOCKET) {
+          process.stderr.write(`[socket] ${type2} threw, falling back to CDP
+`);
+        }
+      }
+    } else if (SOCKET_FAST_OPS.has(type2) && process.env.ENNIO_DEBUG_SOCKET) {
+      process.stderr.write(
+        `[socket] ${type2} NOT routed (connected=${this.socketClient?.isConnected()})
+`
+      );
+    }
     if (!this.ws || this.ws.readyState !== wrapper_default.OPEN) {
       const ok = await this.reconnect(RECONNECT_TIMEOUT_MS);
       if (!ok) throw new Error("Not connected to Hermes Inspector");
@@ -10710,7 +10903,7 @@ var EnnioClient = class {
     }
     const start = Date.now();
     const pollExpr = `(()=>{const v=globalThis.__ennioResults&&globalThis.__ennioResults[${tokenLit}];if(v!==undefined){delete globalThis.__ennioResults[${tokenLit}];}return v===undefined?null:v;})()`;
-    while (Date.now() - start < REQUEST_TIMEOUT_MS) {
+    while (Date.now() - start < REQUEST_TIMEOUT_MS2) {
       const value = await this.eval(pollExpr);
       if (value != null) {
         return JSON.parse(value);
@@ -13815,9 +14008,15 @@ async function runMaestroTests(client, writer, reader, testFilePath, options = {
   const results = { passed: 0, failed: 0, tests: [], client };
   const flow = parseMaestroFile(testFilePath);
   const flowName = flow.name || (0, import_path3.basename)(testFilePath, ".yaml");
+  if (flow.appId) {
+    await client.ensureSocketConnected(flow.appId, process.env.ENNIO_UDID);
+  }
   const reconnectClient = async () => {
     const newClient = new EnnioClient();
     await newClient.connect();
+    if (flow.appId) {
+      await newClient.ensureSocketConnected(flow.appId, process.env.ENNIO_UDID);
+    }
     return newClient;
   };
   const executor = new MaestroExecutor(client, writer, reader, testFilePath, {
@@ -13867,6 +14066,7 @@ async function runMaestroTests(client, writer, reader, testFilePath, options = {
       }
     }
   }
+  executor.printProfileSummary();
   results.client = executor.getClient();
   return results;
 }
@@ -13880,6 +14080,12 @@ var MaestroExecutor = class _MaestroExecutor {
     // false because every fresh sim boots without an override.
     this.airplaneOn = false;
     this.logStart = Date.now();
+    this.logPrev = Date.now();
+    // Per-step timing breadcrumbs. Each verbose log line gets its delta
+    // recorded here, then `printProfileSummary` buckets them by op-type
+    // at flow end so the operator sees "tab tap: 6× = 21 ms, id tap: 14×
+    // = 3287 ms" without grepping. Always collected when verbose is on.
+    this.profileEvents = [];
     this.client = client;
     this.writer = writer;
     this.reader = reader;
@@ -13900,10 +14106,67 @@ var MaestroExecutor = class _MaestroExecutor {
   }
   log(msg) {
     if (this.verbose) {
-      const ms = Date.now() - this.logStart;
-      console.log(`    [+${ms}ms] ${msg}`);
+      const now = Date.now();
+      const ms = now - this.logStart;
+      const delta = now - this.logPrev;
+      this.logPrev = now;
+      const cum = `+${ms}ms`.padStart(8);
+      const d = `\u0394${delta}ms`.padStart(7);
+      console.log(`    [${cum} ${d}] ${msg}`);
+      this.profileEvents.push({ msg, delta });
     }
   }
+  /**
+   * Classify a log message into a coarse op-type bucket. Regex-based
+   * so call sites don't have to change. New categories should mirror
+   * what an operator naturally groups when reading the verbose dump.
+   */
+  bucketFor(msg) {
+    if (msg.startsWith("launchApp")) return "launchApp";
+    if (msg.startsWith("tap: ") && /text/.test(msg) && /Cart|Products|Home|Profile/.test(msg))
+      return "tab tap (text)";
+    if (msg.startsWith("tap: ") && /"id"/.test(msg)) return "id tap";
+    if (msg.startsWith("tap: point")) return "point tap";
+    if (msg.startsWith("tapOn: ") && /"id"/.test(msg)) return "tapOn (auto-scroll + setup)";
+    if (msg.startsWith("tapOn: ") && /text/.test(msg)) return "tapOn (text)";
+    if (msg.startsWith("assertVisible") || msg.startsWith("assertNotVisible"))
+      return "assertVisible";
+    if (msg.startsWith("scrollUntilVisible")) return "scrollUntilVisible";
+    if (msg.startsWith("scroll") || msg.startsWith("swipe")) return "scroll/swipe";
+    if (msg.startsWith("runFlow")) return "runFlow";
+    if (msg.startsWith("(tapping alert button")) return "alert tap";
+    if (msg.startsWith("hideKeyboard")) return "hideKeyboard";
+    if (msg.startsWith("inputText") || msg.startsWith("typeText")) return "typeText";
+    return "other";
+  }
+  printProfileSummary() {
+    if (!this.verbose || this.profileEvents.length === 0) return;
+    const buckets = /* @__PURE__ */ new Map();
+    let total = 0;
+    for (const e of this.profileEvents) {
+      total += e.delta;
+      const b = this.bucketFor(e.msg);
+      const cur = buckets.get(b) ?? { total: 0, count: 0 };
+      cur.total += e.delta;
+      cur.count += 1;
+      buckets.set(b, cur);
+    }
+    const rows = Array.from(buckets.entries()).map(([name, { total: t, count }]) => ({ name, total: t, count })).sort((a, b) => b.total - a.total);
+    console.log("");
+    console.log("  \u2500\u2500 Profile (verbose) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    console.log(
+      `    ${"bucket".padEnd(34)} ${"count".padStart(5)}  ${"total".padStart(8)}  ${"avg".padStart(6)}   pct`
+    );
+    for (const r of rows) {
+      const pct = total > 0 ? (r.total / total * 100).toFixed(1) : "0.0";
+      const avg = r.count > 0 ? Math.round(r.total / r.count) : 0;
+      console.log(
+        `    ${r.name.padEnd(34)} ${String(r.count).padStart(5)}  ${`${r.total}ms`.padStart(8)}  ${`${avg}ms`.padStart(6)}  ${pct.padStart(4)}%`
+      );
+    }
+    console.log(`    ${"TOTAL".padEnd(34)} ${" ".padStart(5)}  ${`${total}ms`.padStart(8)}`);
+    console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  }
   /**
    * Get current client (may have been replaced by launchApp/clearState)
    */
@@ -14005,6 +14268,51 @@ var MaestroExecutor = class _MaestroExecutor {
       await this.waitCommit(POINT_TAP_SETTLE_MS);
       return;
     }
+    if (selector.text && !selector.id) {
+      const alertUp = await this.reader.isAlertPresent();
+      if (!alertUp) {
+        const r = await this.client.send("tapTabByName", { name: selector.text });
+        if (r?.success === true) {
+          this.log(`tap: ${JSON.stringify(selector)} via ${this.writer.describe("tap")}`);
+          this.lastTappedSelector = selector;
+          await new Promise((r2) => setTimeout(r2, 100));
+          return;
+        }
+      }
+    }
+    if (selector.text && !selector.id) {
+      const sb = await this.client.send("focusSearchBar", {
+        placeholder: selector.text
+      });
+      if (sb?.success === true) {
+        this.log(`tap: ${JSON.stringify(selector)} via search bar focus`);
+        this.lastTappedSelector = selector;
+        await this.waitCommit(TAP_NAV_SETTLE_MS);
+        return;
+      }
+    }
+    if (selector.text && !selector.id) {
+      const seg = await this.client.send("selectSegmentByLabel", {
+        label: selector.text
+      });
+      if (seg?.success === true) {
+        this.log(`tap: ${JSON.stringify(selector)} via segmented control`);
+        this.lastTappedSelector = selector;
+        await this.waitCommit(TAP_NAV_SETTLE_MS);
+        return;
+      }
+    }
+    if (selector.text && !selector.id) {
+      const r = await this.client.send("selectPickerValueByLabel", {
+        label: selector.text
+      });
+      if (r?.success === true) {
+        this.log(`tap: ${JSON.stringify(selector)} via picker selectRow`);
+        this.lastTappedSelector = selector;
+        await this.waitCommit(TAP_NAV_SETTLE_MS);
+        return;
+      }
+    }
     if (selector.text && !selector.id) {
       const alertPoll = opts.optional ? 200 : 2e3;
       const ok2 = await this.tryTapAlertButton(selector.text, alertPoll);
@@ -14314,6 +14622,12 @@ var MaestroExecutor = class _MaestroExecutor {
     if ("inputText" in cmd) {
       const text = cmd.inputText;
       this.log(`inputText: "${text}"`);
+      const sbar = await this.client.send("appendSearchBarText", { text });
+      if (sbar?.success === true) {
+        this.log(`inputText: via UISearchBar delegate`);
+        await this.waitCommit(TAP_BACK_RECOVER_DELAY_MS);
+        return;
+      }
       await this.typeText(text);
       return;
     }
@@ -14482,6 +14796,12 @@ var MaestroExecutor = class _MaestroExecutor {
       const eraseCmd = cmd.eraseText;
       const chars = typeof eraseCmd === "number" ? eraseCmd : eraseCmd.characters || 50;
       this.log(`eraseText: ${chars} characters`);
+      const sbar = await this.client.send("eraseSearchBarText", { count: String(chars) });
+      if (sbar?.success === true) {
+        this.log(`eraseText: via UISearchBar delegate`);
+        await this.waitCommit(TAP_BACK_RECOVER_DELAY_MS);
+        return;
+      }
       await this.writer.eraseText(this.lastTappedSelector?.id ?? null, chars);
       return;
     }
@@ -14956,6 +15276,8 @@ var MaestroExecutor = class _MaestroExecutor {
       }
     }
     if (!connected) throw new Error("clearState: Failed to reconnect to app after restart");
+    this.writer.setClient(this.client);
+    this.reader.setClient(this.client);
     this.writer.invalidateViewportCache();
     try {
       await this.client.waitForIdle(POST_LAUNCH_IDLE_BUDGET_MS);
@@ -14991,6 +15313,8 @@ var MaestroExecutor = class _MaestroExecutor {
       }
     }
     if (!connected) throw new Error("launchApp: Failed to reconnect to app after restart");
+    this.writer.setClient(this.client);
+    this.reader.setClient(this.client);
     this.writer.invalidateViewportCache();
     await this.sleep(POST_LAUNCH_SHADOW_COMMIT_MS);
     try {
@@ -15263,6 +15587,23 @@ var HidDaemon = class {
   swipe(x1, y1, x2, y2, durationMs = 300) {
     return this.send(`swipe ${x1} ${y1} ${x2} ${y2} ${durationMs}`);
   }
+  key(keyCode) {
+    return this.send(`key ${keyCode}`);
+  }
+  // Bulk key repeat in ONE gRPC call. Saves the ~160 ms per-call
+  // subprocess spawn cost that `eraseText(50)` / `clearText(100)`
+  // used to pay 50–100× — the whole sequence now lands in ~50 ms.
+  keyRepeat(keyCode, count) {
+    if (count <= 0) return Promise.resolve();
+    return this.send(`keyrep ${keyCode} ${count}`);
+  }
+  // Send arbitrary text via idb's `text` (USB HID layer). Encodes the
+  // string as JSON on the wire so it can contain spaces / unicode /
+  // control chars without breaking the line-delimited protocol.
+  text(text) {
+    if (!text) return Promise.resolve();
+    return this.send(`text ${JSON.stringify(text)}`);
+  }
   close() {
     if (this.dead) return;
     try {
@@ -15330,6 +15671,18 @@ async function swipe2(x1, y1, x2, y2, durationMs = 300) {
   const d = await getHidDaemon();
   await d.swipe(x1, y1, x2, y2, durationMs);
 }
+async function pressKey2(keyCode) {
+  const d = await getHidDaemon();
+  await d.key(keyCode);
+}
+async function pressKeyRepeat(keyCode, count) {
+  const d = await getHidDaemon();
+  await d.keyRepeat(keyCode, count);
+}
+async function typeText2(text) {
+  const d = await getHidDaemon();
+  await d.text(text);
+}
 
 // src/cli/hierarchy.ts
 var import_node_child_process = require("node:child_process");
@@ -15489,6 +15842,13 @@ var NitroWriter = class {
     this.screenSize = null;
     this.surfaceOffset = null;
   }
+  // Hot-swap the underlying client after a launchApp/clearState rebind.
+  // The old client's WebSocket + control socket are torn down by the
+  // runner; without this swap, every send() would target the dead
+  // transports and either throw or stall.
+  setClient(client) {
+    this.client = client;
+  }
   async scrollAuto(direction, distance, testID = "") {
     if (direction === "left" || direction === "right") {
       const startX = direction === "left" ? Math.round(SAFE_CENTER_X * 1.75) : Math.round(SAFE_CENTER_X * 0.25);
@@ -15639,8 +15999,12 @@ var NitroWriter = class {
         return true;
       }
     }
-    await ensureCompanion();
-    await typeText(text);
+    try {
+      await typeText2(text);
+    } catch {
+      await ensureCompanion();
+      await typeText(text);
+    }
     await new Promise((r) => setTimeout(r, 100));
     return true;
   }
@@ -15649,8 +16013,12 @@ var NitroWriter = class {
     if (!c) return false;
     await this.hidTap(c.x, c.y, 50);
     await this.client.waitForCommit(200);
-    for (let i = 0; i < 100; i++) {
-      await pressKey(42);
+    try {
+      await pressKeyRepeat(42, 100);
+    } catch {
+      for (let i = 0; i < 100; i++) {
+        await pressKey(42);
+      }
     }
     await new Promise((r) => setTimeout(r, 100));
     return true;
@@ -15662,9 +16030,13 @@ var NitroWriter = class {
       await this.hidTap(c.x, c.y, 50);
       await this.client.waitForCommit(200);
     }
-    await ensureCompanion();
-    for (let i = 0; i < count; i++) {
-      await pressKey(42);
+    try {
+      await pressKeyRepeat(42, count);
+    } catch {
+      await ensureCompanion();
+      for (let i = 0; i < count; i++) {
+        await pressKey(42);
+      }
     }
     await new Promise((r) => setTimeout(r, 100));
     return true;
@@ -15679,8 +16051,12 @@ var NitroWriter = class {
     };
     const code = map2[keyName.toLowerCase()];
     if (code === void 0) return false;
-    await ensureCompanion();
-    await pressKey(code);
+    try {
+      await pressKey2(code);
+    } catch {
+      await ensureCompanion();
+      await pressKey(code);
+    }
     await this.client.waitForCommit(200);
     return true;
   }
@@ -15845,6 +16221,9 @@ var NitroReader = class {
   constructor(client) {
     this.client = client;
   }
+  setClient(client) {
+    this.client = client;
+  }
   existsById(testID) {
     return this.client.exists(testID);
   }

package/ios/EnnioAutoInit.mm

@@ -16,6 +16,7 @@
 #include <jsi/jsi.h>
 #include <functional>
 #include "../cpp/HybridEnnio.hpp"
+#include "../cpp/EnnioControlSocket.h"
 
 #if __has_include(<ReactCommon/RCTInstance.h>)
 #import <ReactCommon/RCTInstance.h>
@@ -113,6 +114,11 @@ static NSString* ennioDistributionName(EnnioDistribution d) {
     NSString* mark = [NSString stringWithFormat:@"%@/Library/_ennio_load_fired.txt", NSHomeDirectory()];
     [@"loaded" writeToFile:mark atomically:YES encoding:NSUTF8StringEncoding error:nil];
 
+    // Start the Unix-domain control socket before any JS work runs.
+    // Independent of Hermes Inspector — exists to bypass the JS-thread
+    // queue for pure UIKit handlers (see EnnioControlSocket.cpp).
+    ennio::EnnioControlSocket::start();
+
     // Try to swizzle RCTHost's start method
     Class hostClass = NSClassFromString(@"RCTHost");
     if (!hostClass) {

package/ios/EnnioRuntimeHelper.h

@@ -236,6 +236,64 @@ public:
     bool copyToClipboard(const std::string& text);
     bool pasteFromClipboard(const std::string& testID);
     std::string getClipboardText();
+    /**
+     * Programmatic UIPickerView wheel selection. HID swipes against
+     * the picker's spinner are flaky on the iOS 26 simulator — the
+     * touch-begin/end timing doesn't always cross the pan recogniser
+     * threshold and the wheel snaps back. Walks every visible
+     * UIPickerView, asks its dataSource for row count, uses the
+     * delegate's `pickerView:titleForRow:forComponent:` (or a
+     * `viewForRow:` UILabel.text leaf walk) to match `label`
+     * case-insensitively. Calls `selectRow:inComponent:animated:`
+     * then fires `pickerView:didSelectRow:inComponent:` on the
+     * delegate so the @react-native-picker/picker bridge emits
+     * onValueChange. Caller need not know the picker's testID — at
+     * most one picker is normally visible.
+     */
+    bool selectPickerValueByLabel(const std::string& label);
+    /**
+     * Programmatic UISearchBar text entry. RNScreens binds a
+     * UISearchBar to Stack.Screen.headerSearchBarOptions; the bar is
+     * native UIKit, not a React-managed view, so testID lookups
+     * can't reach its inner UITextField. idb HID keystrokes don't
+     * always deliver to the bar's field on iOS 26 simulator either.
+     * Walks every visible UISearchBar, assigns `searchBar.text` and
+     * fires `searchBar:textDidChange:` on the delegate so RNScreens
+     * emits onChangeText. Pass empty string to clear.
+     */
+    bool setSearchBarText(const std::string& text);
+    /**
+     * Append `text` to the currently-focused UISearchBar (if any).
+     * Falls back to the first visible UISearchBar when none is the
+     * first responder. Used by inputText so successive calls build up
+     * the query naturally instead of overwriting.
+     */
+    bool appendSearchBarText(const std::string& text);
+    /**
+     * Delete trailing `count` characters from the focused (or first
+     * visible) UISearchBar. Used by eraseText / clearText. Pass a
+     * very large count (e.g. INT_MAX) to clear the field entirely.
+     */
+    bool eraseSearchBarText(int count);
+    /**
+     * Focus the search bar whose placeholder matches `placeholder`
+     * (case-insensitive). RNScreens-managed UISearchBar isn't in the
+     * React view tree so testID lookups + accessibility-label HID
+     * taps miss it. Calls becomeFirstResponder on the embedded text
+     * field so subsequent inputText fires textDidChange correctly.
+     * When `placeholder` is empty, focuses the first visible search
+     * bar.
+     */
+    bool focusSearchBar(const std::string& placeholder);
+    /**
+     * Programmatic UISegmentedControl selection. Walks every
+     * visible UISegmentedControl, matches a segment by title
+     * (case-insensitive), calls setSelectedSegmentIndex and fires
+     * UIControlEventValueChanged so the RN bridge (RNCSegmentedControl)
+     * emits onChange. Returns false when no matching segment is on
+     * screen.
+     */
+    bool selectSegmentByLabel(const std::string& label);
 
 private:
     EnnioRuntimeHelper() = default;

package/ios/EnnioRuntimeHelper.mm

@@ -2430,6 +2430,283 @@ std::string EnnioRuntimeHelper::getClipboardText() {
     return result;
 }
 
+// First UILabel.text in the subtree of `root`, depth-first. Used to
+// extract row labels when a UIPickerViewDelegate only provides
+// `viewForRow:forComponent:reusingView:` (custom row cells).
+static NSString* firstLabelTextIn(UIView* root) {
+    if (!root) return nil;
+    if ([root isKindOfClass:[UILabel class]]) {
+        NSString* t = ((UILabel*)root).text;
+        if (t.length) return t;
+    }
+    for (UIView* sub in root.subviews) {
+        NSString* hit = firstLabelTextIn(sub);
+        if (hit) return hit;
+    }
+    return nil;
+}
+
+// Collect every visible UIPickerView across connected windows into
+// `out` (depth-first). UIDatePicker on iOS hosts a UIPickerView as
+// a private subview in spinner mode, so we recurse past it rather
+// than treating UIDatePicker itself as terminal.
+static void collectPickerViewsIn(UIView* root, NSMutableArray<UIPickerView*>* out) {
+    if (!root || root.hidden) return;
+    if ([root isKindOfClass:[UIPickerView class]]) {
+        [out addObject:(UIPickerView*)root];
+        // Don't return — a UIPickerView's subviews don't contain
+        // another nested picker on stock iOS, but recursing is
+        // cheap and future-proofs against subclasses that wrap a
+        // sibling picker.
+    }
+    for (UIView* sub in root.subviews) collectPickerViewsIn(sub, out);
+}
+
+bool EnnioRuntimeHelper::selectPickerValueByLabel(const std::string& label) {
+    NSString* needle = [NSString stringWithUTF8String:label.c_str()];
+    __block bool ok = false;
+
+    void (^block)(void) = ^{
+        NSMutableArray<UIPickerView*>* pickers = [NSMutableArray array];
+        for (UIScene* scene in [UIApplication sharedApplication].connectedScenes) {
+            if (![scene isKindOfClass:[UIWindowScene class]]) continue;
+            for (UIWindow* win in [((UIWindowScene*)scene).windows reverseObjectEnumerator]) {
+                collectPickerViewsIn(win, pickers);
+            }
+        }
+        for (UIPickerView* pv in pickers) {
+            id<UIPickerViewDataSource> ds = pv.dataSource;
+            id<UIPickerViewDelegate> dg = pv.delegate;
+            if (!ds) continue;
+
+            // Iterate every component so a multi-wheel picker (e.g.
+            // UIDatePicker's month/day/year) can be targeted by a
+            // unique row label without knowing which component it
+            // belongs to.
+            NSInteger componentCount = [ds numberOfComponentsInPickerView:pv];
+            for (NSInteger component = 0; component < componentCount; component++) {
+                NSInteger rowCount = [ds pickerView:pv numberOfRowsInComponent:component];
+                for (NSInteger row = 0; row < rowCount; row++) {
+                    NSString* title = nil;
+                    if ([dg respondsToSelector:@selector(pickerView:titleForRow:forComponent:)]) {
+                        title = [dg pickerView:pv titleForRow:row forComponent:component];
+                    } else if ([dg respondsToSelector:@selector(pickerView:attributedTitleForRow:forComponent:)]) {
+                        title = [[dg pickerView:pv attributedTitleForRow:row forComponent:component] string];
+                    } else if ([dg respondsToSelector:@selector(pickerView:viewForRow:forComponent:reusingView:)]) {
+                        UIView* rowView = [dg pickerView:pv viewForRow:row forComponent:component reusingView:nil];
+                        title = firstLabelTextIn(rowView);
+                    }
+                    if (title && [title compare:needle options:NSCaseInsensitiveSearch] == NSOrderedSame) {
+                        [pv selectRow:row inComponent:component animated:NO];
+                        if ([dg respondsToSelector:@selector(pickerView:didSelectRow:inComponent:)]) {
+                            [dg pickerView:pv didSelectRow:row inComponent:component];
+                        }
+                        ok = true;
+                        return;
+                    }
+                }
+            }
+        }
+    };
+    if ([NSThread isMainThread]) block(); else dispatchSyncMainWithTimeout(block);
+    return ok;
+}
+
+// Collect every text field that powers a search bar UI. iOS 26
+// replaced UIKit's UISearchBar with a SwiftUI
+// `InlineSearchBarViewRepresentation` wrapper, so a UISearchBar
+// class walk returns 0 hits even though the bar is visible on
+// screen. The inner private class `UISearchBarTextField` (a
+// UITextField subclass) survives the migration and is what the
+// SwiftUI host shows. Walking for that class — plus an
+// in-tree UISearchBar fallback for older iOS / collapsed-mode UI —
+// covers both worlds. `out` receives UITextField instances; the
+// caller drives text via .text + UIControlEventEditingChanged.
+static void collectSearchBarTextFieldsIn(UIView* root, NSMutableArray<UITextField*>* out) {
+    if (!root || root.hidden) return;
+    NSString* cls = NSStringFromClass([root class]);
+    if ([root isKindOfClass:[UITextField class]] &&
+        ([cls isEqualToString:@"UISearchBarTextField"] || [cls containsString:@"SearchBar"])) {
+        [out addObject:(UITextField*)root];
+        return;
+    }
+    if ([root isKindOfClass:[UISearchBar class]]) {
+        UITextField* tf = [(UISearchBar*)root valueForKey:@"searchField"];
+        if (tf) [out addObject:tf];
+        return;
+    }
+    for (UIView* sub in root.subviews) collectSearchBarTextFieldsIn(sub, out);
+}
+
+// Walks every visible search-bar text field across connected
+// windows. Covers iOS 26 SwiftUI-hosted bars (UISearchBarTextField
+// directly under a SwiftUI host) and legacy UISearchBar bars.
+static NSArray<UITextField*>* allSearchBarTextFields() {
+    NSMutableArray<UITextField*>* fields = [NSMutableArray array];
+    for (UIScene* scene in [UIApplication sharedApplication].connectedScenes) {
+        if (![scene isKindOfClass:[UIWindowScene class]]) continue;
+        for (UIWindow* win in [((UIWindowScene*)scene).windows reverseObjectEnumerator]) {
+            collectSearchBarTextFieldsIn(win, fields);
+        }
+    }
+    return fields;
+}
+
+// Return the search-bar text field that is the current first
+// responder, or nil if none. Reading isFirstResponder on the
+// field directly is correct — it IS the focused responder when
+// the search bar is active.
+static UITextField* focusedSearchBarTextField() {
+    for (UITextField* tf in allSearchBarTextFields()) {
+        if (tf.isFirstResponder) return tf;
+    }
+    return nil;
+}
+
+static UITextField* firstSearchBarTextField() {
+    return allSearchBarTextFields().firstObject;
+}
+
+// Fire the events needed for both the SwiftUI search-bar host AND
+// the legacy UISearchBarDelegate path to observe the new value.
+// iOS 26 SwiftUI hosts observe UIControlEventEditingChanged on the
+// underlying text field; UISearchBar bridges through the same
+// notification to its delegate's searchBar:textDidChange:. So a
+// single editingChanged dispatch covers both.
+static void notifySearchTextChanged(UITextField* tf) {
+    if (!tf) return;
+    [tf sendActionsForControlEvents:UIControlEventEditingChanged];
+    [[NSNotificationCenter defaultCenter]
+        postNotificationName:UITextFieldTextDidChangeNotification
+                      object:tf];
+}
+
+bool EnnioRuntimeHelper::setSearchBarText(const std::string& text) {
+    NSString* str = [NSString stringWithUTF8String:text.c_str()];
+    __block bool ok = false;
+    void (^block)(void) = ^{
+        UITextField* tf = focusedSearchBarTextField() ?: firstSearchBarTextField();
+        if (!tf) return;
+        tf.text = str;
+        notifySearchTextChanged(tf);
+        ok = true;
+    };
+    if ([NSThread isMainThread]) block(); else dispatchSyncMainWithTimeout(block);
+    return ok;
+}
+
+bool EnnioRuntimeHelper::appendSearchBarText(const std::string& text) {
+    NSString* str = [NSString stringWithUTF8String:text.c_str()];
+    __block bool ok = false;
+    void (^block)(void) = ^{
+        // Prefer the focused search field; fall back to the first
+        // visible one so iOS 26's SwiftUI host (which sometimes
+        // refuses becomeFirstResponder via UIKit) still routes the
+        // input correctly when focusSearchBar was called just
+        // before this.
+        UITextField* tf = focusedSearchBarTextField() ?: firstSearchBarTextField();
+        if (!tf) return;
+        tf.text = [(tf.text ?: @"") stringByAppendingString:str];
+        notifySearchTextChanged(tf);
+        ok = true;
+    };
+    if ([NSThread isMainThread]) block(); else dispatchSyncMainWithTimeout(block);
+    return ok;
+}
+
+bool EnnioRuntimeHelper::focusSearchBar(const std::string& placeholder) {
+    // `placeholder` is informational only on iOS 26 — the SwiftUI
+    // host's UISearchBarTextField has placeholder="" even when the
+    // visible bar shows "Search fruit". When no placeholder match
+    // is found, fall back to the first visible field (at most one
+    // search bar is normally on screen). Returns success when a
+    // field exists at all, even if becomeFirstResponder is
+    // refused — iOS 26's PlatformViewRepresentable host swallows
+    // some responder calls but the subsequent
+    // appendSearchBarText / eraseSearchBarText paths use
+    // firstSearchBarTextField fallback, so the flow still routes
+    // input correctly.
+    NSString* needle = [NSString stringWithUTF8String:placeholder.c_str()];
+    __block bool ok = false;
+    void (^block)(void) = ^{
+        NSArray<UITextField*>* fields = allSearchBarTextFields();
+        UITextField* target = nil;
+        if (needle.length > 0) {
+            for (UITextField* tf in fields) {
+                if (tf.placeholder &&
+                    [tf.placeholder rangeOfString:needle options:NSCaseInsensitiveSearch].location != NSNotFound) {
+                    target = tf;
+                    break;
+                }
+            }
+        }
+        if (!target) target = fields.firstObject;
+        if (!target) return;
+        [target becomeFirstResponder];  // best-effort; SwiftUI host may refuse
+        ok = true;
+    };
+    if ([NSThread isMainThread]) block(); else dispatchSyncMainWithTimeout(block);
+    return ok;
+}
+
+bool EnnioRuntimeHelper::eraseSearchBarText(int count) {
+    __block bool ok = false;
+    void (^block)(void) = ^{
+        UITextField* tf = focusedSearchBarTextField() ?: firstSearchBarTextField();
+        if (!tf) return;
+        NSString* cur = tf.text ?: @"";
+        NSInteger keep = (NSInteger)cur.length - (NSInteger)count;
+        if (keep < 0) keep = 0;
+        tf.text = [cur substringToIndex:(NSUInteger)keep];
+        notifySearchTextChanged(tf);
+        ok = true;
+    };
+    if ([NSThread isMainThread]) block(); else dispatchSyncMainWithTimeout(block);
+    return ok;
+}
+
+// Collect every visible UISegmentedControl across connected windows.
+static void collectSegmentedIn(UIView* root, NSMutableArray<UISegmentedControl*>* out) {
+    if (!root || root.hidden) return;
+    if ([root isKindOfClass:[UISegmentedControl class]]) {
+        [out addObject:(UISegmentedControl*)root];
+        return;
+    }
+    for (UIView* sub in root.subviews) collectSegmentedIn(sub, out);
+}
+
+bool EnnioRuntimeHelper::selectSegmentByLabel(const std::string& label) {
+    NSString* needle = [NSString stringWithUTF8String:label.c_str()];
+    __block bool ok = false;
+    void (^block)(void) = ^{
+        NSMutableArray<UISegmentedControl*>* controls = [NSMutableArray array];
+        for (UIScene* scene in [UIApplication sharedApplication].connectedScenes) {
+            if (![scene isKindOfClass:[UIWindowScene class]]) continue;
+            for (UIWindow* win in [((UIWindowScene*)scene).windows reverseObjectEnumerator]) {
+                collectSegmentedIn(win, controls);
+            }
+        }
+        for (UISegmentedControl* sc in controls) {
+            for (NSUInteger i = 0; i < sc.numberOfSegments; i++) {
+                NSString* title = [sc titleForSegmentAtIndex:i];
+                if (title && [title compare:needle options:NSCaseInsensitiveSearch] == NSOrderedSame) {
+                    sc.selectedSegmentIndex = (NSInteger)i;
+                    // RNCSegmentedControl bridges onChange via
+                    // UIControlEventValueChanged on the underlying
+                    // UISegmentedControl; setSelectedSegmentIndex
+                    // alone doesn't fire that event so dispatch
+                    // explicitly.
+                    [sc sendActionsForControlEvents:UIControlEventValueChanged];
+                    ok = true;
+                    return;
+                }
+            }
+        }
+    };
+    if ([NSThread isMainThread]) block(); else dispatchSyncMainWithTimeout(block);
+    return ok;
+}
+
 } // namespace ennio
 
 // Objective-C helper for setting the surface presenter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactiive/ennio",
-  "version": "0.0.2",
+  "version": "0.0.4-beta.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/enzomanuelmangano/ennio.git",

package/src/cli/hid-daemon.py

@@ -13,10 +13,19 @@ Wire protocol (line-delimited, both directions):
 
   IN   tap <x> <y> <durationMs>
   IN   swipe <x1> <y1> <x2> <y2> <durationMs>
+  IN   key <keycode>
+  IN   keyrep <keycode> <count>            — N copies, one gRPC call
+  IN   text <json-encoded-string>          — JSON string handles spaces / unicode
   IN   exit
   OUT  ok                  — command completed
   OUT  err <message>       — command failed; daemon stays alive
 
+Why batch a `keyrep` op? `eraseText: 50 characters` used to fan out
+50 separate `idb ui key 42` subprocess invocations (~160 ms each =
+8 s of pure spawn overhead). `keyrep` sends the whole sequence in
+one `client.key_sequence` gRPC call — ~50 ms total regardless of
+count.
+
 The daemon discovers the companion socket from `IDB_COMPANION` env
 var or `/tmp/idb/<UDID>_companion.sock` if the parent passes a UDID
 positional. The CLI launches one daemon per booted target and keeps
@@ -24,6 +33,7 @@ it alive for the whole `ennio test` session.
 """
 
 import asyncio
+import json
 import logging
 import os
 import sys
@@ -116,6 +126,41 @@ async def handle(client: Client, line: str) -> None:
                 duration=dur_ms / 1000.0,
             )
             print("ok", flush=True)
+        elif op == "key":
+            # key <keycode>  — single USB HID key down+up.
+            if len(parts) < 2:
+                print("err key-needs-keycode", flush=True)
+                return
+            await client.key(keycode=int(parts[1]))
+            print("ok", flush=True)
+        elif op == "keyrep":
+            # keyrep <keycode> <count>  — N repeated keys in ONE
+            # gRPC call. Replaces the eraseText/clearText fan-out
+            # of N separate `idb ui key` subprocess spawns
+            # (~160 ms each); the whole sequence now lands in ~50 ms.
+            if len(parts) < 3:
+                print("err keyrep-needs-code-count", flush=True)
+                return
+            code = int(parts[1])
+            count = max(0, int(parts[2]))
+            if count > 0:
+                await client.key_sequence(key_sequence=[code] * count)
+            print("ok", flush=True)
+        elif op == "text":
+            # text <json-encoded-string>  — JSON string so the
+            # payload can carry spaces, unicode, etc. line-safely.
+            payload = line[len("text "):].strip() if len(line) > len("text ") else ""
+            try:
+                text = json.loads(payload)
+            except Exception as e:
+                print(f"err bad-json-text {e}", flush=True)
+                return
+            if not isinstance(text, str):
+                print("err text-not-string", flush=True)
+                return
+            if text:
+                await client.text(text=text)
+            print("ok", flush=True)
         elif op == "exit":
             sys.exit(0)
         else: