@reactiive/ennio 0.0.1

package/cpp/SelectorParser.hpp

@@ -0,0 +1,94 @@
+#pragma once
+
+#include "SelectorCriteria.hpp"
+#include <string>
+
+namespace ennio {
+
+/**
+ * SelectorParser - Parse JSON selector strings into SelectorCriteria
+ *
+ * Supports the full Maestro selector syntax:
+ * - Simple string: "my-test-id" -> id-only selector
+ * - Object: { "id": "btn", "text": "Submit", "enabled": true }
+ * - Nested: { "text": "OK", "below": { "id": "title" } }
+ */
+class SelectorParser {
+public:
+    /**
+     * Parse a JSON selector string into SelectorCriteria
+     *
+     * @param json - JSON string representing the selector
+     * @return Parsed SelectorCriteria
+     * @throws std::runtime_error if parsing fails
+     *
+     * Examples:
+     *   "my-test-id" -> { id: "my-test-id" }
+     *   { "text": "Login" } -> { text: { pattern: "Login", mode: Exact } }
+     *   { "text": ".*Login.*", "textMatchMode": "regex" } -> regex match
+     */
+    static SelectorCriteria parse(const std::string& json);
+
+    /**
+     * Serialize SelectorCriteria back to JSON string
+     */
+    static std::string toJSON(const SelectorCriteria& criteria);
+
+private:
+    /**
+     * Parse a JSON object into SelectorCriteria
+     */
+    static SelectorCriteria parseObject(const std::string& json);
+
+    /**
+     * Parse a nested selector (for spatial/hierarchical refs)
+     */
+    static SelectorCriteriaPtr parseNested(const std::string& json, const std::string& key);
+
+    /**
+     * Extract string value from JSON
+     */
+    static std::string extractString(const std::string& json, const std::string& key);
+
+    /**
+     * Extract boolean value from JSON
+     */
+    static std::optional<bool> extractBool(const std::string& json, const std::string& key);
+
+    /**
+     * Extract number value from JSON
+     */
+    static std::optional<double> extractNumber(const std::string& json, const std::string& key);
+
+    /**
+     * Extract nested object as JSON string
+     */
+    static std::string extractObject(const std::string& json, const std::string& key);
+
+    /**
+     * Extract array as vector of JSON strings
+     */
+    static std::vector<std::string> extractArray(const std::string& json, const std::string& key);
+
+    /**
+     * Check if key exists in JSON
+     */
+    static bool hasKey(const std::string& json, const std::string& key);
+
+    /**
+     * Parse TextMatchMode from string
+     */
+    static TextMatchMode parseTextMatchMode(const std::string& mode);
+
+    /**
+     * Parse Trait from string
+     */
+    static Trait parseTrait(const std::string& trait);
+
+    /**
+     * Parse Point from string or object
+     */
+    static Point parsePoint(const std::string& value);
+};
+
+} // namespace ennio

package/cpp/ShadowTreeTraverser.cpp

@@ -0,0 +1,305 @@
+#include "ShadowTreeTraverser.hpp"
+
+#include <react/renderer/components/view/ViewProps.h>
+#include <react/renderer/components/text/RawTextProps.h>
+#include <react/renderer/components/textinput/TextInputProps.h>
+#include <react/renderer/core/LayoutableShadowNode.h>
+
+namespace ennio {
+
+ShadowTreeTraverser::ShadowNodePtr ShadowTreeTraverser::findByTestID(
+    ShadowNodePtr root,
+    const std::string& testID
+) {
+    if (!root || testID.empty()) {
+        return nullptr;
+    }
+
+    // Check current node
+    auto nodeTestID = getTestID(*root);
+    if (nodeTestID && *nodeTestID == testID) {
+        return root;
+    }
+
+    // Recursively search children
+    for (const auto& child : root->getChildren()) {
+        auto result = findByTestID(child, testID);
+        if (result) {
+            return result;
+        }
+    }
+
+    return nullptr;
+}
+
+bool ShadowTreeTraverser::exists(ShadowNodePtr root, const std::string& testID) {
+    return findByTestID(root, testID) != nullptr;
+}
+
+std::optional<ElementInfo> ShadowTreeTraverser::getElementInfo(ShadowNodePtr node) {
+    if (!node) {
+        return std::nullopt;
+    }
+
+    ElementInfo info;
+
+    // Get testID
+    auto testID = getTestID(*node);
+    info.testID = testID.value_or("");
+
+    // Get component name/type
+    info.type = node->getComponentName();
+
+    // Get text content if available
+    info.text = getText(node);
+
+    // Default values
+    info.accessible = false;
+    info.enabled = true;
+
+    // Try to get ViewProps for accessibility info
+    auto viewProps = std::dynamic_pointer_cast<const facebook::react::ViewProps>(
+        node->getProps()
+    );
+
+    if (viewProps) {
+        info.accessible = viewProps->accessible;
+    }
+
+    // Get layout metrics
+    auto layoutable = dynamic_cast<const facebook::react::LayoutableShadowNode*>(node.get());
+    if (layoutable) {
+        auto metrics = layoutable->getLayoutMetrics();
+        info.layout.x = metrics.frame.origin.x;
+        info.layout.y = metrics.frame.origin.y;
+        info.layout.width = metrics.frame.size.width;
+        info.layout.height = metrics.frame.size.height;
+        info.layout.screenX = metrics.frame.origin.x;
+        info.layout.screenY = metrics.frame.origin.y;
+    }
+
+    return info;
+}
+
+std::optional<LayoutMetrics> ShadowTreeTraverser::getLayoutMetrics(
+    ShadowNodePtr root,
+    const std::string& testID
+) {
+    if (!root || testID.empty()) {
+        return std::nullopt;
+    }
+
+    std::vector<const facebook::react::ShadowNode*> path;
+    auto node = findByTestIDWithPath(root, testID, path);
+
+    if (!node) {
+        return std::nullopt;
+    }
+
+    auto layoutable = dynamic_cast<const facebook::react::LayoutableShadowNode*>(node.get());
+    if (!layoutable) {
+        return std::nullopt;
+    }
+
+    auto metrics = layoutable->getLayoutMetrics();
+    auto [offsetX, offsetY] = calculateAccumulatedOffset(path);
+
+    LayoutMetrics result;
+    result.x = metrics.frame.origin.x;
+    result.y = metrics.frame.origin.y;
+    result.width = metrics.frame.size.width;
+    result.height = metrics.frame.size.height;
+    result.screenX = metrics.frame.origin.x + offsetX;
+    result.screenY = metrics.frame.origin.y + offsetY;
+
+    return result;
+}
+
+bool ShadowTreeTraverser::isVisible(
+    ShadowNodePtr root,
+    const std::string& testID,
+    float screenWidth,
+    float screenHeight
+) {
+    auto metrics = getLayoutMetrics(root, testID);
+    if (!metrics) {
+        return false;
+    }
+
+    // Check if element is within screen bounds
+    if (metrics->screenX + metrics->width < 0 ||
+        metrics->screenY + metrics->height < 0 ||
+        metrics->screenX > screenWidth ||
+        metrics->screenY > screenHeight) {
+        return false;
+    }
+
+    // Check if element has valid size
+    if (metrics->width <= 0 || metrics->height <= 0) {
+        return false;
+    }
+
+    return true;
+}
+
+std::optional<std::string> ShadowTreeTraverser::getText(ShadowNodePtr node) {
+    if (!node) {
+        return std::nullopt;
+    }
+
+    // Check for RawText props
+    auto rawTextProps = std::dynamic_pointer_cast<const facebook::react::RawTextProps>(
+        node->getProps()
+    );
+
+    if (rawTextProps) {
+        return rawTextProps->text;
+    }
+
+    // TextInput: expose placeholder as the matchable text. Maestro flows
+    // commonly use `tapOn: text: "Email"` to focus a field whose only
+    // visible label is the placeholder, so without this we'd miss every
+    // form field.
+    auto textInputProps = std::dynamic_pointer_cast<const facebook::react::TextInputProps>(
+        node->getProps()
+    );
+    if (textInputProps) {
+        // Prefer the current value if set (matches typed-in text), else
+        // fall back to the placeholder hint shown when the field is empty.
+        if (!textInputProps->text.empty()) {
+            return textInputProps->text;
+        }
+        if (!textInputProps->placeholder.empty()) {
+            return textInputProps->placeholder;
+        }
+    }
+
+    // Only recurse for actual Text components (Fabric component name
+    // "Paragraph"). Recursing for arbitrary Views concatenates the entire
+    // subtree's text, which causes containers to falsely match short
+    // patterns like "1" — e.g. a screen-root View whose combined-text
+    // happens to include a price digit. Spatial selectors then evaluate
+    // those bogus matches against the wrong layout box.
+    const char* compName = node->getComponentName();
+    if (!compName) {
+        return std::nullopt;
+    }
+    std::string name(compName);
+    // Paragraph: top-level Fabric Text. Text: nested-inline Text inside
+    // another Text. Both should aggregate their RawText children. Other
+    // components (View, ScrollView, etc) must NOT recurse — otherwise a
+    // container's combined text causes false matches against descendants.
+    if (name != "Paragraph" && name != "Text") {
+        return std::nullopt;
+    }
+
+    std::string combinedText;
+    for (const auto& child : node->getChildren()) {
+        auto childText = getText(child);
+        if (childText) {
+            combinedText += *childText;
+        }
+    }
+
+    if (!combinedText.empty()) {
+        return combinedText;
+    }
+
+    return std::nullopt;
+}
+
+void ShadowTreeTraverser::traverse(
+    ShadowNodePtr root,
+    const VisitorCallback& visitor
+) {
+    if (!root) {
+        return;
+    }
+
+    traverseInternal(*root, visitor, 0);
+}
+
+std::optional<std::string> ShadowTreeTraverser::getTestID(
+    const facebook::react::ShadowNode& node
+) {
+    auto viewProps = std::dynamic_pointer_cast<const facebook::react::ViewProps>(
+        node.getProps()
+    );
+
+    if (viewProps && !viewProps->testId.empty()) {
+        return viewProps->testId;
+    }
+
+    return std::nullopt;
+}
+
+bool ShadowTreeTraverser::traverseInternal(
+    const facebook::react::ShadowNode& node,
+    const VisitorCallback& visitor,
+    int depth
+) {
+    // Visit current node
+    if (!visitor(node, depth)) {
+        return false; // Stop traversal
+    }
+
+    // Visit children
+    for (const auto& child : node.getChildren()) {
+        if (!traverseInternal(*child, visitor, depth + 1)) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+ShadowTreeTraverser::ShadowNodePtr ShadowTreeTraverser::findByTestIDWithPath(
+    ShadowNodePtr root,
+    const std::string& testID,
+    std::vector<const facebook::react::ShadowNode*>& path
+) {
+    if (!root) {
+        return nullptr;
+    }
+
+    // Check current node
+    auto nodeTestID = getTestID(*root);
+    if (nodeTestID && *nodeTestID == testID) {
+        return root;
+    }
+
+    // Add current node to path and search children
+    path.push_back(root.get());
+
+    for (const auto& child : root->getChildren()) {
+        auto result = findByTestIDWithPath(child, testID, path);
+        if (result) {
+            return result;
+        }
+    }
+
+    // Not found in this branch, remove from path
+    path.pop_back();
+
+    return nullptr;
+}
+
+std::pair<float, float> ShadowTreeTraverser::calculateAccumulatedOffset(
+    const std::vector<const facebook::react::ShadowNode*>& path
+) {
+    float offsetX = 0;
+    float offsetY = 0;
+
+    for (const auto* node : path) {
+        auto layoutable = dynamic_cast<const facebook::react::LayoutableShadowNode*>(node);
+        if (layoutable) {
+            auto metrics = layoutable->getLayoutMetrics();
+            offsetX += metrics.frame.origin.x;
+            offsetY += metrics.frame.origin.y;
+        }
+    }
+
+    return {offsetX, offsetY};
+}
+
+} // namespace ennio

package/cpp/ShadowTreeTraverser.hpp

@@ -0,0 +1,142 @@
+#pragma once
+
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+
+#include <react/renderer/core/ShadowNode.h>
+#include <react/renderer/core/LayoutMetrics.h>
+
+namespace ennio {
+
+/**
+ * Information about a found element
+ */
+struct ElementInfo {
+    std::string testID;
+    std::string type;
+    std::optional<std::string> text;
+    bool accessible;
+    bool enabled;
+
+    struct Layout {
+        float x;
+        float y;
+        float width;
+        float height;
+        float screenX;
+        float screenY;
+    } layout;
+};
+
+/**
+ * Layout metrics for an element
+ */
+struct LayoutMetrics {
+    float x;
+    float y;
+    float width;
+    float height;
+    float screenX;
+    float screenY;
+};
+
+/**
+ * ShadowTreeTraverser provides methods to query and traverse
+ * the React Native Fabric shadow tree.
+ */
+class ShadowTreeTraverser {
+public:
+    using ShadowNodePtr = std::shared_ptr<const facebook::react::ShadowNode>;
+    using VisitorCallback = std::function<bool(const facebook::react::ShadowNode&, int depth)>;
+
+    /**
+     * Find a ShadowNode by testID in the given tree
+     * @param root - Root of the shadow tree to search
+     * @param testID - The testID to search for
+     * @return Shared pointer to the node if found, nullptr otherwise
+     */
+    static ShadowNodePtr findByTestID(
+        ShadowNodePtr root,
+        const std::string& testID
+    );
+
+    /**
+     * Check if a node with the given testID exists
+     */
+    static bool exists(ShadowNodePtr root, const std::string& testID);
+
+    /**
+     * Get element information for a node
+     */
+    static std::optional<ElementInfo> getElementInfo(ShadowNodePtr node);
+
+    /**
+     * Get layout metrics for a node
+     * Calculates absolute screen position by traversing parent chain
+     */
+    static std::optional<LayoutMetrics> getLayoutMetrics(
+        ShadowNodePtr root,
+        const std::string& testID
+    );
+
+    /**
+     * Check if a node is visible on screen
+     * Considers: opacity, display, pointerEvents, parent chain, viewport bounds
+     */
+    static bool isVisible(
+        ShadowNodePtr root,
+        const std::string& testID,
+        float screenWidth,
+        float screenHeight
+    );
+
+    /**
+     * Get text content from a node (for Text components)
+     */
+    static std::optional<std::string> getText(ShadowNodePtr node);
+
+    /**
+     * Traverse the shadow tree depth-first
+     * @param root - Root node to start traversal
+     * @param visitor - Callback function, return false to stop traversal
+     */
+    static void traverse(
+        ShadowNodePtr root,
+        const VisitorCallback& visitor
+    );
+
+    /**
+     * Get the testID from a ShadowNode if available
+     */
+    static std::optional<std::string> getTestID(const facebook::react::ShadowNode& node);
+
+private:
+    /**
+     * Internal traversal helper with depth tracking
+     */
+    static bool traverseInternal(
+        const facebook::react::ShadowNode& node,
+        const VisitorCallback& visitor,
+        int depth
+    );
+
+    /**
+     * Find node and accumulate transforms for absolute positioning
+     */
+    static ShadowNodePtr findByTestIDWithPath(
+        ShadowNodePtr root,
+        const std::string& testID,
+        std::vector<const facebook::react::ShadowNode*>& path
+    );
+
+    /**
+     * Calculate accumulated offset from root to target
+     */
+    static std::pair<float, float> calculateAccumulatedOffset(
+        const std::vector<const facebook::react::ShadowNode*>& path
+    );
+};
+
+} // namespace ennio

package/cpp/TestIDRegistry.cpp

@@ -0,0 +1,109 @@
+#include "TestIDRegistry.hpp"
+
+#include <react/renderer/components/view/ViewProps.h>
+#include <react/renderer/core/LayoutableShadowNode.h>
+
+namespace ennio {
+
+TestIDRegistry& TestIDRegistry::getInstance() {
+    static TestIDRegistry instance;
+    return instance;
+}
+
+void TestIDRegistry::registerNode(const std::string& testID, ShadowNodePtr node) {
+    if (testID.empty() || !node) {
+        return;
+    }
+
+    std::lock_guard<std::mutex> lock(mutex_);
+    registry_[testID] = node;
+}
+
+void TestIDRegistry::unregisterNode(const std::string& testID) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    registry_.erase(testID);
+}
+
+TestIDRegistry::ShadowNodePtr TestIDRegistry::findByTestID(const std::string& testID) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    auto it = registry_.find(testID);
+    if (it == registry_.end()) {
+        return nullptr;
+    }
+
+    auto node = it->second.lock();
+    if (!node) {
+        // Expired entry. Evict so it doesn't pile up across renders
+        // between `updateFromTree` sweeps (`registry_` is mutable so
+        // const-correctness holds for callers).
+        registry_.erase(it);
+        return nullptr;
+    }
+
+    return node;
+}
+
+bool TestIDRegistry::exists(const std::string& testID) const {
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    auto it = registry_.find(testID);
+    if (it == registry_.end()) {
+        return false;
+    }
+
+    // Check if weak_ptr is still valid
+    return !it->second.expired();
+}
+
+void TestIDRegistry::clear() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    registry_.clear();
+}
+
+size_t TestIDRegistry::size() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+
+    // Count only non-expired entries
+    size_t count = 0;
+    for (const auto& pair : registry_) {
+        if (!pair.second.expired()) {
+            count++;
+        }
+    }
+    return count;
+}
+
+void TestIDRegistry::updateFromTree(ShadowNodePtr root) {
+    if (!root) {
+        return;
+    }
+
+    std::lock_guard<std::mutex> lock(mutex_);
+    registry_.clear();
+
+    traverseAndRegister(root);
+}
+
+void TestIDRegistry::traverseAndRegister(ShadowNodePtr node) {
+    if (!node) {
+        return;
+    }
+
+    // Try to get testID from ViewProps
+    auto viewProps = std::dynamic_pointer_cast<const facebook::react::ViewProps>(
+        node->getProps()
+    );
+
+    if (viewProps && !viewProps->testId.empty()) {
+        // Store the shared_ptr as weak_ptr for O(1) lookup
+        registry_[viewProps->testId] = node;
+    }
+
+    // Recursively traverse children (getChildren() returns shared_ptr)
+    for (const auto& child : node->getChildren()) {
+        traverseAndRegister(child);
+    }
+}
+
+} // namespace ennio