@reactiive/ennio 0.0.1

package/cpp/HybridEnnio.hpp

@@ -0,0 +1,174 @@
+#pragma once
+
+// Include the generated spec
+#include "../nitrogen/generated/shared/c++/HybridEnnioSpec.hpp"
+
+#include <memory>
+#include <string>
+#include <vector>
+#include <functional>
+#include <mutex>
+
+// React Native Fabric headers
+#include <react/renderer/core/ShadowNode.h>
+#include <react/renderer/uimanager/UIManager.h>
+
+// JSI for runtime + dispatcher access
+#include <jsi/jsi.h>
+
+namespace margelo::nitro { class Dispatcher; }
+
+// Internal components
+#include "Protocol.hpp"
+#include "TestIDRegistry.hpp"
+#include "ShadowTreeTraverser.hpp"
+#include "SelectorCriteria.hpp"
+#include "SelectorParser.hpp"
+#include "ElementMatcher.hpp"
+
+namespace margelo::nitro::ennio {
+
+using ShadowNodePtr = std::shared_ptr<const facebook::react::ShadowNode>;
+using RuntimeExecutor = std::function<void(std::function<void(facebook::jsi::Runtime&)>&&)>;
+
+/**
+ * HybridEnnio - Main Nitro HybridObject for E2E testing
+ *
+ * Provides direct access to React Native's Fabric shadow tree
+ * for fast, reliable E2E testing without instrumentation.
+ */
+class HybridEnnio : public HybridEnnioSpec {
+public:
+    HybridEnnio();
+    ~HybridEnnio() override = default;
+
+    // ============================================
+    // Element Queries
+    // ============================================
+    bool exists(const std::string& testID) override;
+    bool isVisible(const std::string& testID) override;
+    std::variant<nitro::NullType, std::string> getText(const std::string& testID) override;
+
+    // ============================================
+    // Synchronization
+    // ============================================
+    bool waitForIdle(double timeoutMs) override;
+    void synchronize() override;
+
+    // Wake the moment React fires onCommitFiberRoot, capped at maxMs.
+    // Replaces blind sleep settles in the CLI with an early-wake; cap
+    // is the safety floor so the worst case is identical to a sleep.
+    bool waitForNextCommit(double maxMs) override;
+
+    // ============================================
+    // Selector-based Queries (Full Maestro Parity)
+    // ============================================
+    std::variant<nitro::NullType, ExtendedElementInfo> findBySelector(const std::string& selectorJson) override;
+    std::vector<ExtendedElementInfo> findAllBySelector(const std::string& selectorJson) override;
+    bool existsBySelector(const std::string& selectorJson) override;
+    std::variant<nitro::NullType, std::string> getTextBySelector(const std::string& selectorJson) override;
+    bool isVisibleBySelector(const std::string& selectorJson) override;
+
+    // ============================================
+    // Alert/Modal Handling
+    // ============================================
+    bool isAlertPresent() override;
+    std::string getAlertText() override;
+    std::vector<std::string> getAlertButtons() override;
+
+    // ============================================
+    // Fast-mode Writes
+    // ============================================
+    bool scroll(const std::string& testID, ScrollDirection direction, double distance) override;
+    bool scrollTo(const std::string& scrollViewTestID, const std::string& elementTestID) override;
+    bool swipeAtPoints(double x1, double y1, double x2, double y2, double durationMs) override;
+    bool pressHardwareKey(double keyCode) override;
+    bool backGesture() override;
+    bool hideKeyboard() override;
+    bool tapAlertButton(const std::string& buttonText) override;
+    bool dismissAlert() override;
+    bool copyToClipboard(const std::string& text) override;
+    bool pasteFromClipboard(const std::string& testID) override;
+
+    // ============================================
+    // Initialization (called from JS)
+    // ============================================
+
+    /**
+     * Initialize with UIManager reference for shadow tree access
+     * Must be called before using query/action methods
+     */
+    void initialize(
+        std::weak_ptr<facebook::react::UIManager> uiManager,
+        facebook::react::SurfaceId surfaceId
+    );
+
+    /**
+     * Check if the module is properly initialized
+     */
+    bool isInitialized() const;
+
+    /**
+     * JS-thread executor — wraps `RCTInstance.callFunctionOnBufferedRuntimeExecutor:`
+     * (or any equivalent scheduler) so background dispatch worker
+     * threads can schedule result-writes back onto JS. Stored once
+     * during bootstrap by `EnnioAutoInit`.
+     */
+    using JSThreadExecutor = std::function<void(std::function<void(facebook::jsi::Runtime&)>&&)>;
+    static void setJSThreadExecutor(JSThreadExecutor exec);
+
+    /**
+     * Pure-native bootstrap. Called from `EnnioAutoInit`'s post-start
+     * hook on the JS thread (after the runtime is initialised).
+     * Captures the runtime, evaluates the commit-signal walker, installs
+     * `__ennioDispatch` JSI host function so the external CLI can drive
+     * the runner via Hermes Inspector `Runtime.evaluate`. Idempotent.
+     */
+    static void nativeBootstrap(facebook::jsi::Runtime& runtime);
+
+
+private:
+    // Shadow tree access
+    std::weak_ptr<facebook::react::UIManager> uiManager_;
+    facebook::react::SurfaceId surfaceId_ = 0;
+    mutable std::mutex mutex_;
+
+    // Screen dimensions for visibility checks
+    float screenWidth_ = 0;
+    float screenHeight_ = 0;
+
+    /**
+     * Get the current shadow tree root for the surface
+     */
+    ShadowNodePtr getShadowTreeRoot() const;
+
+    /**
+     * Find a node by testID using registry or tree traversal
+     */
+    ShadowNodePtr findNode(const std::string& testID) const;
+
+    /**
+     * Run one request through the central command table. Same path is
+     * driven from JSI (`__ennioDispatch`) — the CLI hands us a Request
+     * over Hermes Inspector CDP and we hand back a Response.
+     */
+    ::ennio::Response handleCommand(const ::ennio::Request& request);
+
+    /**
+     * Convert internal LayoutMetrics to Nitro struct
+     */
+    LayoutMetrics convertLayoutMetrics(const ::ennio::LayoutMetrics& metrics) const;
+
+    /**
+     * Convert internal ExtendedElementInfo to Nitro struct
+     */
+    ExtendedElementInfo convertExtendedElementInfo(const ::ennio::ExtendedElementInfo& info) const;
+
+    /**
+     * Find a node by selector criteria
+     */
+    ShadowNodePtr findNodeBySelector(const ::ennio::SelectorCriteria& criteria) const;
+
+};
+
+} // namespace margelo::nitro::ennio

package/cpp/IdleMonitor.hpp

@@ -0,0 +1,277 @@
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <functional>
+#include <mutex>
+
+namespace ennio {
+
+/**
+ * IdleMonitor tracks pending work to determine when the UI is idle.
+ *
+ * It monitors:
+ * - Shadow tree commits/mounts
+ * - JS thread tasks
+ * - Network requests (optional)
+ *
+ * This is a singleton that can be accessed from anywhere in the app.
+ */
+class IdleMonitor {
+public:
+    static IdleMonitor& getInstance() {
+        static IdleMonitor instance;
+        return instance;
+    }
+
+    // Prevent copying
+    IdleMonitor(const IdleMonitor&) = delete;
+    IdleMonitor& operator=(const IdleMonitor&) = delete;
+
+    // ============================================
+    // Shadow Tree Tracking
+    // ============================================
+
+    /**
+     * Called when a shadow tree commit starts
+     */
+    void onShadowTreeCommitStart() {
+        pendingCommits_.fetch_add(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+    }
+
+    /**
+     * Called when a shadow tree commit completes
+     */
+    void onShadowTreeCommitEnd() {
+        pendingCommits_.fetch_sub(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+        checkAndNotify();
+    }
+
+    /**
+     * Called when a shadow tree mount starts
+     */
+    void onShadowTreeMountStart() {
+        pendingMounts_.fetch_add(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+    }
+
+    /**
+     * Called when a shadow tree mount completes
+     */
+    void onShadowTreeMountEnd() {
+        pendingMounts_.fetch_sub(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+        checkAndNotify();
+    }
+
+    // ============================================
+    // JS Thread Tracking
+    // ============================================
+
+    /**
+     * Called when a JS task starts
+     */
+    void onJSTaskStart() {
+        pendingJSTasks_.fetch_add(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+    }
+
+    /**
+     * Called when a JS task completes
+     */
+    void onJSTaskEnd() {
+        pendingJSTasks_.fetch_sub(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+        checkAndNotify();
+    }
+
+    // ============================================
+    // Network Request Tracking (optional)
+    // ============================================
+
+    /**
+     * Called when a network request starts
+     */
+    void onNetworkRequestStart() {
+        pendingNetworkRequests_.fetch_add(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+    }
+
+    /**
+     * Called when a network request completes
+     */
+    void onNetworkRequestEnd() {
+        pendingNetworkRequests_.fetch_sub(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+        checkAndNotify();
+    }
+
+    // ============================================
+    // Animation Tracking
+    // ============================================
+
+    /**
+     * Called when an animation starts
+     */
+    void onAnimationStart() {
+        pendingAnimations_.fetch_add(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+    }
+
+    /**
+     * Called when an animation completes
+     */
+    void onAnimationEnd() {
+        pendingAnimations_.fetch_sub(1);
+        lastActivityTime_ = std::chrono::steady_clock::now();
+        checkAndNotify();
+    }
+
+    // ============================================
+    // Status Queries
+    // ============================================
+
+    /**
+     * Check if the UI is currently idle
+     * Returns true if:
+     * - No pending commits or mounts
+     * - No pending JS tasks
+     * - (Optionally) No pending network requests
+     * - (Optionally) No pending animations
+     */
+    bool isIdle(bool includeNetwork = false, bool includeAnimations = false) const {
+        if (pendingCommits_.load() > 0) return false;
+        if (pendingMounts_.load() > 0) return false;
+        if (pendingJSTasks_.load() > 0) return false;
+        if (includeNetwork && pendingNetworkRequests_.load() > 0) return false;
+        if (includeAnimations && pendingAnimations_.load() > 0) return false;
+        return true;
+    }
+
+    /**
+     * Get the time since the last activity
+     */
+    std::chrono::milliseconds timeSinceLastActivity() const {
+        auto now = std::chrono::steady_clock::now();
+        return std::chrono::duration_cast<std::chrono::milliseconds>(
+            now - lastActivityTime_.load()
+        );
+    }
+
+    /**
+     * Wait for idle state with timeout
+     * @param timeoutMs Maximum time to wait in milliseconds
+     * @param includeNetwork Whether to wait for network requests
+     * @param includeAnimations Whether to wait for animations
+     * @param stabilityMs How long the system must be idle before returning
+     * @return true if idle state was reached, false on timeout
+     */
+    bool waitForIdle(
+        int timeoutMs,
+        bool includeNetwork = false,
+        bool includeAnimations = false,
+        int stabilityMs = 100
+    ) {
+        auto deadline = std::chrono::steady_clock::now() +
+            std::chrono::milliseconds(timeoutMs);
+
+        std::unique_lock<std::mutex> lock(mutex_);
+
+        while (std::chrono::steady_clock::now() < deadline) {
+            // Check if idle
+            if (isIdle(includeNetwork, includeAnimations)) {
+                // Check stability - has it been idle long enough?
+                auto idleTime = timeSinceLastActivity();
+                if (idleTime.count() >= stabilityMs) {
+                    return true;
+                }
+
+                // Wait for remaining stability time
+                auto remainingStability = std::chrono::milliseconds(stabilityMs) - idleTime;
+                cv_.wait_for(lock, remainingStability);
+            } else {
+                // Wait for notification or timeout
+                auto remaining = std::chrono::duration_cast<std::chrono::milliseconds>(
+                    deadline - std::chrono::steady_clock::now()
+                );
+                if (remaining.count() <= 0) {
+                    return false;
+                }
+                cv_.wait_for(lock, remaining);
+            }
+        }
+
+        return isIdle(includeNetwork, includeAnimations);
+    }
+
+    // ============================================
+    // Debug Information
+    // ============================================
+
+    /**
+     * Get current pending counts for debugging
+     */
+    struct PendingCounts {
+        int commits;
+        int mounts;
+        int jsTasks;
+        int networkRequests;
+        int animations;
+    };
+
+    PendingCounts getPendingCounts() const {
+        return {
+            pendingCommits_.load(),
+            pendingMounts_.load(),
+            pendingJSTasks_.load(),
+            pendingNetworkRequests_.load(),
+            pendingAnimations_.load()
+        };
+    }
+
+    /**
+     * Reset all counters (for testing)
+     */
+    void reset() {
+        pendingCommits_.store(0);
+        pendingMounts_.store(0);
+        pendingJSTasks_.store(0);
+        pendingNetworkRequests_.store(0);
+        pendingAnimations_.store(0);
+        lastActivityTime_.store(std::chrono::steady_clock::now());
+    }
+
+private:
+    IdleMonitor()
+        : pendingCommits_(0)
+        , pendingMounts_(0)
+        , pendingJSTasks_(0)
+        , pendingNetworkRequests_(0)
+        , pendingAnimations_(0)
+        , lastActivityTime_(std::chrono::steady_clock::now()) {}
+
+    void checkAndNotify() {
+        if (isIdle()) {
+            cv_.notify_all();
+        }
+    }
+
+    // Atomic counters for thread-safe tracking
+    std::atomic<int> pendingCommits_;
+    std::atomic<int> pendingMounts_;
+    std::atomic<int> pendingJSTasks_;
+    std::atomic<int> pendingNetworkRequests_;
+    std::atomic<int> pendingAnimations_;
+
+    // Last activity timestamp
+    std::atomic<std::chrono::steady_clock::time_point> lastActivityTime_;
+
+    // Mutex and condition variable for waiting
+    mutable std::mutex mutex_;
+    std::condition_variable cv_;
+};
+
+} // namespace ennio

package/cpp/Protocol.cpp

@@ -0,0 +1,135 @@
+#include "Protocol.hpp"
+
+#include <iomanip>
+#include <sstream>
+#include <string>
+
+namespace ennio {
+
+// Escape characters that would otherwise break the toJSON() string when
+// `id` or `error` carries an external value (request id, exception
+// message). Control chars get \uXXXX form, the rest match the strict
+// JSON escape set.
+static std::string jsonEscape(const std::string& str) {
+    std::string out;
+    out.reserve(str.size() + 8);
+    for (char c : str) {
+        switch (c) {
+            case '"':  out += "\\\""; break;
+            case '\\': out += "\\\\"; break;
+            case '\n': out += "\\n"; break;
+            case '\r': out += "\\r"; break;
+            case '\t': out += "\\t"; break;
+            default:
+                if (static_cast<unsigned char>(c) < 0x20) {
+                    char buf[8];
+                    snprintf(buf, sizeof(buf), "\\u%04x", static_cast<unsigned char>(c));
+                    out += buf;
+                } else {
+                    out += c;
+                }
+        }
+    }
+    return out;
+}
+
+namespace json {
+
+std::string stringify(const std::string& key, const std::string& value) {
+    return "\"" + key + "\":\"" + value + "\"";
+}
+
+std::string stringify(const std::string& key, bool value) {
+    return "\"" + key + "\":" + (value ? "true" : "false");
+}
+
+std::string stringify(const std::string& key, int value) {
+    return "\"" + key + "\":" + std::to_string(value);
+}
+
+std::string stringify(const std::string& key, double value) {
+    std::ostringstream oss;
+    oss << std::setprecision(10) << value;
+    return "\"" + key + "\":" + oss.str();
+}
+
+std::string parseString(const std::string& json, const std::string& key) {
+    std::string search = "\"" + key + "\":\"";
+    size_t pos = json.find(search);
+    if (pos == std::string::npos) {
+        return "";
+    }
+    pos += search.length();
+    std::string result;
+    bool escaped = false;
+    for (size_t i = pos; i < json.size(); i++) {
+        char c = json[i];
+        if (escaped) {
+            switch (c) {
+                case '"': result += '"'; break;
+                case '\\': result += '\\'; break;
+                case 'n': result += '\n'; break;
+                case 'r': result += '\r'; break;
+                case 't': result += '\t'; break;
+                default: result += c; break;
+            }
+            escaped = false;
+        } else if (c == '\\') {
+            escaped = true;
+        } else if (c == '"') {
+            break;
+        } else {
+            result += c;
+        }
+    }
+    return result;
+}
+
+bool parseBool(const std::string& json, const std::string& key) {
+    std::string search = "\"" + key + "\":";
+    size_t pos = json.find(search);
+    if (pos == std::string::npos) {
+        return false;
+    }
+    pos += search.length();
+    return json.substr(pos, 4) == "true";
+}
+
+int parseInt(const std::string& json, const std::string& key) {
+    std::string search = "\"" + key + "\":";
+    size_t pos = json.find(search);
+    if (pos == std::string::npos) {
+        return 0;
+    }
+    pos += search.length();
+    return std::stoi(json.substr(pos));
+}
+
+double parseDouble(const std::string& json, const std::string& key) {
+    std::string search = "\"" + key + "\":";
+    size_t pos = json.find(search);
+    if (pos == std::string::npos) {
+        return 0.0;
+    }
+    pos += search.length();
+    return std::stod(json.substr(pos));
+}
+
+} // namespace json
+
+std::string Response::toJSON() const {
+    std::ostringstream oss;
+    oss << "{";
+    oss << "\"id\":\"" << jsonEscape(id) << "\",";
+    oss << "\"success\":" << (success ? "true" : "false");
+    if (!data.empty()) {
+        oss << ",\"data\":" << data;
+    }
+    if (!error.empty()) {
+        oss << ",\"error\":\"" << jsonEscape(error) << "\"";
+    }
+    oss << "}";
+    return oss.str();
+}
+
+} // namespace ennio

package/cpp/Protocol.hpp

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <string>
+
+namespace ennio {
+
+// Request envelope. Built by the CLI side as a JSON-RPC payload, hands
+// off to HybridEnnio::handleCommand() inside a background dispatch
+// worker. `payload` is a JSON string (not parsed) — the handler does
+// its own type-specific extraction via cpp/json helpers.
+struct Request {
+    std::string id;
+    std::string type;
+    std::string payload;
+};
+
+// Response envelope. `data` is a pre-rendered JSON fragment (object,
+// array, bool, number, string literal — whatever the handler emits).
+// `Response::toJSON()` wraps it into the full reply object the CLI
+// expects: `{"id":..,"success":..,"data":..,"error":..}`.
+struct Response {
+    std::string id;
+    bool success;
+    std::string data;
+    std::string error;
+
+    std::string toJSON() const;
+};
+
+// Tiny, dependency-free JSON helpers. Used by the dispatch handlers to
+// peel typed values out of `Request.payload` (which is a JSON string,
+// not a parsed object). Loose enough to handle the CLI's serialiser
+// without pulling in a real JSON library; strict enough to break loudly
+// if the wire format drifts.
+namespace json {
+    std::string stringify(const std::string& key, const std::string& value);
+    std::string stringify(const std::string& key, bool value);
+    std::string stringify(const std::string& key, int value);
+    std::string stringify(const std::string& key, double value);
+
+    std::string parseString(const std::string& json, const std::string& key);
+    bool parseBool(const std::string& json, const std::string& key);
+    int parseInt(const std::string& json, const std::string& key);
+    double parseDouble(const std::string& json, const std::string& key);
+}
+
+} // namespace ennio